From feff469282c7de874d9b14206fea446be1bf4a61 Mon Sep 17 00:00:00 2001 From: manoraga Date: Fri, 21 Aug 2026 11:50:03 +0300 Subject: [PATCH] docs: update roadmap and changelog for v3.0 clean architecture release --- docs/CHANGELOG.md | 30 ++++++++++++++ docs/in_progress/ROADMAP.md | 79 ++++++++++++++++--------------------- 2 files changed, 63 insertions(+), 46 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index c1ccf25..0301c1e 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -2,6 +2,36 @@ Все ключевые изменения архитектуры, инструментов и модулей проекта SCUD Orion AI фиксируются в данном файле[cite: 6]. +## [3.0.0] — 2026-08-21 +### 🚀 Глубокий архитектурный рефакторинг (Unified Clean Architecture) + +#### Добавлено: +- **Пакет ядра `core/`:** + - `core/connection.py`: централизованный менеджер SQLite-подключений с поддержкой WAL-режима и row_factory. + - `core/schema.py`: единая точка инициализации схемы данных и индексов. + - `core/repositories/`: низкоуровневые репозитории `scud_repo.py` и `zup_repo.py`. +- **Доменные сервисы `services/`:** + - `services/tasks/`: полная изоляция логики задач (CRUD, Markdown-экспорт, генерация `ROADMAP.md`). + - `services/prompts/`: доменный сервис системного промпта, поддержка превью, генерация HTML-Diff и пакетное удаление узлов (`BATCH_DELETE`). + - `services/snapshots/`: бизнес-логика срезов СКУД с защитой финишных Y-снапшотов. + - `services/knowledge/`: сервис базы знаний правил и синонимов отделов. + - `services/scud_etl/`: модульный ETL-конвейер (`pipeline.py`, `anomaly_detector.py`, `merger.py`, `sql_queries.py`). +- **ИИ-оркестратор `modules/ai_engine/`:** + - Декомпозиция монолитного `agent.py` на узкие обработчики `handlers/` и динамический контекст-билдер `context_builder.py`. + - Двухконтурная обработка: нативный Function Calling + семантический страхующий инжектор (`tool_injector.py`). + - Интеллектуальный Topic Drift менеджер с вежливым напоминанием на 3-й шаг и автоочисткой эфемерных сообщений на 4-й. +- **Интерфейс и UI:** + - Кнопка «✏️ Редактировать» прямо в карточке просмотра системного промпта с инлайн-редактором. + +#### Исправлено: +- Устранена утечка системного промпта в постоянный контекст (`chat_messages`). +- Исправлены ошибки несоответствия сигнатур (`TypeError: create_prompt_preview`, `save_full_prompt_draft`, `get_snapshots_registry`) в Fast-Path. +- Устранена галлюцинация слов-паразитов («Почемучка», «Почемучто») на уровне валидации ответа. +- Исправлено устаревшее противоречивое правило 2.3 в базе данных, блокировавшее интерактивное удаление задач. + +#### Удалено: +- Устаревшие файлы-дубли: `modules/web_api/llm/db/db_tasks.py`, `db_snapshots.py`, `prompt_merger.py`. + --- ## [2026-08-19] — Инлайн-редактор задач, интеллектуальный ContextManager и стабилизация Function Calling diff --git a/docs/in_progress/ROADMAP.md b/docs/in_progress/ROADMAP.md index dec7be6..1ec6ff1 100644 --- a/docs/in_progress/ROADMAP.md +++ b/docs/in_progress/ROADMAP.md @@ -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`). +- [ ] **Диалоговый аудит расхождений** + - [ ] Инструмент точечной выборки: «Кто сегодня не пришел из отдела ОВК?», «Покажи опоздавших за вчера». + - [ ] Быстрое внесение исключений и синонимов подразделений через диалог. ---