docs: update roadmap and changelog for v3.0 clean architecture release

This commit is contained in:
2026-08-21 11:50:03 +03:00
parent e8a542eded
commit feff469282
2 changed files with 63 additions and 46 deletions
+33 -46
View File
@@ -74,56 +74,43 @@
---
## 8. Архитектурный рефакторинг и декомпозиция монолитов (Текущий этап)
> **Контроль версий:** перед каждым этапом и после его успешной проверки выполняется коммит и фиксация в репозитории **Gitea**.
## 🏗️ Раздел 8. Глубокий архитектурный рефакторинг ядра и сервисов `[ЗАВЕРШЕНО]`
- [ ] **Шаг 0: Фиксация базового состояния в Gitea:**
- Создание тега/коммита `v2.5-pre-refactor` в Gitea перед структурными изменениями.
- [ ] **Шаг 1: Разделение слоя данных и ядра (`core/`):**
- Создание `core/connection.py` (единый SQLite Connection Manager с WAL и таймаутами).
- Создание `core/schema.py` (DDL-инициализация всех таблиц и индексов из `database.py`).
- Фиксация контрольной точки в Gitea.
- [ ] **Шаг 2: Выделение доменных сервисов (`services/` / `domain/`):**
- **Задачи (`services/tasks/`):** декомпозиция на `repository.py`, `service.py`, `exporter.py` (правило: до 100–150 строк на файл).
- **Системный промпт (`services/prompts/`):** декомпозиция на `repository.py`, `service.py`, `diff_engine.py`.
- **Снапшоты (`services/snapshots/`):** декомпозиция на `repository.py`, `service.py`.
- **База знаний и правила (`services/knowledge/`):** вынос правил арбитража и словаря синонимов подразделений.
- Фиксация контрольной точки в Gitea.
- [ ] **Шаг 3: Декомпозиция ETL-конвейера (`main_etl.py` и `scud_export.py`):**
- Выделение `services/scud_etl/pipeline.py` (оркестрация без длинных простыней кода).
- Выделение `services/scud_etl/merger.py` (чистая склейка Dataframe 1С ⟷ СКУД).
- Выделение `services/scud_etl/anomaly_detector.py` (алгоритмическая детекция нарушений).
- Выделение `services/scud_etl/sql_queries.py` (вынос длинных T-SQL запросов).
- Фиксация контрольной точки в Gitea.
- [ ] **Шаг 4: Выделение чистого ИИ-оркестратора (`modules/ai_engine/`):**
- Создание компактного `agent.py` (~60–80 строк) без ветвлений `if/elif` на сотни строк.
- Внедрение изолированных обработчиков инструментов:
- `handlers/task_handler.py`
- `handlers/prompt_handler.py`
- `handlers/snapshot_handler.py`
- `handlers/anomaly_handler.py`
- Создание `context_builder.py` (календарь, роли, сборка системного контекста).
- Фиксация контрольной точки в Gitea.
- [ ] **Шаг 5: Облегчение `web_api` и адаптация роутеров:**
- Превращение `web_api` исключительно в тонкий транспортный шлюз (FastAPI + Статика).
- Очистка роутеров от прямого SQL — вызовы только через доменные сервисы.
- Рефакторинг CLI-утилиты `scripts/db_cli.py` (вынос форматирования в `scripts/cli/formatters.py`).
- Финальное сквозное тестирование и фиксация релиза в Gitea (`v3.0-clean-architecture`).
- [x] **Шаг 1. Выделение общего слоя ядра (`core/`)**
- [x] Изолированный пул соединений SQLite (`core/connection.py`) с поддержкой WAL и таймаутов.
- [x] DDL-схемы таблиц и индексов (`core/schema.py`).
- [x] Репозитории СКУД и 1С (`core/repositories/scud_repo.py`, `core/repositories/zup_repo.py`).
- [x] Фасад обратной совместимости (`core/database.py`).
- [x] **Шаг 2. Декомпозиция предметных доменов (`services/`)**
- [x] Сервис задач (`services/tasks/`): CRUD, валидация, markdown-экспорт (`exporter.py`).
- [x] Сервис системного промпта (`services/prompts/`): сборка узлов, вычисление diff (`diff_engine.py`), пакетное удаление (`BATCH_DELETE`).
- [x] Сервис снапшотов СКУД (`services/snapshots/`): безопасное удаление с защитой Y-снапшотов.
- [x] Сервис базы знаний (`services/knowledge/`): правила арбитража и синонимы отделов.
- [x] **Шаг 3. Рефакторинг ETL-конвейера (`services/scud_etl/`)**
- [x] Оркестратор этапов контроллинга (`pipeline.py`).
- [x] Детектор аномалий и конфликтов реестров (`anomaly_detector.py`).
- [x] Агрегация проходов и наложение исключений (`merger.py`).
- [x] Информативное консольное логирование этапов в `main_etl.py`.
- [x] **Шаг 4. Модульный ИИ-оркестратор (`modules/ai_engine/`)**
- [x] Динамический строитель системного контекста (`context_builder.py`).
- [x] Изолированные обработчики инструментов (`handlers/task_handler.py`, `handlers/prompt_handler.py`, `handlers/snapshot_handler.py`).
- [x] Компактный диспетчер диалога (`agent.py`).
- [x] Двухконтурный семантический анализатор намерений (`tool_injector.py`).
- [x] **Шаг 5. Зачистка рудиментов и стабилизация**
- [x] Устранение дубликатов в `web_api/llm/db/`.
- [x] Очистка роутеров от прямых манипуляций с базой данных.
- [x] Исправление сигнатур Fast-Path перехватчиков.
---
## 9. Диалоговая генерация и контроль отчетов СКУД (Conversational Reporting Engine)
- [ ] **Инструмент построения сводок (`db_generate_scud_report`):**
- Создание инструмента Function Calling для запуска конвейера контроллинга за выбранную дату/снапшот прямо из чата[cite: 4].
- Поддержка параметров: `target_date`, `snapshot_id`, `mode` (`summary` — дневная сводка, `detailed` — вчерашний отчет)[cite: 4].
- [ ] **Интерактивная карточка аудита отчета в UI:**
- Вывод статуса генерации, ключевых метрик (всего сотрудников, явка, опоздания, количество аномалий)[cite: 4].
- Ссылки на сгенерированные файлы Excel (`.xlsx`) и Markdown (`.md`)[cite: 4].
- [ ] **Диалоговый разбор аномалий и исключений:**
- Возможность в диалоге запросить расшифровку конкретной аномалии[cite: 4].
- Быстрое добавление сотрудника/отдела в `exceptions.json` или базу знаний прямо из чата по кнопке карточки[cite: 4].
- [ ] **Экспорт и отправка среза:**
- Команда формирования итоговой выгрузки для руководства в формате PDF/Markdown с передачей файла пользователю[cite: 4].
## 📊 Раздел 9. Диалоговая генерация и контроль отчетов СКУД (Conversational Reporting Engine) `[В ПЛАНАХ]`
- [ ] **Интерактивный запуск отчетов из чата**
- [ ] Инструмент `db_generate_report(date_str, report_type)` для генерации сводки или детального отчета по требованию оператора.
- [ ] Автоматическая отдача карточки скачивания сформированного Excel-файла прямо в диалоге (`FILE_DOWNLOAD_CARD`).
- [ ] **Диалоговый аудит расхождений**
- [ ] Инструмент точечной выборки: «Кто сегодня не пришел из отдела ОВК?», «Покажи опоздавших за вчера».
- [ ] Быстрое внесение исключений и синонимов подразделений через диалог.
---