lauadminandClaude Opus 5.5
518a99197f
Cashier creates an ETTN receipt in Checkbox bound to the TTN with payment control; Checkbox fiscalizes it itself when the parcel is paid for. - cash_registers (Fernet-encrypted license key / PIN) and receipts tables - Checkbox HTTP client + stub (ETTN does not work on test registers) - two-phase create via ARQ job, timeout reconciliation, cron status polling - /receipts and /cash-registers API, audit records - dashboard: per-order and bulk create, prepayment, cancel; cash registers page Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
102 lines
4.2 KiB
Markdown
102 lines
4.2 KiB
Markdown
# lux_fiscal
|
|
|
|
Веб-приложение для ручного пробития фискальных чеков по заказам: заказы из собственной CRM, статусы и сумма послеоплаты из Новой Пошты, фискализация через [Checkbox](https://checkbox.ua).
|
|
|
|
Архитектура целиком описана в плане проекта; здесь — только то, что нужно для запуска.
|
|
|
|
## Текущее состояние
|
|
|
|
| Этап | Что входит | Статус |
|
|
|---|---|---|
|
|
| 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+ — если хочется запускать бэкенд без контейнеров
|
|
|
|
## Запуск
|
|
|
|
```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`.
|