# 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/`

## Тесты

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

```bash
./scripts/run-tests.sh
```

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

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

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

```bash
make test-prod
```

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

```bash
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)

```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
```