Aleksandr Meshchriakov
ff7884ebe9
- Полностью обновлена документация проекта под текущую архитектуру - Добавлены исчерпывающие инструкции локального запуска: Docker и без Docker - Уточнены реальные API эндпоинты, задачи Celery, переменные окружения и prod/dev сценарии - Удалены вспомогательные временные файлы: concatenate_files.py и один_файл.docx
278 lines
8.2 KiB
Markdown
278 lines
8.2 KiB
Markdown
# Mostovik Backend
|
||
|
||
Backend-сервис на Django/DRF для сбора, хранения и выдачи данных из государственных источников (Минпромторг, ЕРП, ЕИС закупок, ФНС), с асинхронной обработкой через Celery.
|
||
|
||
## Что умеет проект
|
||
|
||
- JWT-аутентификация и профиль пользователя.
|
||
- Swagger UI документация API.
|
||
- Health/Liveness/Readiness эндпоинты.
|
||
- Фоновые задачи с трекингом статуса (`BackgroundJob`).
|
||
- Парсеры источников:
|
||
- Минпромторг: сертификаты и реестр производителей.
|
||
- Единый реестр проверок (`proverki.gov.ru`, включая 248-ФЗ/294-ФЗ).
|
||
- Закупки (`zakupki.gov.ru`, SOAP API с токеном).
|
||
- ФНС: загрузка и обработка Excel-отчётности (`fin_{id}_{ogrn}.xlsx`).
|
||
- Админ-панель на Jazzmin для мониторинга данных и логов загрузок.
|
||
|
||
## Технологии
|
||
|
||
- Python 3.11
|
||
- Django 3.2
|
||
- Django REST Framework
|
||
- PostgreSQL 15
|
||
- Redis 7
|
||
- Celery + django-celery-beat + django-celery-results
|
||
- drf-yasg (Swagger/OpenAPI)
|
||
- uv (управление зависимостями)
|
||
- Docker / Docker Compose
|
||
|
||
## Структура проекта
|
||
|
||
```text
|
||
.
|
||
├── src/
|
||
│ ├── apps/
|
||
│ │ ├── core/ # health, background jobs, openapi, startup checks
|
||
│ │ ├── user/ # auth, профиль пользователя
|
||
│ │ └── parsers/ # клиенты/сервисы/задачи парсеров
|
||
│ ├── core/ # urls/asgi/wsgi/celery
|
||
│ ├── settings/ # base/dev/production/test
|
||
│ └── manage.py
|
||
├── tests/
|
||
├── docker/
|
||
│ ├── Dockerfile
|
||
│ └── scripts/
|
||
├── input/ # входящие/обработанные/ошибочные файлы ФНС
|
||
├── docker-compose.dev.yml
|
||
├── docker-compose.prod.yml
|
||
└── Makefile
|
||
```
|
||
|
||
## Переменные окружения
|
||
|
||
Ключевые переменные:
|
||
|
||
- `DJANGO_SETTINGS_MODULE`: `settings.dev` (локально/dev) или `settings.production` (prod).
|
||
- `POSTGRES_*`: доступ к PostgreSQL.
|
||
- `REDIS_CACHE_URL`, `CELERY_BROKER_URL`, `CELERY_RESULT_BACKEND`: Redis/Celery.
|
||
- `CHECKO_API_KEY`: ключ API Checko.
|
||
- `ZAKUPKI_TOKEN`: токен SOAP API ЕИС закупок.
|
||
- `COLLECTSTATIC_ON_MIGRATE`: `1`/`0`.
|
||
- `STARTUP_CHECKS_ENABLED`: fail-fast проверки DB/Redis перед стартом runtime-процессов.
|
||
|
||
Важно: если используете `.env.dev`/`.env.prod`, проверьте, что `DJANGO_SETTINGS_MODULE` указывает на `settings.*`, а не на устаревший `config.settings.*`.
|
||
|
||
## Локальный запуск в Docker (рекомендуется)
|
||
|
||
### 1. Подготовка
|
||
|
||
```bash
|
||
# из корня проекта
|
||
cp .env.prod.example .env.prod # только если нужен prod compose
|
||
```
|
||
|
||
Для dev используется `.env.dev`. При необходимости поправьте:
|
||
|
||
```env
|
||
DJANGO_SETTINGS_MODULE=settings.dev
|
||
```
|
||
|
||
### 2. Старт dev-стека
|
||
|
||
```bash
|
||
make dev-up
|
||
# или:
|
||
docker compose -f docker-compose.dev.yml up -d
|
||
```
|
||
|
||
Сервисы:
|
||
|
||
- `db` (PostgreSQL)
|
||
- `redis`
|
||
- `migrate` (однократный запуск миграций)
|
||
- `web` (Django runserver)
|
||
- `celery_worker`
|
||
- `celery_beat`
|
||
|
||
### 3. Проверка
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml ps
|
||
docker compose -f docker-compose.dev.yml logs -f web
|
||
```
|
||
|
||
### 4. Остановка
|
||
|
||
```bash
|
||
make dev-down
|
||
```
|
||
|
||
## Локальный запуск без Docker
|
||
|
||
Вариант для разработки на хосте.
|
||
|
||
### 1. Зависимости
|
||
|
||
```bash
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||
source "$HOME/.cargo/env"
|
||
uv sync --dev
|
||
```
|
||
|
||
### 2. Поднять PostgreSQL и Redis
|
||
|
||
Любым удобным способом (локально через сервисы или контейнеры). Пример с Docker:
|
||
|
||
```bash
|
||
docker run -d --name mostovik_pg \
|
||
-e POSTGRES_DB=mostovik \
|
||
-e POSTGRES_USER=postgres \
|
||
-e POSTGRES_PASSWORD=postgres \
|
||
-p 5432:5432 postgres:15.10
|
||
|
||
docker run -d --name mostovik_redis -p 6379:6379 redis:7-alpine
|
||
```
|
||
|
||
### 3. Экспорт переменных
|
||
|
||
```bash
|
||
export DJANGO_SETTINGS_MODULE=settings.dev
|
||
export POSTGRES_HOST=127.0.0.1
|
||
export POSTGRES_PORT=5432
|
||
export POSTGRES_DB=mostovik
|
||
export POSTGRES_USER=postgres
|
||
export POSTGRES_PASSWORD=postgres
|
||
export REDIS_HOST=127.0.0.1
|
||
export REDIS_CACHE_URL=redis://127.0.0.1:6379/1
|
||
export CELERY_BROKER_URL=redis://127.0.0.1:6379/0
|
||
export CELERY_RESULT_BACKEND=redis://127.0.0.1:6379/0
|
||
```
|
||
|
||
### 4. Миграции и запуск
|
||
|
||
```bash
|
||
cd src
|
||
uv run python manage.py migrate
|
||
uv run python manage.py createsuperuser
|
||
uv run python manage.py runserver
|
||
```
|
||
|
||
В отдельных терминалах:
|
||
|
||
```bash
|
||
cd src && DJANGO_SETTINGS_MODULE=settings.dev uv run celery -A core worker --loglevel=INFO
|
||
cd src && DJANGO_SETTINGS_MODULE=settings.dev uv run celery -A core beat --loglevel=INFO
|
||
```
|
||
|
||
Опционально для `proverki.gov.ru` fallback-режима:
|
||
|
||
```bash
|
||
uv run playwright install chromium
|
||
```
|
||
|
||
## API и доступные эндпоинты
|
||
|
||
Базовый URL в dev: `http://localhost:8000`
|
||
|
||
- Swagger UI: `GET /`
|
||
- Admin: `GET /admin/`
|
||
- Health: `GET /health/`, `GET /health/live/`, `GET /health/ready/`
|
||
|
||
Версионированный API: `/api/v1/`
|
||
|
||
- Пользователи и auth: `/api/v1/users/`
|
||
- Фоновые задачи: `/api/v1/jobs/`
|
||
- Минпромторг: `/api/v1/minpromtorg/`
|
||
- Проверки: `/api/v1/proverki/`
|
||
- Закупки: `/api/v1/zakupki/`
|
||
- ФНС: `/api/v1/fns/`
|
||
- Системные (admin): `/api/v1/system/`
|
||
|
||
Основные auth-эндпоинты:
|
||
|
||
- `POST /api/v1/users/register/`
|
||
- `POST /api/v1/users/login/`
|
||
- `POST /api/v1/users/token/refresh/`
|
||
- `POST /api/v1/users/token/verify/`
|
||
- `GET /api/v1/users/me/`
|
||
|
||
ФНС загрузка:
|
||
|
||
- `POST /api/v1/fns/upload/` (`multipart/form-data`, поле `files`)
|
||
- `GET /api/v1/fns/reports/`
|
||
- `GET /api/v1/fns/reports/{id}/`
|
||
|
||
## Парсеры и фоновые задачи
|
||
|
||
Celery-задачи (основные):
|
||
|
||
- `apps.parsers.tasks.parse_industrial_production`
|
||
- `apps.parsers.tasks.parse_manufactures`
|
||
- `apps.parsers.tasks.parse_inspections`
|
||
- `apps.parsers.tasks.sync_inspections`
|
||
- `apps.parsers.tasks.parse_procurements`
|
||
- `apps.parsers.tasks.sync_procurements`
|
||
- `apps.parsers.tasks.process_fns_file`
|
||
- `apps.parsers.tasks.scan_fns_directory`
|
||
|
||
Планировщик (`celery beat`) по умолчанию:
|
||
|
||
- ежедневный парсинг Минпромторга (сертификаты/производители)
|
||
- сканирование директории ФНС каждые 5 минут
|
||
|
||
Директории ФНС:
|
||
|
||
- входящие: `input/fns/`
|
||
- успешные: `input/fns/processed/`
|
||
- ошибки: `input/fns/failed/`
|
||
|
||
## Команды разработки
|
||
|
||
```bash
|
||
make install
|
||
make setup-dev
|
||
make test
|
||
make test-cov
|
||
make test-fast
|
||
make lint
|
||
make pre-commit
|
||
make pre-push
|
||
make migrate
|
||
make createsuperuser
|
||
make shell
|
||
```
|
||
|
||
## Production (docker-compose.prod.yml)
|
||
|
||
```bash
|
||
cp .env.prod.example .env.prod
|
||
# обязательно проверить:
|
||
# DJANGO_SETTINGS_MODULE=settings.production
|
||
|
||
docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --build
|
||
docker compose -f docker-compose.prod.yml --env-file .env.prod ps
|
||
```
|
||
|
||
В prod compose поднимаются:
|
||
|
||
- `migrate`
|
||
- `web` (gunicorn)
|
||
- `celery_worker`
|
||
- `celery_beat`
|
||
|
||
БД/Redis в prod compose не создаются, предполагаются внешние сервисы.
|
||
|
||
## Наблюдаемость и диагностика
|
||
|
||
- Health-checkи для оркестрации: `/health/live/`, `/health/ready/`, `/health/`.
|
||
- Расширенный health: `GET /health/?include_celery=true`.
|
||
- Логи контейнеров:
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml logs -f web
|
||
docker compose -f docker-compose.dev.yml logs -f celery_worker
|
||
docker compose -f docker-compose.dev.yml logs -f celery_beat
|
||
```
|
||
|