scud_orion_ai_v2/PROJECT_SNAPSHOT.md

📦 ПАСПОРТ СНАПШОТА ПРОЕКТА: scud_orion_ai_v2

Архитектура: Автоматизированный конвейер кадрового контроллинга и детекции аномалий
Интеграционный стек: СКУД «Орион Pro» ⟷ 1С:ЗУП ⟷ AI-Аудитор
Статус: 🟢 Готовая боевая сборка с прямой SQL-интеграцией, обработкой 1С-реестров и обучением на лету.

---

📁 Итоговая структура каталогов

scud_orion_ai_v2/
├── .gitignore                   # Настройки исключений отслеживания Git
├── exceptions.json              # Реестр постоянных исключений (ОВК, подрядчики, особые роли)
├── knowledge_base.json          # Динамическая база знаний (накопленные правила ИИ из режима Human-in-the-Loop)
├── config.py                    # Глобальная конфигурация путей, моделей Ollama и функций нормализации
├── main.py                      # Главный оркестратор (Этапы 0–5, логика слияния, детекция аномалий)
│
├── data/                        # 📂 Папка входных сырых данных
│   ├── scud/                    # [Автовыгрузка СКУД] Файлы Сотрудники_ДД.ММ.ГГГГ.xlsx из MS SQL
│   ├── 1c/                      # [Кадровые реестры] Файлы из 1С:ЗУП:
│   │                            #   • Штатные сотрудники - ОУП.xlsx
│   │                            #   • Отсутствия сотрудников - выгрузка.xlsx
│   └── static_reason_workers.csv# [Справочник] Реестр постоянных причин (Удаленка и т.д.)
│
├── output/                      # 📂 Результаты работы (Excel-сводки и ИИ-отчеты в Markdown)
│   ├── Сводка_контроллинга_ДД.ММ.ГГГГ.md
│   ├── ДД месяца ГГГГ сводка.xlsx
│   └── ДД месяца ГГГГ отчет.xlsx
│
└── modules/                     # 📂 Функциональные ядро-модули
    ├── scud_export.py           # Модуль прямого подключения к MS SQL Server (Орион Pro)
    ├── data_loader.py           # Загрузка и первичная предобработка СКУД/1С файлов
    ├── data_validator.py        # Валидатор свежести и корректности входных таблиц
    ├── ai_verifier.py           # Интеграция с Ollama (Qwen2.5) для нечеткого поиска ФИО и опечаток
    ├── text_reporter.py         # Формирователь экспертного аналитического отчета ИИ
    ├── excel_exporter.py        # Генератор итоговых стилизованных Excel-отчетов
    ├── feedback_loop.py         # Модуль интерактивного обучения и дообучения ИИ (Human-in-the-Loop)
    └── knowledge_base.py        # Менеджер чтения/записи базы знаний knowledge_base.json

---

🛠️ Главные технические наработки и решённые задачи

1. Автоматический забор данных СКУД из БД MS SQL Server (scud_export.py)

• Прямой коннект: Запрос к БД СКУД Orion-14.01.21-1 через pyodbc.
• Высокая скорость (0.2 сек): Использование оконной функции ROW_NUMBER() OVER (PARTITION BY HozOrgan ORDER BY TimeVal DESC) для мгновенного сбора событий за 24 часа.
• Корректный учет текущего присутствия (СЕГОДНЯ):
  • Если день ещё не окончен и последнее событие — Вход, в колонке выводится Нет выхода.
  • Ограничено искажение времени для тех, кто ещё находится в здании или уходил на обед.
• Поддержка отладки (-d / --debug): Вывод детальной статистики в консоль (сколько в здании, сколько ушло, сколько отсутствовало).

2. Нормализация и ИИ-сборка данных (config.py + data_loader.py + ai_verifier.py)

• Удаление технического мусора: Автоматическая очистка служебных пометок 1С в скобках ((осн.), (совм.), (сводная)), предотвращающая расхождение ФИО.
• Умное слияние с 1С: Поиск опечаток и несопоставленных записей в реестре отсутствий через нейросеть Qwen2.5:14b.

3. Комплексный детектор аномалий (main.py)

Автоматическое пересечение всех 4 источников (СКУД + 1С + Статический реестр + Исключения) с перехватом конфликтов:

• 🔴 Критическая аномалия: Физический проход по СКУД при наличии оформленного документа в 1С (Отпуск / Больничный / Командировка).
• 🟠 Удалёнщик в офисе: Сотрудник числится на постоянной удалёнке, но пришёл через турникет.
• 🟡 Конфликт справочников: Нестыковка данных 1С:ЗУП и реестра статических причин.

4. Обучение на лету / Human-in-the-Loop (feedback_loop.py + knowledge_base.json)

• Запоминание правил: Если пользователь разрешает спорную ситуацию (например: «Незнанова иногда в офисе — не считать аномалией»), правило фиксируется в knowledge_base.json.
• Авто-фильтрация: Детектор аномалий проверяет Базу Знаний до формирования вопросов, избавляя пользователя от повторных уведомлений по решённым случаям.

5. Лаконичная аналитическая отчетность (text_reporter.py)

• Формирование строгой сводки в формате Markdown.
• Выведение отдельным блоком нумерованного списка истинно неизвестных случаев.
• Отсутствие дублирования ФИО в разделе кадровых рекомендаций.

---

🚀 Команды для запуска снапшота

Режим запуска	Команда в терминале
Стандартный запуск (Экспорт СКУД из SQL + ИИ Анализ)	python main.py
Режим отладки (С детальными логами)	python main.py -d
Без повторного обращения к SQL (На сохраненных файлах)	python main.py --skip-export
Отладка только модуля выгрузки СКУД	python modules/scud_export.py -d