scud_ai/docs/in_progress/ROADMAP.md

План реализации (ROADMAP)

1. Очистка от регулярок и костылей (tool_injector.py) [ЗАВЕРШЕНО]

• Полностью удалить принудительные перехваты текста регулярными выражениями для команд добавления, редактирования и удаления пунктов.
• Оставить в модуле только базовую санитарную очистку сырых тегов (<tool_call>).

---

2. Настройка контекста и инструкций сессии (agent.py) [ЗАВЕРШЕНО]

• Передать управление диалогом языковой модели через системный блок role: "system".
• При активном состоянии PROMPT_PREVIEW передавать модели инструкцию:
  • Подтверждение / отмена / корректировка: продолжать работу с превью и вызывать соответствующие инструменты.
  • Смена темы: вежливо напомнить об открытом изменении и запросить решение.
• Обеспечить видимость эфемерных сообщений (is_ephemeral = 1) для модели во время активной работы с превью.
• Внедрить семантический Topic Drift Guard (idle_turns = 3) с вопросами и кнопками из tool_action_registry.
• Реализовать детерминированный мгновенный сброс сессии и зачистку эфемерного контекста при вызове сторонних инструментов.

---

3. Очистка эфемерных сообщений при завершении (fast_path.py / context_manager.py) [ЗАВЕРШЕНО]

• Настроить удаление временных сообщений превью (db_purge_ephemeral_messages) строго в момент нажатия кнопок «Подтвердить» или «Отменить».
• Сбрасывать состояние сессии в базе данных после фиксации решения.
• Внедрить прямое точечное применение изменений через db_apply_prompt_node_action.
• Добавить обработку фазы PROMPT_FOLLOWUP с кнопками завершения и очистки контекста.
• Создать context_manager.py для строгого разграничения служебных tool-пар (is_ephemeral=1) и содержательного диалога (is_ephemeral=0), сохраняя беседы Topic Drift в истории.

---

4. Инлайн-редактор в окне диалога (core.js) [ЗАВЕРШЕНО]

• Проверить работу блока ручного редактирования (inline-prompt-editor-container) с кнопками «Сохранить правки» и «Свернуть».
• Обеспечить сохранение черновика через API (/api/v1/chat/draft) и отображение обновленного текста перед подтверждением.
• Реализовать двусторонний клиентский Diff-рендерер (одновременная подсветка добавленных строк и зачеркивание удаленных [УДАЛЕНИЕ]).
• Добавить авто-форматирование и отступы подпунктов (X.Y.) при ручном сохранении черновика.

---

5. Тестирование и валидация системного промпта [ЗАВЕРШЕНО]

• Нативные вызовы: проверить добавление, редактирование и удаление пунктов через нативные вызовы модели (db_prompt_node_edit).
• Контекстные сценарии: проверить поведение модели при смене темы диалога оператором (Guardrail).
• UI и очистка: проверить ручное редактирование через кнопку в окне чата и последующую очистку контекста (db_purge_ephemeral_messages).
• Строгий вызов Базы Знаний: внедрено правило 2.9 в системный промпт для пресечения текстовой имитации вызова db_get_rules.

---

6. Распространение архитектурного паттерна на модуль задач (tasks) [ЗАВЕРШЕНО]

• Масштабирование UI задач:
  • Увеличена ширина карточки до max-w-4xl и динамическая высота скролла до 70vh.
  • Реализованы переключатели фильтрации: «В работе» (по умолчанию), «В планах», «Готово», «Все».
  • Разделены кнопки действия: «В работу» (для плановых) и «Готово» (для текущих).
• Инлайн-редактирование карточки задачи:
  • Плавная трансформация карточки в 3-строчную форму (текст, дата со встроенным пикером, выпадающий список важности).
  • Отображение даты создания задачи.
  • Сохранение через REST API эндпоинт PATCH /api/v1/tasks/{id}.
• Детерминированный Fast-Path и двухфазное удаление:
  • Мгновенная смена статусов без задержек LLM.
  • Карточка подтверждения удаления с автоочисткой контекста.
• Генерация отчетов задач в Markdown:
  • Добавлен инструмент db_export_tasks_markdown для формирования Markdown-файла с группировкой по модулям и чекбоксами [x] / [ ].
  • Реализован роутер безопасной отдачи файлов с сохранением имени (/api/v1/files/download/...).
• Доменная консолидация задач:
  • Реализован консолидированный инструмент db_tasks_edit(action: ["ADD", "UPDATE", "DELETE", "EXPORT"], ...).

---

7. Распространение на модуль снапшотов (snapshots) [ЗАВЕРШЕНО]

• Поддержка Y-снапшотов: универсальный парсинг и поиск по snapshot_id LIKE 'Y%' и срезам за 22:00:00.
• Single Active Snapshot View: сохранение активного среза в контексте для аналитики с автоматической ротацией и зачисткой при запросе новых дат.
• Интерактивный UI с чекбоксами и защитой срезов:
  • Чекбоксы в строках дневных срезов и кнопка «Выбрать все» в шапке.
  • Защита итогового вечернего среза Y (иконка замочка 🔒, блокировка выбора).
  • Динамическая кнопка «Удалить выбранные (N)» в подвале карточки.
• Детерминированный Fast-Path удаления срезов:
  • Двухфазное подтверждение удаления (одиночное и пакетное) с корректным счётчиком количества удаляемых элементов.
  • Защита от сброса фильтра даты (query_date) при обновлении карточки после удаления.

---

8. Глубокий архитектурный рефакторинг ядра и сервисов [ЗАВЕРШЕНО]

• Выделение общего слоя ядра (core/):
  • Изолированный пул соединений SQLite (core/connection.py) с поддержкой WAL и таймаутов.
  • DDL-схемы таблиц и индексов (core/schema.py).
  • Репозитории СКУД и 1С (core/repositories/scud_repo.py, core/repositories/zup_repo.py).
  • Фасад обратной совместимости (core/database.py).
• Декомпозиция предметных доменов (services/):
  • Сервис задач (services/tasks/), системного промпта (services/prompts/), срезов СКУД (services/snapshots/), базы знаний (services/knowledge/).
• Рефакторинг ETL-конвейера (services/scud_etl/):
  • Оркестратор pipeline.py, детектор аномалий anomaly_detector.py, слияние merger.py.
• Модульный ИИ-оркестратор (modules/ai_engine/):
  • Динамический строитель системного контекста (context_builder.py).
  • Изолированные обработчики инструментов в handlers/.

---

9. Реляционный реестр исключений, схлопывание мульти-пропусков и автозакрытие 8.5ч [ЗАВЕРШЕНО]

• Реестр исключений в SQLite (exceptions_registry):
  • Хранение категорий departments, positions, fio, position_keywords, include_fio в БД.
  • Доменный сервис exceptions_repo.py и полная поддержка в CLI scripts/db_cli.py exceptions.
• Агрегация мульти-пропусков физлиц в СКУД:
  • Функция aggregate_scud_by_person в merger.py: объединение событий всех пропусков одного человека (ранний вход, поздний выход, присутствие).
  • Автоматическая фиксация аномалий дублирования пропусков (DUPLICATE_SCUD_CARD).
• Умный выбор ставки совместителей 1С:ЗУП:
  • Функция select_best_zup_position в merger.py: привязка ставки 1С по подразделению физического нахождения в СКУД.
• Автозакрытие смен по Правилу 8.5ч:
  • Для забывших отметиться на выходе офисных сотрудников: автоматический расчет Вход + 8ч 30мин, норма 8 часов и отклонение 0:00 в excel_exporter.py.
• Кэш сопоставлений личностей (person_identity_mapping):
  • Таблица в SQLite и команды db_cli.py mapping [list|add|del].
  • Теневой режим ИИ-подсказок по нечетким ФИО в text_reporter.py.
• Каскадный fallback кадровых отсутствий:
  • MS SQL ЗУП \rightarrow резервный парсинг Отсутствия_*.xlsx \rightarrow static_reason_workers.csv.

---

10. Разделение генераторов и почасовые срезы [ЗАВЕРШЕНО]

• Разделение логики генерации на svodka_generator.py и otchet_generator.py.
• Перевод времени суточного среза Y на 23:59:59.
• Интеллектуальный поиск срезов services/snapshots/finder.py (Snap-to-Grid ±20 мин).
• Флаг --time и интерактивный help в main_etl.py.
• Флаг --export-only для почасового крона.
• Политика ночной ротации промежуточных срезов services/snapshots/retention.py.
• Исправление целочисленного инкремента snapshot_id.

---

11. Стабилизация генератора отчетов и верстки [ЗАВЕРШЕНО]

• Миграция на XlsxWriter: полный перевод экспорта книг (scud_export.py, excel_exporter.py) на чистый генератор, устранивший ошибки OpenXML и окна восстановления при открытии.
• Интерактивные группировки в Сводке: восстановление сворачивания категорий по умолчанию (level=1, collapsed=True) и кнопок управления уровнями [+]/[-] (outline_settings(symbols_below=False)).
• Компактная экранная верстка Детального отчета: центрирование столбца «Подразделение», расширение столбца «ФИО» (+10%, ширина 33), оптимизация ширины колонок «Первая активность» (11) и «Отклонение от нормы» (11) для отображения без горизонтальной прокрутки.
• Защита от блокировок занятых файлов (Fallback Timestamp): механизм перехвата FileCreateError/OSError в safe_close_workbook с сохранением копии при открытом в Excel файле.
• Безопасная синхронизация 1С с сетевой шары: переход на shutil.copyfile в share_copier.py для устранения сбоев прав доступа (Operation not permitted) на SMB/CIFS-ресурсах.

---

12. UI/UX веб-интерфейса и скроллинг ленты сообщений [ЗАВЕРШЕНО]

• Паттерн Gemini-скролла: реализация функции scrollToUserMessageTop в core.js, позиционирующей свежий вопрос пользователя строго по верхней кромке видимой области.
• Полное скрытие истории: предыдущие объемные ответы модели гарантированно вытесняются за верхний край экрана.
• Стабилизация панели ввода: настройка padding-bottom: 80vh для #chat-messages-container в index.html, обеспечивающая необходимый запас высоты прокрутки без сдвига строки ввода текста.

---

13. Интеллектуальный кадровый арбитраж ДО генерации отчетов [В ПЛАНАХ]

• Двухконтурный вызов ИИ: перенос арбитража не сопоставившихся персон на этап [2.5] ДО сохранения Excel-файлов сводка.xlsx и отчет.xlsx.
• Якорный табельный номер (TabNo Matching):
  • Извлечение TabNo из MS SQL СКУД Орион и 1С:ЗУП.
  • Добавление колонок scud_tab_no и zup_tab_no в SQLite.
  • Защита от смены фамилий и опечаток через инвариант табельного номера.
• 4-уровневая система предохранителей (Guardrails):
  • Уровень 1: Точный матч ФИО (100%).
  • Уровень 2: Матч по табельному номеру при расхождении ФИО.
  • Уровень 3: Валидация кэша person_identity_mapping с проверкой актуальности статуса в 1С.
  • Уровень 4: ИИ-арбитраж с записью верифицированной связки в кэш.

---

14. Изолированная песочница кода (Code Execution Sandbox Engine) [В ПЛАНАХ]

• Docker/gVisor контур:
  • Создание изолированного контейнера без доступа к внешней сети (network: none) с ограниченными лимитами по памяти и CPU (cgroups).
  • Настройка безопасного монтирования только необходимых CSV/Parquet-файлов данных в режиме Read-Only.
• Динамические Python/Pandas вычисления:
  • Инструмент генерации и безопасного выполнения скриптов агрегации и аналитики данных СКУД / 1С на лету.
  • Перехват stdout/stderr, сбор результатов расчетов и графиков с передачей в UI-чата.

---

15. Архитектура обработки событий турникетов и детализация проходов (Сырые логи СКУД) [В РАБОТЕ]

• Итерация 1: Устранение фантомных выходов в боевом SQL (scud_export.py):
  • Перестроить блок CASE WHEN определения Direction: приоритет отдавать физическому направлению контроллера (log.Mode = 1 -> 'IN', log.Mode = 2 -> 'OUT').
  • Исключить универсальные коды событий 28 (разблокировка створки) и 32 (проворот турникета) из жесткого перечня 'IN', так как они зеркальны для обоих направлений.
  • Закрепить расчет первого входа FirstIn и последнего выхода FilteredLastOut (строго OUT позже FirstIn).
• Итерация 2: DDL-схема и таблица сырых событий (core/schema.py):
  • Создать таблицу scud_events_raw (поля: log_date, time_val, hoz_organ, fio_clean, event_code, mode, direction, created_at).
  • Настроить индексы idx_raw_date_fio и idx_raw_mode для быстрых выборок.
• Итерация 3: Конвейер выгрузки сырых событий (services/scud_export.py):
  • Добавить сохранение всех фактов физических проходов (Event = 32 / Event = 28) в scud_events_raw параллельно с формированием агрегированного снапшота в scud_logs.
• Итерация 4: Модуль оперативного присутствия и внутридневного учета:
  • Реализовать инструмент «Кто прямо сейчас в здании» по последнему зафиксированному Mode сотрудника за текущие сутки.
  • Подготовить расчет реального суммарного времени нахождения на рабочем месте с учетом перекуров, обедов и выходов за периметр.