Aleksandr Meshchriakov
d5d184537f
- Перенесена структура Django-конфига в src/core и src/settings - Унифицирована Docker-сборка и docker-compose для dev/prod - Добавлены startup-checks (DB/Redis) и обновлены env-шаблоны - Расширена OpenAPI-документация и ответы API - Удалены устаревшие deploy/requirements/служебные скрипты - Обновлены CI/CD, README и тесты
350 lines
12 KiB
Markdown
350 lines
12 KiB
Markdown
# 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`
|
||
|
||
### Запуск парсеров
|
||
|
||
```python
|
||
# Через 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. Установка зависимостей
|
||
|
||
```bash
|
||
# Установка 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. Настройка окружения
|
||
|
||
```bash
|
||
# Для dev compose уже готов файл .env.dev (можно использовать как есть).
|
||
# Для prod compose заполните .env.prod на основе .env.prod.example.
|
||
```
|
||
|
||
### 3. Запуск с Docker Compose (рекомендуется)
|
||
|
||
```bash
|
||
# Запуск всех 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)
|
||
|
||
#### Запуск баз данных:
|
||
```bash
|
||
# PostgreSQL
|
||
sudo systemctl start postgresql
|
||
|
||
# Redis
|
||
sudo systemctl start redis
|
||
```
|
||
|
||
#### Миграции и запуск:
|
||
```bash
|
||
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`.
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
## Мониторинг и логирование
|
||
|
||
### Логи приложения
|
||
```bash
|
||
# Логи Django
|
||
tail -f logs/django.log
|
||
|
||
# Логи Celery
|
||
tail -f logs/celery.log
|
||
|
||
# Системные логи
|
||
journalctl -u gunicorn -f
|
||
journalctl -u celery-worker -f
|
||
```
|
||
|
||
### Мониторинг Celery
|
||
```bash
|
||
# Запуск Flower (в отдельном терминале)
|
||
celery -A core flower
|
||
|
||
# Доступ через браузер: http://localhost:5555
|
||
```
|
||
|
||
## Разработка
|
||
|
||
### Запуск тестов
|
||
```bash
|
||
# Запуск всех тестов
|
||
make test
|
||
|
||
# Запуск с покрытием
|
||
make test-cov
|
||
|
||
# Запуск только быстрых тестов
|
||
make test-fast
|
||
|
||
# Запуск тестов конкретного модуля
|
||
make test TARGET=user
|
||
|
||
# Линтинг и форматирование
|
||
make lint
|
||
make format
|
||
|
||
# Проверка типов
|
||
make type-check
|
||
|
||
# Проверка безопасности
|
||
make security-check
|
||
```
|
||
|
||
### Создание миграций
|
||
```bash
|
||
# Через Makefile
|
||
make migrate
|
||
|
||
# Или напрямую
|
||
cd src
|
||
python manage.py makemigrations
|
||
python manage.py migrate
|
||
|
||
# Создание суперпользователя
|
||
make createsuperuser
|
||
```
|
||
|
||
### Работа с задачами Celery
|
||
```python
|
||
# В коде 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
|
||
|
||
```bash
|
||
# Качество кода
|
||
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](https://docs.djangoproject.com/)
|
||
- [Celery Documentation](https://docs.celeryproject.org/)
|
||
- [Scrapy Documentation](https://docs.scrapy.org/)
|
||
- [Django REST Framework](https://www.django-rest-framework.org/)
|
||
|
||
## Лицензия
|
||
|
||
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
|