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

docs/RUKOVODSTVO_ADMINISTRATORA.md

@@ -0,0 +1,594 @@
+# РУКОВОДСТВО АДМИНИСТРАТОРА
+## Система ETL MOSTOVIK
+
+Версия документа: 1.0  
+Дата: 2026-01-21
+
+---
+
+## СОДЕРЖАНИЕ
+
+1. [Общие сведения](#1-общие-сведения)
+2. [Архитектура системы](#2-архитектура-системы)
+3. [Развёртывание системы](#3-развёртывание-системы)
+4. [Конфигурирование](#4-конфигурирование)
+5. [Управление службами](#5-управление-службами)
+6. [Мониторинг и логирование](#6-мониторинг-и-логирование)
+7. [Резервное копирование](#7-резервное-копирование)
+8. [Безопасность](#8-безопасность)
+9. [Устранение неисправностей](#9-устранение-неисправностей)
+
+---
+
+## 1. ОБЩИЕ СВЕДЕНИЯ
+
+### 1.1. Назначение системы
+
+MOSTOVIK — система ETL (Extract, Transform, Load) для сбора и обработки данных из государственных источников:
+
+- **Минпромторг** (minpromtorg.gov.ru) — сертификаты промышленного производства, реестр производителей
+- **Единый реестр проверок** (proverki.gov.ru) — данные о проверках по ФЗ-294 и ФЗ-248
+- **ФНС** — бухгалтерская отчётность
+
+### 1.2. Технические характеристики
+
+| Параметр | Значение |
+|----------|----------|
+| Язык программирования | Python 3.11 |
+| Фреймворк | Django 3.2.25 |
+| База данных | PostgreSQL 15.10 |
+| Кеш/брокер | Redis 7.x |
+| Очереди задач | Celery 5.3.6 |
+| Веб-сервер | Apache 2.4.57 + Gunicorn |
+| Автоматизация браузера | Playwright 1.52+ |
+
+---
+
+## 2. АРХИТЕКТУРА СИСТЕМЫ
+
+### 2.1. Компоненты системы
+
+```
++-------------------------------------------------------------+
+|                        Apache 2.4.57                        |
+|                     (HTTPS termination)                     |
++-----------------------------+-------------------------------+
+                              |
+                              v
++-------------------------------------------------------------+
+|                      Gunicorn WSGI                          |
+|                    (3 workers, gevent)                      |
++-----------------------------+-------------------------------+
+                              |
+                              v
++-------------------------------------------------------------+
+|                    Django Application                       |
+|  +--------------+  +--------------+  +------------------+  |
+|  |   Parsers    |  |     Core     |  |      User        |  |
+|  |    (apps)    |  |    (apps)    |  |      (apps)      |  |
+|  +--------------+  +--------------+  +------------------+  |
++-----------------------------+-------------------------------+
+                              |
+                +-------------+-------------+
+                v             v             v
++---------------+ +-----------+ +---------------+
+|  PostgreSQL   | |   Redis   | |   File System |
+|   (port 5432) | | (port 6379)| |  (logs/media) |
++---------------+ +-----------+ +---------------+
+```
+
+### 2.2. Службы Celery
+
+| Служба | Назначение | Порт |
+|--------|------------|------|
+| celery-worker | Выполнение фоновых задач | - |
+| celery-beat | Планирование периодических задач | - |
+| flower | Мониторинг Celery (опционально) | 5555 |
+
+### 2.3. Структура каталогов
+
+```
+/var/www/project/
+├── src/                    # Исходный код Django
+│   ├── config/            # Конфигурация
+│   │   ├── settings/      # Настройки (dev, prod, test)
+│   │   ├── celery.py     # Конфигурация Celery
+│   │   └── wsgi.py       # Точка входа WSGI
+│   ├── apps/              # Приложения Django
+│   │   ├── core/         # Базовые компоненты
+│   │   ├── parsers/      # Парсеры данных
+│   │   └── user/         # Пользователи и аутентификация
+│   └── manage.py         # Утилита управления
+├── venv/                  # Виртуальное окружение Python
+├── logs/                  # Логи приложения
+├── media/                 # Пользовательские файлы
+├── staticfiles/           # Статические файлы
+└── deploy/                # Файлы развёртывания
+    ├── systemd/          # Unit-файлы systemd
+    ├── apache/           # Конфигурация Apache
+    └── scripts/          # Скрипты развёртывания
+```
+
+---
+
+## 3. РАЗВЁРТЫВАНИЕ СИСТЕМЫ
+
+### 3.1. Системные требования
+
+**Минимальные:**
+- ЦПУ: 2 ядра
+- ОЗУ: 4 ГБ
+- Диск: 20 ГБ
+- ОС: Astra Linux / Ubuntu 20.04+
+
+**Рекомендуемые:**
+- ЦПУ: 4 ядра
+- ОЗУ: 8 ГБ
+- Диск: 50 ГБ SSD
+- ОС: Astra Linux Special Edition
+
+### 3.2. Предварительная настройка
+
+#### 3.2.1. Установка системных зависимостей
+
+```bash
+apt-get update && apt-get upgrade -y
+
+apt-get install -y \
+    python3.11 \
+    python3.11-venv \
+    python3.11-dev \
+    postgresql-15 \
+    postgresql-client-15 \
+    redis-server \
+    apache2 \
+    libapache2-mod-wsgi-py3 \
+    git \
+    build-essential \
+    libpq-dev \
+    libffi-dev \
+    libxml2-dev \
+    libxslt1-dev \
+    zlib1g-dev
+```
+
+#### 3.2.2. Установка менеджера пакетов uv
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source $HOME/.cargo/env
+```
+
+### 3.3. Автоматическое развёртывание
+
+```bash
+chmod +x deploy/scripts/deploy.sh
+sudo ./deploy/scripts/deploy.sh
+```
+
+Скрипт выполняет:
+- Обновление системы
+- Установку зависимостей
+- Клонирование репозитория
+- Создание виртуального окружения
+- Установку зависимостей Python
+- Настройку базы данных
+- Выполнение миграций
+- Настройку systemd и Apache
+
+### 3.4. Ручное развёртывание
+
+#### 3.4.1. Настройка базы данных
+
+```bash
+sudo -u postgres psql <<EOF
+CREATE DATABASE mostovik_prod;
+CREATE USER mostovik_user WITH PASSWORD 'secure_password';
+GRANT ALL PRIVILEGES ON DATABASE mostovik_prod TO mostovik_user;
+ALTER DATABASE mostovik_prod OWNER TO mostovik_user;
+EOF
+```
+
+#### 3.4.2. Установка приложения
+
+```bash
+PROJECT_PATH="/var/www/project"
+mkdir -p ${PROJECT_PATH}/{src,logs,media,staticfiles}
+cd ${PROJECT_PATH}
+
+# Клонирование репозитория
+git clone <repository_url> .
+git checkout main
+
+# Создание виртуального окружения
+uv venv ${PROJECT_PATH}/venv
+source ${PROJECT_PATH}/venv/bin/activate
+
+# Установка зависимостей
+uv pip install --upgrade pip
+uv pip install -r requirements.txt
+```
+
+#### 3.4.3. Настройка окружения
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+**Обязательные параметры:**
+
+| Переменная | Описание | Пример |
+|------------|----------|--------|
+| SECRET_KEY | Ключ шифрования Django | django-insecure-... |
+| POSTGRES_DB | Имя базы данных | mostovik_prod |
+| POSTGRES_USER | Пользователь БД | mostovik_user |
+| POSTGRES_PASSWORD | Пароль БД | secure_password |
+| POSTGRES_HOST | Узел БД | 127.0.0.1 |
+| POSTGRES_PORT | Порт БД | 5432 |
+| REDIS_URL | URL Redis | redis://127.0.0.1:6379/0 |
+| CELERY_BROKER_URL | URL брокера | redis://127.0.0.1:6379/0 |
+
+#### 3.4.4. Выполнение миграций
+
+```bash
+cd ${PROJECT_PATH}/src
+python manage.py makemigrations
+python manage.py migrate
+python manage.py collectstatic --noinput
+```
+
+#### 3.4.5. Создание суперпользователя
+
+```bash
+python manage.py createsuperuser
+```
+
+Или автоматически:
+
+```bash
+echo "from django.contrib.auth import get_user_model; User = get_user_model(); User.objects.create_superuser('admin', 'admin@example.com', 'adminpass') if not User.objects.filter(username='admin').exists() else None" | python manage.py shell
+```
+
+---
+
+## 4. КОНФИГУРИРОВАНИЕ
+
+### 4.1. Настройка Apache
+
+Конфигурационный файл: /etc/apache2/sites-available/project.conf
+
+**Основные параметры для изменения:**
+
+```apache
+ServerName your-domain.com
+SSLCertificateFile /etc/ssl/certs/your-cert.pem
+SSLCertificateKeyFile /etc/ssl/private/your-key.pem
+SSLCertificateChainFile /etc/ssl/certs/your-chain.pem
+```
+
+**Активация сайта:**
+
+```bash
+a2ensite project.conf
+a2enmod ssl rewrite headers expires
+a2dissite 000-default
+systemctl restart apache2
+```
+
+### 4.2. Настройка systemd
+
+Файлы служб расположены в /etc/systemd/system/:
+
+| Файл | Служба |
+|------|--------|
+| gunicorn.service | WSGI-сервер Gunicorn |
+| celery-worker.service | Worker Celery |
+| celery-beat.service | Планировщик Celery |
+
+**Перезапуск после изменений:**
+
+```bash
+systemctl daemon-reload
+systemctl restart gunicorn
+systemctl restart celery-worker
+systemctl restart celery-beat
+```
+
+### 4.3. Настройка брандмауэра
+
+```bash
+ufw allow 80/tcp
+ufw allow 443/tcp
+ufw deny 5432/tcp
+ufw deny 6379/tcp
+ufw enable
+```
+
+---
+
+## 5. УПРАВЛЕНИЕ СЛУЖБАМИ
+
+### 5.1. Проверка состояния служб
+
+```bash
+systemctl status gunicorn
+systemctl status celery-worker
+systemctl status celery-beat
+systemctl status apache2
+systemctl status postgresql
+systemctl status redis-server
+```
+
+### 5.2. Запуск/остановка/перезапуск
+
+```bash
+systemctl start gunicorn
+systemctl stop gunicorn
+systemctl restart gunicorn
+
+systemctl start celery-worker
+systemctl stop celery-worker
+systemctl restart celery-worker
+
+systemctl start celery-beat
+systemctl stop celery-beat
+systemctl restart celery-beat
+
+systemctl restart apache2
+```
+
+### 5.3. Включение автозагрузки
+
+```bash
+systemctl enable gunicorn celery-worker celery-beat apache2 postgresql redis-server
+```
+
+### 5.4. Управление через Makefile
+
+```bash
+cd /var/www/project
+
+make migrate
+make createsuperuser
+make shell
+make logs
+```
+
+---
+
+## 6. МОНИТОРИНГ И ЛОГИРОВАНИЕ
+
+### 6.1. Логи приложения
+
+| Лог | Путь |
+|-----|------|
+| Django | /var/www/project/logs/django.log |
+| Celery | /var/www/project/logs/celery.log |
+| Gunicorn | /var/log/gunicorn/error.log |
+| Apache error | /var/log/apache2/project_error.log |
+| Apache access | /var/log/apache2/project_access.log |
+| PostgreSQL | /var/log/postgresql/postgresql-15-main.log |
+| Redis | /var/log/redis/redis-server.log |
+
+### 6.2. Просмотр логов в реальном времени
+
+```bash
+tail -f /var/www/project/logs/django.log
+tail -f /var/www/project/logs/celery.log
+
+journalctl -u gunicorn -f
+journalctl -u celery-worker -f
+journalctl -u celery-beat -f
+journalctl -u apache2 -f
+```
+
+### 6.3. Мониторинг Celery Flower
+
+```bash
+source /var/www/project/venv/bin/activate
+celery -A config flower --port=5555
+```
+
+**Доступ:** http://localhost:5555
+
+### 6.4. Мониторинг базы данных
+
+```bash
+sudo -u postgres psql mostovik_prod
+
+# Проверка размера таблиц
+SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
+FROM pg_tables
+WHERE schemaname = 'public'
+ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
+
+# Проверка активных подключений
+SELECT * FROM pg_stat_activity WHERE datname = 'mostovik_prod';
+```
+
+### 6.5. Мониторинг Redis
+
+```bash
+redis-cli
+INFO
+DBSIZE
+```
+
+---
+
+## 7. РЕЗЕРВНОЕ КОПИРОВАНИЕ
+
+### 7.1. Резервное копирование базы данных
+
+```bash
+#!/bin/bash
+BACKUP_DIR="/var/backups/mostovik"
+DATE=$(date +%Y%m%d_%H%M%S)
+DB_NAME="mostovik_prod"
+DB_USER="mostovik_user"
+
+mkdir -p ${BACKUP_DIR}
+pg_dump -U ${DB_USER} -h 127.0.0.1 ${DB_NAME} | gzip > ${BACKUP_DIR}/db_backup_${DATE}.sql.gz
+find ${BACKUP_DIR} -name "db_backup_*.sql.gz" -mtime +7 -delete
+```
+
+**Настройка cron:**
+
+```bash
+0 2 * * * /var/www/project/scripts/backup_db.sh
+```
+
+### 7.2. Резервное копирование медиафайлов
+
+```bash
+#!/bin/bash
+BACKUP_DIR="/var/backups/mostovik"
+DATE=$(date +%Y%m%d_%H%M%S)
+MEDIA_DIR="/var/www/project/media"
+
+mkdir -p ${BACKUP_DIR}
+tar -czf ${BACKUP_DIR}/media_backup_${DATE}.tar.gz ${MEDIA_DIR}
+find ${BACKUP_DIR} -name "media_backup_*.tar.gz" -mtime +7 -delete
+```
+
+### 7.3. Восстановление
+
+```bash
+# Восстановление БД
+gunzip -c db_backup_20260121_020000.sql.gz | psql -U mostovik_user -h 127.0.0.1 mostovik_prod
+
+# Восстановление медиа
+tar -xzf media_backup_20260121_020000.tar.gz -C /var/www/project/
+```
+
+---
+
+## 8. БЕЗОПАСНОСТЬ
+
+### 8.1. Минимальные требования
+
+1. Смена SECRET_KEY в .env
+2. Смена паролей БД и суперпользователя
+3. Настройка HTTPS с действительным сертификатом
+4. Ограничение доступа к портам БД и Redis
+5. Регулярное обновление системы
+
+### 8.2. Настройка SSL/TLS
+
+```bash
+apt-get install certbot python3-certbot-apache
+certbot --apache -d your-domain.com -d www.your-domain.com
+certbot renew --dry-run
+```
+
+### 8.3. Обновление зависимостей
+
+```bash
+source /var/www/project/venv/bin/activate
+pip-audit
+uv pip install --upgrade -r requirements.txt
+systemctl restart gunicorn celery-worker celery-beat
+```
+
+### 8.4. Аудит безопасности
+
+```bash
+bandit -r /var/www/project/src/
+pip-audit
+python manage.py check --deploy
+```
+
+---
+
+## 9. УСТРАНЕНИЕ НЕИСПРАВНОСТЕЙ
+
+### 9.1. Служба не запускается
+
+```bash
+journalctl -u <service_name> -n 50 --no-pager
+apache2ctl configtest
+systemctl cat <service_name>
+```
+
+### 9.2. Ошибки подключения к БД
+
+```bash
+systemctl status postgresql
+sudo -u postgres psql -c "SELECT * FROM pg_stat_activity WHERE datname = 'mostovik_prod';"
+cat /var/www/project/.env | grep POSTGRES
+```
+
+### 9.3. Ошибки Celery
+
+```bash
+journalctl -u celery-worker -n 100
+
+source /var/www/project/venv/bin/activate
+celery -A config inspect active
+celery -A config inspect registered
+celery -A config status
+celery -A config purge  # осторожно!
+```
+
+### 9.4. Проблемы с производительностью
+
+```bash
+free -h
+top -p $(pgrep -d',' -f gunicorn|celery)
+df -h
+du -sh /var/www/project/logs
+```
+
+**Оптимизация PostgreSQL:**
+
+```sql
+SELECT query, calls, total_time, mean_time
+FROM pg_stat_statements
+ORDER BY mean_time DESC
+LIMIT 10;
+
+VACUUM ANALYZE;
+```
+
+---
+
+## ПРИЛОЖЕНИЕ А. КОМАНДЫ БЫСТРОГО ДОСТУПА
+
+```bash
+# Перезапуск всех служб
+systemctl restart apache2 gunicorn celery-worker celery-beat
+
+# Проверка состояния
+systemctl status apache2 gunicorn celery-worker celery-beat postgresql redis-server
+
+# Просмотр логов
+journalctl -u gunicorn -n 100 --no-pager
+
+# Django shell
+cd /var/www/project/src && python manage.py shell
+
+# Миграции
+cd /var/www/project/src && python manage.py makemigrations && python manage.py migrate
+
+# Статические файлы
+cd /var/www/project/src && python manage.py collectstatic --noinput
+```
+
+---
+
+## ПРИЛОЖЕНИЕ Б. ПЕРИОДИЧЕСКИЕ ЗАДАЧИ CELERY
+
+| Задача | Расписание | Описание |
+|--------|------------|----------|
+| parse_industrial_production | Ежедневно в 3:00 | Парсинг сертификатов Минпромторга |
+| parse_manufactures | Ежедневно в 4:00 | Парсинг реестра производителей |
+| scan_fns_directory | Каждые 5 минут | Сканирование папки ФНС |
+
+**Изменение расписания:**
+
+Через Django Admin: /admin/django_celery_beat/periodictask/
+
+---
+
+*Документ составлен на основе версии кода от 2026-01-21*

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*