mostovik-backend/docs/TECHNICAL_SPECIFICATION.md

# ТЕХНИЧЕСКАЯ СПЕЦИФИКАЦИЯ
## Система ETL MOSTOVIK

Версия документа: 1.0
Дата: 2026-01-21

---

## 1. НАЗНАЧЕНИЕ ПРОГРАММЫ

### 1.1. Общее назначение

Система MOSTOVIK представляет собой ETL-платформу (Extract, Transform, Load) для автоматизированного сбора, обработки и хранения данных из государственных информационных систем и реестров.

### 1.2. Функциональное назначение

Программа предназначена для решения следующих задач:

- **Автоматический сбор данных** из государственных источников:
  - Минпромторг России (minpromtorg.gov.ru) — сертификаты промышленного производства, реестр производителей
  - Единый реестр проверок (proverki.gov.ru) — данные о проверках юридических лиц и ИП
  - Федеральная налоговая служба (ФНС) — бухгалтерская отчётность организаций

- **Обработка и трансформация данных**:
  - Парсинг структурированных и неструктурированных данных
  - Нормализация форматов данных
  - Дедупликация записей
  - Валидация целостности данных

- **Хранение и предоставление доступа**:
  - Централизованное хранение собранных данных
  - Предоставление данных через REST API
  - Ведение журнала загрузок и аудита

- **Автоматизация процессов**:
  - Планирование периодических задач сбора данных
  - Мониторинг выполнения задач
  - Обработка ошибок и повторные попытки

### 1.3. Ограничения, накладываемые на область применения программы

#### 1.3.1. Правовые ограничения

Программа должна применяться в соответствии с требованиями:

- Федерального закона от 27.07.2006 № 149-ФЗ «Об информации, информационных технологиях и о защите информации»
- Федерального закона от 27.07.2006 № 152-ФЗ «О персональных данных»
- Положений об использовании данных государственных информационных систем
- Лицензионных соглашений источников данных

#### 1.3.2. Технические ограничения

- **Частота обращения к источникам**: не чаще одного раза в сутки для каждого источника (согласно настройкам Celery beat)
- **Объём обрабатываемых данных**: ограничен доступными системными ресурсами (ОЗУ, дисковое пространство)
- **Время отклика источников**: зависит от доступности внешних API и веб-ресурсов
- **Поддерживаемые форматы файлов**:
  - Excel (.xlsx) — для отчётов ФНС
  - JSON — для API-ответов
  - HTML — для веб-парсинга

#### 1.3.3. Эксплуатационные ограничения

- Требуется стабильное подключение к сети Интернет для доступа к внешним источникам
- Работа с некоторыми источниками возможна только через браузерную автоматизацию (Playwright), что увеличивает требования к ресурсам
- Не допускается одновременная работа нескольких экземпляров системы с одной базой данных без дополнительной настройки

#### 1.3.4. Область неприменимости

Программа не предназначена для:

- Обработки данных в реальном времени
- Работы с классифицированной информацией
- Использования в качестве единственного источника истины для критически важных систем
- Замены официальных запросов в государственные органы

---

## 2. УСЛОВИЯ ПРИМЕНЕНИЯ

### 2.1. Требования к необходимым для данной программы другим программам

#### 2.1.1. Операционная система

| Параметр | Минимальные требования | Рекомендуемые требования |
|----------|----------------------|-------------------------|
| ОС | Ubuntu 20.04 / Astra Linux Common Edition | Astra Linux Special Edition 1.7 |
| Ядро Linux | 5.4+ | 5.15+ |

#### 2.1.2. Системное программное обеспечение

| Компонент | Версия | Назначение |
|-----------|--------|------------|
| Python | 3.11 | Язык программирования |
| PostgreSQL | 15.10 | Система управления БД |
| Redis | 7.x | Кеш и брокер сообщений |
| Apache | 2.4.57 | Веб-сервер (HTTPS termination) |
| Gunicorn | 21.2.0 | WSGI-сервер для Django |
| Playwright | 1.57.0+ | Автоматизация браузера |

#### 2.1.3. Библиотеки Python (основные)

| Библиотека | Версия | Назначение |
|------------|--------|------------|
| Django | 3.2.25 | Веб-фреймворк |
| Django REST Framework | 3.14.0 | REST API |
| Celery | 5.3.6 | Очередь задач |
| requests | 2.31.0 | HTTP-запросы |
| pandas | 2.0.3 | Обработка табличных данных |
| openpyxl | 3.1.5+ | Чтение Excel |
| python-docx | 1.2.0+ | Чтение Word |
| BeautifulSoup4 | 4.12.3 | Парсинг HTML |
| Scrapy | 2.11.2 | Веб-скрапинг |
| Selenium | 4.17.2 | Автоматизация браузера |

#### 2.1.4. Дополнительные компоненты

- **libpq-dev** — клиентская библиотека PostgreSQL
- **libffi-dev** — Foreign Function Interface
- **libxml2-dev, libxslt1-dev** — библиотеки для работы с XML
- **zlib1g-dev** — библиотека сжатия
- **build-essential** — компилятор и инструменты сборки

### 2.2. Требования к необходимым для данной программы техническим средствам

#### 2.2.1. Минимальные аппаратные требования

| Компонент | Требование | Примечание |
|-----------|------------|------------|
| Процессор | 2 ядра | x86_64 совместимый |
| Оперативная память | 4 ГБ | При минимальной нагрузке |
| Дисковое пространство | 20 ГБ | SSD рекомендуется |
| Сетевой интерфейс | 100 Мбит/с | Для доступа к источникам |

#### 2.2.2. Рекомендуемые аппаратные требования

| Компонент | Требование | Примечание |
|-----------|------------|------------|
| Процессор | 4 ядра | Для параллельного выполнения задач |
| Оперативная память | 8 ГБ | Для работы Playwright и обработки больших файлов |
| Дисковое пространство | 50 ГБ SSD | Для БД, логов и медиафайлов |
| Сетевой интерфейс | 1 Гбит/с | Для высокой пропускной способности |

#### 2.2.3. Требования к инфраструктуре

- **Доступ в Интернет**: обязательный для всех внешних источников
- **Статический IP-адрес**: рекомендуется для production-развёртывания
- **SSL/TLS сертификат**: обязателен для HTTPS-соединения
- **Резервное питание**: рекомендуется для предотвращения потери данных

#### 2.2.4. Требования к системе управления базами данных

| Параметр | Значение |
|----------|----------|
| СУБД | PostgreSQL 15.10 |
| Минимальный размер БД | 1 ГБ |
| Рекомендуемый размер БД | 10 ГБ+ |
| Максимальное количество подключений | 100 |
| Режим изоляции | Read Committed (по умолчанию) |

#### 2.2.5. Требования к системе кеширования

| Параметр | Значение |
|----------|----------|
| Система | Redis 7.x |
| Режим работы | in-memory с persistence (RDB/AOF) |
| Выделенная память | 512 МБ — 2 ГБ |
| Порты | 6379 (по умолчанию) |

---

## 3. ОПИСАНИЕ ЗАДАЧИ

### 3.1. Определение задачи

#### 3.1.1. Общая характеристика

Система MOSTOVIK решает задачу автоматизированного сбора и консолидации данных из распределённых государственных источников с целью создания единого централизованного хранилища для последующего анализа и использования.

#### 3.1.2. Основные подзадачи

**Извлечение данных (Extract):**

- Подключение к удалённым источникам данных через HTTP/HTTPS
- Авторизация и аутентификация в системах-источниках (при необходимости)
- Получение данных в различных форматах (JSON, HTML, Excel)
- Обход ограничений и защита от блокировок (proxy, rate limiting)

**Трансформация данных (Transform):**

- Парсинг сырых данных и извлечение структурированной информации
- Нормализация форматов (даты, числовые значения, строки)
- Валидация данных на соответствие ожидаемым схемам
- Дедупликация записей по уникальным ключам
- Обогащение данных метаданными (источник, время загрузки, batch ID)

**Загрузка данных (Load):**

- Сохранение обработанных данных в PostgreSQL
- Ведение журнала загрузок (ParserLoadLog)
- Отслеживание прогресса задач (BackgroundJob)
- Индексация для ускорения поиска

#### 3.1.3. Функциональные требования

| ID | Требование | Описание |
|----|------------|----------|
| ФТ-001 | Автоматический сбор данных | Система должна автоматически собирать данные по расписанию |
| ФТ-002 | Поддержка множественных источников | Система должна поддерживать подключение к различным источникам |
| ФТ-003 | Обработка ошибок | Система должна обрабатывать ошибки сети и источников |
| ФТ-004 | Повторные попытки | Система должна выполнять повторные попытки при сбоях |
| ФТ-005 | Логирование | Система должна вести подробный журнал всех операций |
| ФТ-006 | Мониторинг | Система должна предоставлять информацию о статусе задач |
| ФТ-007 | REST API | Система должна предоставлять доступ к данным через API |
| ФТ-008 | Дедупликация | Система должна предотвращать дублирование записей |

### 3.2. Методы решения задачи

#### 3.2.1. Архитектурный подход

Система построена по **ETL-архитектуре** с использованием следующих принципов:

- **Модульность**: каждый источник данных реализуется в виде отдельного модуля
- **Расширяемость**: новые источники добавляются без изменения ядра системы
- **Асинхронность**: задачи выполняются фоново через очередь Celery
- **Отказоустойчивость**: сохранение прогресса и повторные попытки при ошибках

#### 3.2.2. Методы извлечения данных

**HTTP-запросы (requests library):**

Прямые запросы к API источников данных.

**Веб-скрапинг (Scrapy, BeautifulSoup):**

Парсинг HTML-страниц государственных сайтов.

**Браузерная автоматизация (Playwright, Selenium):**

Для JavaScript-рендеринга и динамических страниц.

**Парсинг файлов (pandas, openpyxl):**

Обработка Excel-файлов и других табличных форматов.

#### 3.2.3. Методы трансформации данных

**Нормализация:**

- Приведение дат к единому формату (YYYY-MM-DD)
- Очистка строк от лишних пробелов и символов
- Стандартизация числовых форматов

**Дедупликация:**

Механизм update_or_create по уникальным ключам (ИНН, ОГРН, номер сертификата).

**Валидация:**

- Проверка обязательных полей
- Валидация форматов (ИНН, ОГРН)
- Проверка ссылочной целостности

#### 3.2.4. Методы загрузки данных

**Пакетная загрузка:**

- Группировка записей по batch ID
- Атомарное сохранение пакетов
- Откат при ошибках

**Потоковая обработка:**

- Обработка больших файлов по частям
- Прогресс-отслеживание
- Кеширование промежуточных результатов

#### 3.2.5. Методы планирования задач

**Celery Beat (периодические задачи):**

| Задача | Расписание |
|--------|------------|
| Парсинг Минпромторга | Ежедневно в 3:00 |
| Парсинг реестра производителей | Ежедневно в 4:00 |
| Синхронизация проверок | По мере необходимости |
| Сканирование папки ФНС | Каждые 5 минут |

**Управление очередями:**

- Приоритизация задач
- Распределение по workers
- Мониторинг через Flower

#### 3.2.6. Методы обеспечения надёжности

**Логирование:**

- Запись всех операций в ParserLoadLog
- Детализация ошибок
- Аудит действий пользователей

**Мониторинг:**

- Отслеживание статуса задач (BackgroundJob)
- Прогресс выполнения (0–100%)
- Уведомления об ошибках

**Восстановление:**

- Точки сохранения (checkpoints)
- Повторные попытки с экспоненциальной задержкой
- Резервное копирование БД

---

## 4. ВХОДНЫЕ И ВЫХОДНЫЕ ДАННЫЕ

### 4.1. Сведения о входных данных

#### 4.1.1. Классификация входных данных

| Тип | Источник | Формат | Периодичность |
|-----|----------|--------|---------------|
| Сертификаты промышленного производства | Минпромторг (API) | JSON | Ежедневно |
| Реестр производителей | Минпромторг (веб) | HTML/JSON | Ежедневно |
| Данные о проверках | proverki.gov.ru (веб) | HTML/JSON | По запросу |
| Бухгалтерская отчётность | ФНС (файлы) | Excel (.xlsx) | По мере поступления |

#### 4.1.2. Структура входных данных

**Сертификаты Минпромторга:**

- certificate_number: номер сертификата (строка)
- issue_date: дата выдачи (YYYY-MM-DD)
- expiry_date: дата окончания (YYYY-MM-DD)
- organisation_name: название организации (текст)
- inn: ИНН организации (строка)
- ogrn: ОГРН организации (строка)
- certificate_file_url: URL файла сертификата

**Реестр производителей:**

- inn: ИНН производителя
- ogrn: ОГРН производителя
- manufacturer_name: наименование производителя
- address: юридический адрес
- products: список продукции

**Данные о проверках:**

- inspection_id: идентификатор проверки
- inspection_type: тип (294/248 ФЗ)
- data_year: год данных
- data_month: месяц данных
- entity_name: название юридического лица
- entity_inn: ИНН проверяемого лица
- inspection_date: дата проверки
- inspection_body: орган проведения проверки

**Бухгалтерская отчётность (Excel):**

- Период: отчётный период
- Выручка: сумма выручки
- Прибыль: сумма прибыли
- Активы: сумма активов
- Обязательства: сумма обязательств

#### 4.1.3. Требования к качеству входных данных

| Параметр | Требование |
|----------|------------|
| Полнота | Все обязательные поля должны быть заполнены |
| Актуальность | Данные должны соответствовать текущему состоянию источника |
| Консистентность | Данные должны соответствовать ожидаемой схеме |
| Уникальность | Дубликаты должны быть идентифицируемы по ключевым полям |

#### 4.1.4. Ограничения входных данных

- **Максимальный размер файла**: 50 МБ (для Excel-файлов ФНС)
- **Максимальное количество записей в пакете**: 10 000
- **Таймаут запроса к источнику**: 30 секунд
- **Максимальное количество повторных попыток**: 3

### 4.2. Сведения о выходных данных

#### 4.2.1. Классификация выходных данных

| Тип | Назначение | Формат | Способ доступа |
|-----|------------|--------|----------------|
| Нормализованные данные | Хранение в БД | PostgreSQL таблицы | Внутреннее API |
| Данные для клиентов | REST API | JSON | HTTP/HTTPS |
| Отчёты о загрузках | Аудит и мониторинг | PostgreSQL + логи | Django Admin, API |
| Файлы выгрузки | Экспорт данных | CSV, Excel | По запросу |

#### 4.2.2. Структура выходных данных

**Таблицы базы данных:**

| Таблица | Описание | Ключевые поля |
|---------|----------|---------------|
| parsers_industrial_certificate | Сертификаты Минпромторга | certificate_number, inn, ogrn |
| parsers_manufacturer_record | Реестр производителей | inn, ogrn |
| parsers_inspection_record | Проверки | inspection_id, entity_inn |
| parsers_financial_report | Отчёты ФНС | external_id, ogrn |
| parsers_load_log | Журнал загрузок | batch_id, source, status |
| core_backgroundjob | Статус задач | task_id, status, progress |

**REST API ответы:**

Формат JSON с пагинацией:
- count: общее количество записей
- next: URL следующей страницы
- previous: URL предыдущей страницы
- results: массив объектов данных

**Статус задачи (BackgroundJob):**

- task_id: уникальный идентификатор задачи
- task_name: имя задачи
- status: статус (pending/running/completed/failed)
- progress: прогресс выполнения (0-100)
- message: текстовое сообщение
- result: результат выполнения (JSON)
- started_at: время начала
- completed_at: время завершения

**Лог загрузки (ParserLoadLog):**

- batch_id: идентификатор пакета
- source: источник данных
- records_count: количество записей
- status: статус загрузки
- error_message: сообщение об ошибке
- created_at: время создания

#### 4.2.3. Требования к качеству выходных данных

| Параметр | Требование |
|----------|------------|
| Целостность | Все внешние ключи должны быть валидны |
| Консистентность | Данные должны соответствовать схеме БД |
| Индексирование | Ключевые поля должны быть индексированы |
| Аудит | Все изменения должны логироваться |

#### 4.2.4. Форматы представления данных

**JSON (REST API):**

- Кодировка: UTF-8
- Формат дат: ISO 8601
- Пагинация: cursor-based или page-based

**CSV (экспорт):**

- Разделитель: точка с запятой (;)
- Кодировка: UTF-8
- Заголовки: имена полей

**Excel (экспорт):**

- Формат: .xlsx
- Кодировка: UTF-8
- Листы: по одному на таблицу

#### 4.2.5. Объёмы выходных данных

| Источник | Ожидаемый объём (мес.) | Рост (год) |
|----------|----------------------|------------|
| Сертификаты | 1 000 — 5 000 записей | ~50 000 записей |
| Производители | 500 — 2 000 записей | ~20 000 записей |
| Проверки | 5 000 — 20 000 записей | ~200 000 записей |
| Отчёты ФНС | 100 — 500 файлов | ~5 000 файлов |

---

## ПРИЛОЖЕНИЕ А. ГЛОССАРИЙ

| Термин | Определение |
|--------|-------------|
| ETL | Extract, Transform, Load — процесс извлечения, трансформации и загрузки данных |
| Batch ID | Уникальный идентификатор пакета загруженных данных |
| BackgroundJob | Фоновая задача с отслеживанием прогресса |
| ParserLoadLog | Журнал загрузок парсеров |
| Playwright | Библиотека для автоматизации браузера |
| Celery | Распределённая очередь задач |
| Django | Веб-фреймворк для разработки на Python |
| REST API | Программный интерфейс на основе HTTP |
| PostgreSQL | Реляционная система управления базами данных |
| Redis | Система кеширования и брокер сообщений |

---

*Документ составлен на основе версии кода от 2026-01-21*