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

Структура проекта

.
├── 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. Подготовка

# из корня проекта
cp .env.prod.example .env.prod  # только если нужен prod compose

Для dev используется .env.dev. При необходимости поправьте:

DJANGO_SETTINGS_MODULE=settings.dev

2. Старт dev-стека

make dev-up
# или:
docker compose -f docker-compose.dev.yml up -d

Сервисы:

• db (PostgreSQL)
• redis
• migrate (однократный запуск миграций)
• web (Django runserver)
• celery_worker
• celery_beat

3. Проверка

docker compose -f docker-compose.dev.yml ps
docker compose -f docker-compose.dev.yml logs -f web

4. Остановка

make dev-down

Локальный запуск без Docker

Вариант для разработки на хосте.

1. Зависимости

curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.cargo/env"
uv sync --dev

2. Поднять PostgreSQL и Redis

Любым удобным способом (локально через сервисы или контейнеры). Пример с Docker:

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. Экспорт переменных

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. Миграции и запуск

cd src
uv run python manage.py migrate
uv run python manage.py createsuperuser
uv run python manage.py runserver

В отдельных терминалах:

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-режима:

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) по умолчанию:

• weekly-обновление источников Минпромторга и проверок
• сканирование директории ФНС каждые 5 минут

При старте celery worker также выполняется одноразовый автозапуск apps.parsers.tasks.parse_all_sources (с lock через cache, чтобы избежать дублей).

Директории ФНС:

• входящие: input/fns/
• успешные: input/fns/processed/
• ошибки: input/fns/failed/

Тесты

• Все тесты проекта хранятся только в ROOT_DIR/tests.
• Размещение тестов внутри src/**/tests не используется.
• Базовый запуск всех тестов:

./scripts/run-tests.sh

• Запуск отдельных тестов через скрипт (с путями относительно src/):

./scripts/run-tests.sh ../tests/apps/parsers/test_tasks.py

• Прогон в режиме, близком к production (PostgreSQL + миграции):

make test-prod

Команды разработки

make install
make setup-dev
make test
make test-prod
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)

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.
• Логи контейнеров:

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