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

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

---

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

```plaintext
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` |