avm/mostovik-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fix_config
mostovik-backend/docs/TECHNICAL_SPECIFICATION.md

25 KiB
Raw Permalink Blame History

ТЕХНИЧЕСКАЯ СПЕЦИФИКАЦИЯ

Система 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

Reference in New Issue View Git Blame Copy Permalink