# 🔄 ПАСПОРТ АЛГОРИТМА И ETL-КОНВЕЙЕРА: `scud_orion_ai_v2`

> **Архитектурный паттерн:** Гибридный ETL (Extract, Transform, Load) с хранением аналитического следа  
> **Хранилище данных:** SQLite (режим WAL)  
> **Интеграционный стек:** `MS SQL Server` ⟷ `1С:ЗУП (SMB/Share)` ⟷ `Ollama (Qwen 2.5)` ⟷ `SQLite`

---

## 📐 Сквозной цикл работы проекта (`main.py`)

```plaintext
 [БД MS SQL 'Орион Pro']      [Сетевая шара \storage\...]
           │                                │
     (0. run_export)             (0.5 share_copier)
           ▼                                ▼
   [data/scud/*.xlsx]              [data/1c/*.xlsx]
           │                                │
           └────────────────┬───────────────┘
                            ▼
                (1. data_validator)  ──(Проверка фатальных ошибок)
                            │
                            ▼
                 (2. data_loader)    ──(Фоллбэки по датам)
                            │
                            ▼
              (3. ai_verifier + Qwen 2.5) ──(Исправление опечаток)
                            │
                            ▼
                   (4. Сведение данных)
                 ┌──────────┴──────────┐
                 ▼                     ▼
          [Данные за ВЧЕРА]    [Данные за СЕГОДНЯ]
                 │                     │
                 ▼                     ▼
        (Detailed Excel)       (Summary Excel + Markdown)
                 │                     │
                 └──────────┬──────────┘
                            ▼
                 (5. feedback_loop)   ──(Обучение ИИ)
                            │
                            ▼
            (database.py / SQLite WAL) ──(Сохранение фактов)
```

---

## 📋 Пошаговый алгоритм по этапам

### Этап 0: Извлечение сырых данных (Extract)

#### 1. БД СКУД «Орион Pro» $
ightarrow$ Excel (`scud_export.py`)
* Скрипт подключается напрямую к **MS SQL Server** системы «Орион Pro».
* Формирует агрегированные файлы `Сотрудники_DD.MM.YYYY.xlsx` в папку `data/scud/` отдельно за **Сегодня** и за **Вчера**.

#### 2. Сетевая шара $
ightarrow$ Папка `data/1c/` (`share_copier.py`)
* Заходит по UNC-пути `\storage\SCUD\Обмен\Штат`.
* Ищет и забирает свежие выгрузки **1С:ЗУП**: `Штат_DD_MM_YYYY.xlsx` и `Отсутствия_DD_MM_YYYY.xlsx` за Сегодня и Вчера.

---

### Этап 1: Валидация и защита от сбоев (`data_validator.py`)
* Проверяет наличие файлов за **Вчера** *(они критически важны для формирования ежедневного табеля)*.
* Если файлы за **Сегодня** ещё не выложены кадровой службой на сетевую шару:
  * Выдаёт мягкое предупреждение.
  * Отменяет генерацию сегодняшней сводки *(чтобы не плодить ложные аномалии по понедельникам/утрам)*.
  * Не останавливает работу системы, мягко переходя к формированию вчерашнего отчёта.

---

### Этап 2: Нормализация и загрузка (`data_loader.py`)
* Очищает и применительно нормализует ФИО через `normalize_fio`: удаление лишних пробелов, точек, приведение к единому регистру.
* Выделяет факты физического присутствия по СКУД *(наличие первого входа / последнего выхода)*.
* Исключает из анализа подрядчиков, охрану и служебные карты *(по реестру исключений)*.

---

### Этап 3: ИИ-аудит опечаток и сопоставление ФИО (`ai_verifier.py`)
* Неопознанные проходы СКУД отправляются в локальную нейросеть **Qwen 2.5** *(через Ollama)*.
* ИИ сверяет опечатки в СКУД с 100% эталонным реестром **Штатного расписания 1С**.
* Сопоставленные опечатки автоматически исправляются в датасете перед сведением.

---

### Этап 4: Бизнес-логика, сведение и детекция аномалий
Система разделяет контекст на два независимых потока:

#### 1. Поток ВЧЕРА (Детальный отчёт)
* Объединяет `СКУД (Вчера)` + `1С:Отсутствия (Вчера)`.
* Считает реальные часы нахождения в здании, обед (30 мин) и отклонение от 8-часовой нормы.
* Формирует Excel `output/[Дата] отчет.xlsx`.

#### 2. Поток СЕГОДНЯ (Ежедневная сводка)
* Объединяет `СКУД (Сегодня)` + `1С:Отсутствия (Сегодня)` + `Реестр удалёнщиков`.
* 🔴 **Детекция аномалий:** Физический приход по СКУД при наличии любого документа отсутствия в 1С *(отпуск, больничный и т.д., кроме командировок)* помечается как **Истинная Аномалия**.
* 🟢 **Удалёнщики:** Удалёнщики, пришедшие в офис, не считаются аномалией *(правило компании)*.
* Формирует Excel `output/[Дата] сводка.xlsx` *(со свернутыми группами без номеров строк)* и текстовую Markdown-сводку.

---

### Этап 5: Обучение Human-in-the-Loop (`feedback_loop.py`)
* Если ИИ находит спорные случаи, он запрашивает подтверждение оператора в консоли.
* Новые правила, введённые пользователем, мгновенно сохраняются и в `knowledge_base.json`, и в таблицу `ai_knowledge_base` в БД SQLite.

---

### Этап 6: Сохранение аналитического следа в БД (`database.py`)
Вся история сохраняется в локальную **SQLite БД** (`data/scud_orion_ai.db`) в режиме высокой производительности (**WAL / executemany**):

| Таблица | Содержимое |
| :--- | :--- |
| `scud_logs` | История всех проходов по дням |
| `zup_staff` | Срезы штатного расписания |
| `zup_absences` | Оформленные документы из 1С |
| `anomalies_history` | Найденные и подтверждённые нарушения |
| `ai_knowledge_base` | Обучающие правила для нейросети |