lauadminandClaude Opus 5.5
44fe648ebc
The prod overlay drops host ports for api/frontend and attaches frontend to the server's external `web` network (alias lux-fiscal-frontend), where NPM terminates TLS for asist.ystyle.com.ua. migrate/api/worker now share a single lux-fiscal-backend image instead of three identical copies. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
lux_fiscal
Веб-приложение для ручного пробития фискальных чеков по заказам: заказы из собственной CRM, статусы и сумма послеоплаты из Новой Пошты, фискализация через Checkbox.
Архитектура целиком описана в плане проекта; здесь — только то, что нужно для запуска.
Текущее состояние
| Этап | Что входит | Статус |
|---|---|---|
| 1 | Каркас: FastAPI, Postgres, Alembic, Docker, логи, health-check | ✅ готово |
| 2 | Аутентификация, роли, журнал аудита | ✅ готово |
| 3 | Заказы + заглушка CRM | ✅ готово |
| 4 | Нова Пошта: статусы и сумма послеоплаты | ✅ готово |
| 5 | Checkbox: ЕТТН-чеки по ТТН с контролем оплаты (план: .plans/checkbox-ettn-receipts.md) |
🚧 код готов, ждёт проверки на боевой кассе |
| 6 | Очередь и редактор чека (фронтенд) | ⏳ |
| 7 | Админка | ⏳ |
| 8 | Реальный API CRM | ⏳ |
| 9 | Продакшен-обвязка | ⏳ |
Требования
- Docker и Docker Compose — основной способ запуска
- Python 3.12+ — если хочется запускать бэкенд без контейнеров
Запуск
cp .env.example .env
Сгенерируйте оба ключа и впишите их в .env — со значениями-заглушками приложение не поднимется:
docker compose run --rm api python -m app.cli gen-keys
Поднимите стек (миграции накатятся автоматически отдельным контейнером migrate):
docker compose up -d --build
Создайте первого администратора из FIRST_ADMIN_* в .env:
docker compose run --rm api python -m app.cli bootstrap
API доступен на http://localhost:8000, интерактивная документация — на /docs (в продакшене отключена).
Проверка работоспособности
curl -s localhost:8000/api/v1/health/ready
Вход и запрос своего профиля:
curl -s -X POST localhost:8000/api/v1/auth/login -H 'Content-Type: application/json' -d '{"email":"admin@example.com","password":"<пароль>"}'
curl -s localhost:8000/api/v1/auth/me -H 'Authorization: Bearer <access_token>'
Разработка без Docker
Нужен доступный Postgres — схема использует JSONB и частичные уникальные индексы, поэтому SQLite не подойдёт.
cd backend && python -m venv .venv && .venv/Scripts/pip install -e ".[dev]"
Пропишите в .env POSTGRES_HOST=localhost, REDIS_HOST=localhost и запускайте:
cd backend && .venv/Scripts/alembic upgrade head
cd backend && .venv/Scripts/uvicorn app.main:app --reload
Тесты и линтер
cd backend && .venv/Scripts/python -m pytest -q
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.