Initial commit: backend scaffold, auth, frontend login

- FastAPI + SQLAlchemy async + Alembic + Postgres backend - Auth: JWT access + rotating refresh tokens, argon2, roles, audit log - React 19 + Vite frontend: login page, protected route, auth context - Docker Compose: postgres, redis, migrate, api, worker (placeholder), frontend/nginx Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-22 15:07:15 +03:00
commit 2664cb8213
71 changed files with 4999 additions and 0 deletions
@@ -0,0 +1,101 @@
+# 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`.