feat: Обновить README и архитектуру проекта, добавить поддержку режима cron и улучшить интерфейс командной строки

2026-09-24 01:10:20 +00:00 · 2025-10-26 16:53:59 +03:00
parent 877a0e0553
commit 22e32354f5
4 changed files with 349 additions and 97 deletions
@@ -0,0 +1,69 @@
+# Архитектура проекта
+
+Ниже — схема на уровне компонентов в формате, аналогичном примеру.
+
+```
+                 [CLI (main.py / run.fish / run.sh / run_cron.fish)]
+                                   |
+                                   v
+               Fetcher — загрузка HTML и проверка кода ответа
+                     [Fetcher: HTTP GET (requests.Session)]
+                             (timeout / retries / delay)
+                                   |
+                                   v
+    • Parser      — извлечение таблиц/списков и распознавание колонок (BS4+lxml)
+    • Normalizer  — очистка значений, trim, удаление префиксов, приведение типов/дат
+    • Model       — маппинг в dataclasses (Auditor, Organization, …)
+    • Exporter    — выгрузка pandas.DataFrame в Excel через openpyxl
+                                   |
+                                   v
+[Pipeline]
+[Parser (BeautifulSoup + эвристики)] --> [Normalizer] --> [Model] --> [DataFrame] --> [Exporter (XLSX)]
+```
+
+## Соответствие компонент файлам
+
+- CLI / запуск:
+  - `main.py` — CLI-меню, режим неинтерактивного запуска через аргументы (`--registry`, `--mode`, `--list`).
+  - `run.fish`, `run.sh` — быстрый старт; `run_cron.fish` — обёртка для cron (Fish).
+
+- Fetcher:
+  - `parsers/base_parser.py` → `BaseParser._make_request()` (requests.Session, заголовок User-Agent, таймаут, задержка, повторные попытки).
+  - Пагинация: `BaseParser._get_pagination_urls()`.
+
+- Parser:
+  - Специализированные: `parsers/auditors_parser.py`, `parsers/organizations_parser.py`.
+  - Универсальный: `parsers/generic_parser.py` (табличные реестры, автоматическое определение заголовков).
+  - Общая точка входа: `BaseParser.parse_registry(detailed=...)`.
+
+- Normalizer:
+  - Локальные шаги очистки/приведения: обрезка пробелов, извлечение чисел/дат, нормализация полей (внутри парсеров).
+  - Приведение к словарям/рубрикам, единообразные ключи для экспорта.
+
+- Model:
+  - `models/auditor.py`, `models/organization.py`, и др. — dataclasses, метод `to_dict()` для экспорта.
+
+- DataFrame + Exporter:
+  - Формирование `pandas.DataFrame` и экспорт: `utils/excel_exporter.py` → `ExcelExporter.export_to_excel()`.
+  - Форматирование XLSX (ширина колонок, шапка, стили): `ExcelExporter._format_excel()`.
+
+- Конфигурация и логирование:
+  - `config.py` — URL реестров (`REGISTRIES`), сетевые и экспортные настройки (`PARSER_CONFIG`, `EXPORT_CONFIG`, `LOGGING_CONFIG`).
+  - `utils/logger.py` — консольный и файловый логгеры (`logs/parser_YYYY-MM-DD.log`).
+
+## Потоки выполнения
+
+- Режим запуска:
+  - Интерактивный CLI: выбор реестра и детализации из меню (`main.py`).
+  - Неинтерактивный (для cron): `python main.py --registry <key> --mode <quick|full>`.
+
+- Детализация:
+  - `mode=quick` — первая страница (без обхода пагинации и детальных карточек).
+  - `mode=full` — все страницы (пагинация) и, при поддержке, парсинг детальных карточек записей.
+
+- Надёжность:
+  - Повторные попытки при ошибках сети, управляемая задержка между запросами.
+  - Логи INFO/DEBUG в консоль и файл.
+
+- Выходные данные:
+  - Сырые записи → нормализованные словари → модели (dataclasses) → `pandas.DataFrame` → XLSX в `data/exports/`.