mostovik-backend/README.md

Django ETL Boilerplate

Шаблон Django приложения для ETL (Extract, Transform, Load) операций с функциями веб-скрапинга.

Технологический стек

• Python: 3.11.2
• Django: 3.2.25
• Django REST Framework: 3.14.0
• PostgreSQL: 15.10
• Redis: 7.x
• Celery: 5.3.6
• Playwright: 1.52+ (browser automation)
• Gunicorn: 21.2.0
• Apache: 2.4.57

Парсеры данных

Проект включает парсеры для загрузки данных из государственных источников:

Минпромторг (minpromtorg.gov.ru)

• Сертификаты промышленного производства - parse_industrial_production
• Реестр производителей - parse_manufactures

Единый реестр проверок (proverki.gov.ru)

• Проверки по ФЗ-294 - традиционные проверки
• Проверки по ФЗ-248 - новые проверки с 2021 года
• Автоматическая синхронизация - sync_inspections

Запуск парсеров

# Через Celery
from apps.parsers.tasks import (
    parse_industrial_production,
    parse_manufactures,
    parse_inspections,
    sync_inspections,
)

# Парсинг сертификатов
parse_industrial_production.delay()

# Парсинг производителей
parse_manufactures.delay()

# Парсинг проверок за конкретный месяц
parse_inspections.delay(year=2025, month=10, is_federal_law_248=False)

# Автоматическая синхронизация (с 01.01.2025 до текущего месяца)
sync_inspections.delay()

Особенности парсера proverki.gov.ru

• Использует Playwright для JS-рендеринга
• Поддержка потокового парсинга для больших файлов (>50 МБ)
• Автоматическое определение последнего загруженного периода
• Раздельная загрузка ФЗ-294 и ФЗ-248

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

mostovik-backend/
├── src/                    # Исходный код Django
│   ├── apps/              # Django приложения
│   │   └── user/         # Приложение пользователей
│   ├── core/              # Runtime-конфигурация проекта (urls/asgi/wsgi/celery)
│   ├── settings/          # Django settings (base, dev, production, test)
│   └── manage.py         # Управление Django
├── tests/                  # Тесты (в корне проекта)
│   ├── apps/user/         # Тесты для user app
│   ├── conftest.py       # Конфигурация pytest
│   └── README.md         # Документация по тестам
├── docker/                # Docker конфигурации
├── pyproject.toml         # Конфигурация проекта и инструментов
├── Makefile              # Команды для разработки
├── docker-compose.dev.yml # Docker Compose для разработки
└── docker-compose.prod.yml # Docker Compose для production

Быстрый старт (локальная разработка)

1. Установка зависимостей

# Установка uv (если не установлен)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env

# Создание виртуального окружения с uv
uv venv .venv
source .venv/bin/activate

# Установка зависимостей через uv
uv pip install -e ".[dev]"

# Или через Makefile
make install

# Настройка окружения разработки (pre-commit hooks)
make setup-dev

2. Настройка окружения

# Для dev compose уже готов файл .env.dev (можно использовать как есть).
# Для prod compose заполните .env.prod на основе .env.prod.example.

3. Запуск с Docker Compose (рекомендуется)

# Запуск всех dev сервисов (db, redis, migrate, web, celery)
docker compose -f docker-compose.dev.yml up -d

# Проверка состояния контейнеров
docker compose -f docker-compose.dev.yml ps

# Просмотр логов
docker compose -f docker-compose.dev.yml logs -f web

4. Ручная настройка (без Docker)

Запуск баз данных:

# PostgreSQL
sudo systemctl start postgresql

# Redis
sudo systemctl start redis

Миграции и запуск:

cd src

# Миграции
python manage.py makemigrations
python manage.py migrate

# Создание суперпользователя
python manage.py createsuperuser

# Запуск разработческого сервера
python manage.py runserver

# Запуск Celery worker (в отдельном терминале)
celery -A core worker --loglevel=info

# Запуск Celery beat (в отдельном терминале)
celery -A core beat --loglevel=info

API Endpoints

Основной префикс: /api/

Data Processor

• GET/POST /api/data-sources/ - Источники данных
• GET/POST /api/data-pipelines/ - ETL пайплайны
• GET /api/extracted-data/ - Извлеченные данные
• GET /api/processing-logs/ - Логи обработки

Web Scraping

• GET/POST /api/scraping-jobs/ - Задачи скрапинга
• GET /api/scraped-items/ - Скрапленные данные
• GET/POST /api/spider-configurations/ - Конфигурации пауков
• GET/POST /api/proxy-servers/ - Прокси сервера

Аутентификация

• POST /api/api-token-auth/ - Получение API токена

Развертывание

Используется docker-compose.prod.yml и файл окружения .env.prod.

# 1) Заполнить .env.prod (можно взять шаблон .env.prod.example)

# 2) Собрать и запустить сервисы
docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --build

# 3) Проверить состояние
docker compose -f docker-compose.prod.yml --env-file .env.prod ps

Мониторинг и логирование

Логи приложения

# Логи Django
tail -f logs/django.log

# Логи Celery
tail -f logs/celery.log

# Системные логи
journalctl -u gunicorn -f
journalctl -u celery-worker -f

Мониторинг Celery

# Запуск Flower (в отдельном терминале)
celery -A core flower

# Доступ через браузер: http://localhost:5555

Разработка

Запуск тестов

# Запуск всех тестов
make test

# Запуск с покрытием
make test-cov

# Запуск только быстрых тестов
make test-fast

# Запуск тестов конкретного модуля
make test TARGET=user

# Линтинг и форматирование
make lint
make format

# Проверка типов
make type-check

# Проверка безопасности
make security-check

Создание миграций

# Через Makefile
make migrate

# Или напрямую
cd src
python manage.py makemigrations
python manage.py migrate

# Создание суперпользователя
make createsuperuser

Работа с задачами Celery

# В коде Python
from apps.data_processor.tasks import process_extracted_data
from apps.scraping.tasks import run_scraping_job

# Запуск асинхронно
result = process_extracted_data.delay()
print(result.id)  # ID задачи

Конфигурация инструментов

Все конфигурации инструментов разработки централизованы в файле pyproject.toml:

• pytest: настройки тестирования
• coverage: отчеты о покрытии кода
• ruff: линтинг и форматирование
• black: форматирование кода
• isort: сортировка импортов
• mypy: проверка типов
• bandit: проверка безопасности

Полезные команды Make

# Качество кода
make lint          # Проверка линтерами
make format        # Форматирование кода
make type-check    # Проверка типов
make security-check # Проверка безопасности
make pre-commit    # Запуск всех pre-commit hooks

# Тестирование
make test          # Все тесты
make test-cov      # Тесты с покрытием
make test-fast     # Только быстрые тесты

# Разработка
make shell         # Django shell
make migrate       # Миграции
make clean         # Очистка временных файлов

Безопасность

• Все секретные ключи хранятся в переменных окружения
• Используется HTTPS в продакшене
• Настроены заголовки безопасности в Apache
• Регулярное обновление зависимостей

Поддержка

Для вопросов и поддержки обращайтесь к документации Django и используемым библиотекам:

• Django Documentation
• Celery Documentation
• Scrapy Documentation
• Django REST Framework

Лицензия

MIT License

---

Changelog

2026-01-21

Добавлено

• Задача sync_inspections - автоматическая синхронизация проверок с proverki.gov.ru
  • Инкрементальная загрузка с последнего сохранённого периода
  • Начало с 01.01.2025 если БД пуста
  • Раздельная загрузка ФЗ-294 и ФЗ-248
  • Автоматическая остановка при отсутствии данных (2 пустых месяца)
• Поля в модели InspectionRecord:
  • is_federal_law_248 - признак проверки по ФЗ-248
  • data_year - год загруженных данных
  • data_month - месяц загруженных данных
• Потоковый парсинг XML для файлов >50 МБ (iterparse)
• Методы в InspectionService:
  • get_last_loaded_period() - получение последнего загруженного периода
  • has_data_for_period() - проверка наличия данных за период

2026-01-20

Добавлено

• Парсер proverki.gov.ru с поддержкой Playwright
• Навигация по порталу (клик на вкладку "Скачать")
• Парсинг XML с namespaces
• Извлечение данных из атрибутов и вложенных элементов

2026-01-19

Добавлено

• Парсеры Минпромторга (сертификаты, производители)
• Модуль apps.parsers с клиентами, сервисами и задачами Celery
• Django Admin для управления записями парсеров
• Дедупликация по unique constraints