# lux_fiscal

Веб-приложение для ручного пробития фискальных чеков по заказам: заказы из собственной CRM, статусы и сумма послеоплаты из Новой Пошты, фискализация через [Checkbox](https://checkbox.ua).

Архитектура целиком описана в плане проекта; здесь — только то, что нужно для запуска.

## Текущее состояние

| Этап | Что входит | Статус |
|---|---|---|
| 1 | Каркас: FastAPI, Postgres, Alembic, Docker, логи, health-check | ✅ готово |
| 2 | Аутентификация, роли, журнал аудита | ✅ готово |
| 3 | Заказы + заглушка CRM | ⏳ |
| 4 | Нова Пошта: статусы и сумма послеоплаты | ⏳ |
| 5 | Checkbox: смены, чеки, PDF | ⏳ |
| 6 | Очередь и редактор чека (фронтенд) | ⏳ |
| 7 | Админка | ⏳ |
| 8 | Реальный API CRM | ⏳ |
| 9 | Продакшен-обвязка | ⏳ |

## Требования

- Docker и Docker Compose — основной способ запуска
- Python 3.12+ — если хочется запускать бэкенд без контейнеров

## Запуск

```bash
cp .env.example .env
```

Сгенерируйте оба ключа и впишите их в `.env` — со значениями-заглушками приложение не поднимется:

```bash
docker compose run --rm api python -m app.cli gen-keys
```

Поднимите стек (миграции накатятся автоматически отдельным контейнером `migrate`):

```bash
docker compose up -d --build
```

Создайте первого администратора из `FIRST_ADMIN_*` в `.env`:

```bash
docker compose run --rm api python -m app.cli bootstrap
```

API доступен на `http://localhost:8000`, интерактивная документация — на `/docs` (в продакшене отключена).

## Проверка работоспособности

```bash
curl -s localhost:8000/api/v1/health/ready
```

Вход и запрос своего профиля:

```bash
curl -s -X POST localhost:8000/api/v1/auth/login -H 'Content-Type: application/json' -d '{"email":"admin@example.com","password":"<пароль>"}'
```

```bash
curl -s localhost:8000/api/v1/auth/me -H 'Authorization: Bearer <access_token>'
```

## Разработка без Docker

Нужен доступный Postgres — схема использует `JSONB` и частичные уникальные индексы, поэтому SQLite не подойдёт.

```bash
cd backend && python -m venv .venv && .venv/Scripts/pip install -e ".[dev]"
```

Пропишите в `.env` `POSTGRES_HOST=localhost`, `REDIS_HOST=localhost` и запускайте:

```bash
cd backend && .venv/Scripts/alembic upgrade head
```

```bash
cd backend && .venv/Scripts/uvicorn app.main:app --reload
```

## Тесты и линтер

```bash
cd backend && .venv/Scripts/python -m pytest -q
```

```bash
cd backend && .venv/Scripts/python -m ruff check app tests
```

## Безопасность

- `SECRET_KEY` подписывает JWT, `ENCRYPTION_KEY` шифрует ключи касс Checkbox в БД. Оба обязательны и оба должны быть настоящими.
- **Смена `ENCRYPTION_KEY` делает ранее сохранённые ключи касс нечитаемыми** — их придётся ввести заново через админку. Ключ стоит забэкапить отдельно от дампа БД.
- Postgres и Redis не публикуют порты наружу; `api` слушает только `127.0.0.1` — наружу его выставляет nginx с TLS.
- После первого входа смените пароль администратора и удалите `FIRST_ADMIN_PASSWORD` из `.env`.