добавил документов в папку

2026-03-26 15:46:37 +03:00
parent 1b326eb1b0
commit 3b986b6310
8 changed files with 3469 additions and 0 deletions
--- a/docs/TECHNICAL_SPECIFICATION.md
+++ b/docs/TECHNICAL_SPECIFICATION.md
@@ -0,0 +1,493 @@
+# ТЕХНИЧЕСКАЯ СПЕЦИФИКАЦИЯ
+## Система 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*