26 KiB
PROJECT BRAIN: SCUD Orion AI & Context API (Master Technical & Architectural Manifesto)
Версия документа: 5.0 (Ultimate Developer & LLM Context Engine)
Назначение: Исчерпывающий контекстный дамп проекта для немедленного продолжения разработки в любой передовой LLM без потери исторического контекста, с полным пониманием бизнес-логики, схем баз данных, подводных камней и нерешенных задач.
---
1. Архитектурный паспорт и инфраструктурный профиль
| Компонент | Параметры и стек |
|---|---|
| Среда и ОС | Linux Docker Home (Debian/Ubuntu), Python 3.11/3.12 в виртуальном окружении venv, Git/Gitea. Разработка ведется через VS Code Remote-SSH. |
| Локальная СУБД проекта | SQLite (data/scud_orion_ai.db), режим PRAGMA journal_mode = WAL, PRAGMA synchronous = NORMAL, PRAGMA foreign_keys = ON. |
| СКУД Источник (MSSQL) | MS SQL Server 172.16.31.221\SQL (база Orion-14.01.21-1), драйвер ODBC Driver 18 for SQL Server (TrustServerCertificate=yes, Encrypt=no). Доступ через pyodbc. |
| 1С:ЗУП 3.1 Источник (MSSQL) | MS SQL Server ACCOUNT-01 (база ZUP30, пользователь scud_reader). Прямое чтение таблиц dbo._Reference299 (сотрудники) и dbo._InfoRg16921 (состояния отсутствий). Резервная Samba-шара: /mnt/scud_share. |
| Локальный контур LLM | Ollama на http://192.168.11.3:11434 (GPU NVIDIA RTX 5070 Ti 16GB). Модель qwen2.5:14b (основной агент, Function Calling, анализ аномалий), qwen2.5vl:7b-q8_0 (OCR документов/картинок). |
| Web API & Фронтенд | FastAPI (Uvicorn), JWT (HS256, 30 дней), Passlib (bcrypt). Фронтенд: Single Page Application (HTML5, Tailwind CSS, Vanilla JS) с Generative UI виджетами. |
---
2. Энциклопедия подводных камней, инцидентов и принятых инженерных решений
2.1. Галлюцинации LLM и переход к парадигме Python-Driven Diff
- Проблема: Попытка передать списки в 300 ФИО напрямую в промпт модели с командой «сравни списки» приводила к потере контекста, выдуманным опечаткам («ЛЕНМОРНИИПРОЕКТ ОЭС Варламова Мария») и плейсхолдерам ('Васильев Л.И.', ...).
- Решение: Утверждена строгая гибридная схема:
- Детерминированный слой (Python / Pandas / SQL): читает файлы, нормализует строки, агрегирует совмещения и мгновенно находит 95%+ точных соответствий.
- Интеллектуальный слой (Qwen 2.5:14b): вызывается только на спорный несовпавший остаток (1–5 записей) в виде строгого JSON-интерфейса Entity Resolution.
2.2. Символьная нормализация и кадровые совмещения (Кейс Балаевой О.Г.)
- Проблема символов: Латинские омоглифы (буквы клавиатуры a, c, e, o, p, x, y вместо русских), разделители 1С в скобках ((осн.), (совм.), (внешн.)), неразрывные пробелы \xa0, буква ё и случайный ввод цифры 0 вместо буквы О.
- Решение (normalize_fio): Очистка скобок через регулярное выражение re.sub(r'\(.*?\)', '', fio), замена латиницы через str.maketrans('aceopxyABCEHKMOPTX', 'асеорхуАВСЕНКМОРТХ'), замена ё->е и удаление лишних пробелов.
- Коллизия 270 vs 271: В СКУД 270 физических лиц (один пропуск на человека), в 1С — 271 строка. Сотрудник Балаева Ольга Геннадьевна числится на двух ставках в разных отделах (Руководитель управления персоналом и Руководитель режимно-секретного отдела).
- Решение: Внедрена группировка датафрейма 1С по fio_clean с агрегацией должностей и подразделений через разделитель " / ".
2.3. Защита от коллизий полных тёзок и ложных связок однофамильцев (Кейс Семеновых)
- Инцидент: Неограниченная строгими правилами LLM связала двух разных сотрудниц — «Семенову Юлию Борисовну» (работает) и «Семенову Дину Дмитриевну» (в отпуске), посчитав разные имена опечаткой из-за одинаковой фамилии. В результате Юлии Борисовне ошибочно был приписан статус отпуска.
- Двухконтурный барьер:
- В промпте: Запрет объединения однофамильцев с разными именами/отчествами.
- В Python: Проверка совпадения первых букв имени и отчества. При несовпадении сопоставление ИИ аннулируется с логированием ⚠️ [Блокировка фейка].
2.4. Вынесение исключений в exceptions.json и синонимы отделов
- Служебный персонал (отдел «ЭТО», уборщики производственных и служебных помещений, клинеры, дворники, гардеробщики) вынесен в exceptions.json.
- Для сопоставления кратких аббревиатур СКУД и полных названий отделов 1С («ОВК» ⟷ «Отдел внутреннего контроля») создана таблица department_synonyms с автоматическим самообучением при работе человека (Human-in-the-Loop).
2.5. Разгадка феномена «исчезающих неизвестных» и аппаратный сбой СКУД 04.08.2026
- Аномалия: Утром 04.08.2026 на главном КПП зависли контроллеры входа. У 119 сотрудников не записалось утреннее событие (time_in = 'Нет входа'). Из них 57 человек были в отпусках/командировках по 1С. Оставшиеся 74 человека были на работе без утренней отметки. Однако вечерняя сводка показала всего 4–7 «неизвестных».
- Причина: Скрипт агрегации видел дневные перемещения (обед, внутренние двери, туалет, вечерний выход) и автоматически проставлял Статус = 'Присутствовал' и is_present = 1, несмотря на то, что колонка Начало_дня оставалась 'Нет входа'. В итоге 70 человек тихо ушли в «Итого на работе», а системный сбой оборудования был замаскирован.
- Архитектурный фикс:
- Введена колонка first_activity («Первая активность») — вычисление MIN(TimeVal) AS FirstRawEvent по таблице pLogData без учета направления двери.
- Если time_in == 'Нет входа', но first_activity != '—', записи ставится anomaly_flag = 'ANOMALY_NO_IN_HAS_ACTIVITY', а is_present принудительно сбрасывается в 0.
- Внедрен модуль analyze_scud_mass_failure_ai(): если доля таких аномалий превышает 5% смены (>10 чел.), ИИ генерирует системный алерт о массовом сбое контроллеров КПП.
- Кейс Равина В.Э.: Главный специалист официально находился в основном отпуске по 1С, утреннего входа на КПП не было, но зафиксирована активность в 14:11:06 и вечерний выход в 17:18:38. Система зарегистрировала истинную кадровую аномалию (физическое присутствие при официальном отпуске).
2.6. Система сквозных датированных снапшотов (срезов)
- Формат ID: [Y]YYYYMMDD-NNN (например, Y20260804-001 для вчерашнего зафиксированного вечернего среза на 22:00 и 20260805-002 для дневного).
- Оптимизация: Функция has_yesterday_final_snapshot() проверяет наличие вчерашнего среза в SQLite: если он есть, повторный тяжелый запрос к MS SQL Орион пропускается.
- CLI-управление: Поддержка запуска отчетов по любому историческому снапшоту через ключ --snapshot [ID] и пропуск выгрузки через --skip-export.
2.7. Web API, Generative UI и управление жизненным циклом сессий (Topic Drift & Ephemeral Buffer)
- Проблема засорения контекста LLM: Вывод объемных списков задач, системных промптов и таблиц срезов забивал окно диалога, вызывая галлюцинации и «залипание» модели на старых данных.
- Решение:
- В chat_messages введен флаг is_ephemeral = 1 для временных сообщений.
- Двухфазные сессии (PROMPT_PREVIEW → PROMPT_FOLLOWUP) и детерминированный счетчик idle_turns.
- Context Guard: На 3-м шаге отвлечения оператора на сторонние темы система отвечает на вопрос и выводит интерактивное напоминание с кнопками [Завершить настройку] / [Показать промпт]. При idle_turns > 3 происходит автоочистка сессии вызовом db_purge_ephemeral_messages().
- Fast-Path: Прямой перехват команд подтверждения («да», «подтверждаю») и выхода («нет, спасибо») без обращения к LLM (ответ за 0.05 сек).
- Декларативный реестр (tool_action_registry): Хранение шаблонов ответов, кнопок и настроек эфемерности в SQLite.
- Generative UI (Задачи): Инструмент db_get_tasks возвращает TASK_INTERACTIVE_CARD, рендерящий на клиенте живой виджет задач с табами (Все / В работе / В планах / Завершенные), чекбоксами и inline-созданием задач через REST API.
---
3. Полная схема базы данных SQLite (data/scud_orion_ai.db)
| Таблица | Назначение и бизнес-логика | Структура полей |
|---|---|---|
| scud_logs | Логи проходов СКУД, расчетное время в здании и снапшоты. | id INTEGER PK AUTOINCREMENT, log_date TEXT, fio TEXT, fio_clean TEXT, department TEXT, position TEXT, time_in TEXT, first_activity TEXT DEFAULT '—', time_out TEXT, time_in_building TEXT, is_present INTEGER, anomaly_flag TEXT DEFAULT 'NONE', snapshot_time TEXT, snapshot_id TEXT, created_at TIMESTAMP |
| zup_staff | Штатное расписание 1С:ЗУП на даты срезов. | id INTEGER PK AUTOINCREMENT, snapshot_date TEXT, fio TEXT, fio_clean TEXT, department TEXT, position TEXT, created_at TIMESTAMP |
| zup_absences | Документы отклонений 1С (отпуска, больничные, командировки, декреты). | id INTEGER PK AUTOINCREMENT, absence_date TEXT, fio TEXT, fio_clean TEXT, absence_type TEXT, created_at TIMESTAMP |
| anomalies_history | Журнал выявленных кадровых и аппаратных аномалий. | id INTEGER PK AUTOINCREMENT, anomaly_date TEXT, fio TEXT, anomaly_type TEXT, details TEXT, human_status TEXT DEFAULT 'Pending', created_at TIMESTAMP |
| ai_knowledge_base | Глобальные правила арбитража и приоритеты компании для ИИ. | id INTEGER PK AUTOINCREMENT, rule_text TEXT UNIQUE, added_by TEXT DEFAULT 'Human', created_at TIMESTAMP |
| system_prompts | Версионные системные промпты агента (активный по is_active=1). | id INTEGER PK AUTOINCREMENT, name TEXT, prompt_text TEXT, is_active INTEGER DEFAULT 1, updated_at TIMESTAMP |
| tool_action_registry | Декларативный реестр шаблонов, кнопок и настроек эфемерности инструментов. | id INTEGER PK AUTOINCREMENT, tool_name TEXT UNIQUE, category TEXT, bypass_llm INTEGER, success_template TEXT, follow_up_question TEXT, action_type TEXT, buttons_json TEXT, is_active INTEGER, is_ephemeral INTEGER, updated_at TIMESTAMP |
| session_states | Активные состояния сессий, черновики и счетчик idle_turns. | session_id TEXT PRIMARY KEY, state_type TEXT, pending_data TEXT, updated_at TIMESTAMP |
| chat_messages | История диалогов с поддержкой разделения на постоянные и эфемерные сообщения. | id INTEGER PK AUTOINCREMENT, session_id TEXT, role TEXT, content TEXT, is_ephemeral INTEGER DEFAULT 0, created_at TIMESTAMP |
| tasks | Реестр задач операторов с привязкой к user_id. | id INTEGER PK AUTOINCREMENT, task_id TEXT, module TEXT, title TEXT, priority TEXT, status TEXT, due_date TEXT, user_id INTEGER, created_at TIMESTAMP |
| users | Учетные записи операторов (хэши паролей bcrypt, права администратора). | id INTEGER PK AUTOINCREMENT, username TEXT UNIQUE, password_hash TEXT, is_admin INTEGER, full_name TEXT, created_at TIMESTAMP |
| department_synonyms | База соответствия аббревиатур СКУД полным названиям отделов 1С. | id INTEGER PK AUTOINCREMENT, short_name TEXT UNIQUE, full_name TEXT, created_at TIMESTAMP |
| system_reference | Справочник команд и примеров промптов для операторов. | id INTEGER PK AUTOINCREMENT, category TEXT, title TEXT, example_prompt TEXT, description TEXT |
---
4. Архитектурная структура каталогов
scud_ai/
├── config.py # Конфигурация: пути, расчет дат, URL Ollama, параметры MS SQL
├── exceptions.json # Декларативные фильтры исключений (ОВК, уборщики, подрядчики)
├── main_etl.py # Оркестратор ETL: экспорт СКУД/1С -> SQLite -> Excel/MD отчеты
├── project_code_snapshot.md # Полный монолитный исходный код всех файлов репозитория
├── core/
│ └── database.py # Драйвер SQLite (WAL), функции сохранения/загрузки срезов
├── services/
│ ├── scud_export.py # Прямой SQL-экспорт из MS SQL «Орион Pro»
│ ├── zup_extractor.py # Прямой SQL-экспорт из MS SQL 1С:ЗУП 3.1
│ ├── data_loader.py # Загрузка данных, нормализация ФИО, расчет первой активности
│ ├── data_validator.py # Проверка свежести и наличия файлов за Вчера и Сегодня
│ ├── excel_exporter.py # Генерация сводки и детального отчета в Excel (openpyxl)
│ ├── text_reporter.py # Построение итогового Markdown-отчета через Qwen 2.5
│ ├── ai_verifier.py # Модули ИИ-аудита, Fuzzy Matching и детекции сбоев СКУД
│ ├── feedback_loop.py # Интерактивный консольный модуль Human-in-the-Loop
│ ├── knowledge_base.py # Интерфейс работы с базой знаний правил
│ └── share_copier.py # Резервное скачивание файлов 1С с шары /mnt/scud_share
├── scripts/
│ ├── db_cli.py # CLI-утилита управления БД, снапшотами, дампами и сессиями
│ ├── fix_snapshots.py # Скрипт переиндексации и нормализации снапшотов
│ ├── init_tool_registry.py # Инициализация декларативного реестра инструментов
│ └── diagnostics/
│ ├── inspect_db.py # Диагностика структуры таблиц и количества записей
│ ├── inspect_ephemeral.py # Анализ распределения постоянных и эфемерных сообщений
│ ├── inspect_files.py # Аудит файлов и размеров на диске
│ └── show_tree.py # Вывод дерева каталогов
├── modules/web_api/
│ ├── main.py # Точка входа FastAPI приложения, роутеры и раздача статики
│ ├── routers/ (admin, auth, chat, tasks) # REST эндпоинты
│ ├── llm/
│ │ ├── agent.py # Координатор диалога, Tool Calls и Topic Drift Guard
│ │ ├── schemas.py # Описание JSON-схем инструментов для Ollama
│ │ ├── file_parser.py # Мультимодальный парсер файлов (PDF, PNG, XLSX, TXT)
│ │ ├── db_tools.py # Фасадные вызовы функций БД для агента
│ │ ├── core/ (calendar_utils, fast_path, ollama_client, prompt_merger, tool_injector)
│ │ └── db/ (connection, db_chat, db_prompts, db_snapshots, db_tasks)
│ └── static/ (index.html, css/styles.css, js/app.js, js/auth.js, js/chat.js, js/tasks.js)
└── docs/
└── development_roadmap.md # Стратегическая дорожная карта и архитектурный бэклог
---
5. Справочник команд CLI (HOWTO)
ETL Пайплайн (main_etl.py):
- python main_etl.py — стандартный дневной запуск (экспорт из MS SQL, сохранение снапшота, генерация отчетов).
- python main_etl.py --skip-export — построение отчетов по последнему имеющемуся снапшоту из SQLite без повторного запроса к MS SQL.
- python main_etl.py --snapshot 20260805-001 — точный расчет отчетов по указанному составному ID снапшота.
- python main_etl.py -d — запуск в режиме расширенной отладки (DEBUG).
CLI базы данных (scripts/db_cli.py):
- python scripts/db_cli.py stats — статистика по количеству строк во всех таблицах БД.
- python scripts/db_cli.py snapshots [ДД.ММ.ГГГГ] — просмотр реестра снапшотов с сортировкой по времени создания (свежие сверху).
- python scripts/db_cli.py scud [ДД.ММ.ГГГГ] [--snapshot ID] [--export-xlsx NAME] — инспекция логов СКУД и экспорт в Excel.
- python scripts/db_cli.py absences [ДД.ММ.ГГГГ] — список кадровых отклонений из 1С:ЗУП.
- python scripts/db_cli.py anomalies — история выявленных аномалий.
- python scripts/db_cli.py rules — правила базы знаний компании.
- python scripts/db_cli.py prompts — системные промпты из system_prompts.
- python scripts/db_cli.py tools — декларативный реестр действий инструментов и кнопок.
- python scripts/db_cli.py sessions — активные сессионные стейты и висящие черновики.
- python scripts/db_cli.py snapshot del [ID] — удаление конкретного снапшота по ID.
- python scripts/db_cli.py snapshot del --day [ДД.ММ.ГГГГ] — удаление всех снапшотов за день.
- python scripts/db_cli.py dump [backup.xlsx] — полный дамп всех таблиц базы данных в многостраничный Excel.
---
6. Стратегическая дорожная карта и нерешенные задачи (Roadmap & Backlog)
- Масштабирование механизма эфемерного контекста на все инструменты (Rollout Roadmap):
- Снапшоты (snapshots): Перевод вывода объемных таблиц срезов в эфемерный режим (is_ephemeral = 1), внедрение интерактивного подтверждения при удалении снапшотов по ID/дате через состояния SNAPSHOTS_PREVIEW / SNAPSHOTS_FOLLOWUP.
- База знаний и аномалии (kb & anomalies): Вывод справочников команд, правил арбитража и списков аномалий исключительно во временный слой для исключения «залипания» модели на устаревших правилах из истории сообщений.
- Декларативная унификация в tool_action_registry: Расширение схемы таблицы полями followup_state_type, auto_purge_on_exit, guard_question_template для устранения хардкода имен функций в agent.py.
- Модуль анализа внутридневных перемещений («Контроль перекуров»):
- Анализ интервалов между событиями OUT (выход) и IN (возврат) по журналу pLogData.
- Подсчет суммарного времени нахождения вне рабочего места в течение смены с отсечением технологической нормы (30–40 минут).
- Вывод аналитического блока и злостных нарушителей в отдельный лист Excel-отчета и итоговую Markdown-сводку.
- Интерактивный Task Planner & Roadmap Engine:
- Специализированный инструмент для ведения динамических проектных планов и чек-листов с чекбоксами ([ ] / [x]) прямо в диалоге с синхронизацией в таблицу tasks.
- Изолированная среда исполнения кода (Code Execution Sandbox):
- Безопасный изолированный Docker/gVisor контейнер для динамического выполнения генерируемого моделью Python/Pandas кода на лету с возвратом stdout/stderr и графиков в контекст.
- Автоматизация расписания срезов и Telegram-алерты:
- Автозапуск выгрузок в 12:00, 17:00 и 19:00 через systemd-таймеры с фиксацией snapshot_time.
- Отправка мгновенных алертов о массовых сбоях турникетов (>5%) и критических кадровых конфликтах дежурному системному администратору в Telegram.