проект теперь работает с использованием локальной базы данных SQLite. Все данные аккумулируются и хранятся в ней. Впереди - разработка веб интерфейса.

2026-08-03 12:59:23 +03:00
parent d39618c891
commit 0efbe4ff99
14 changed files with 976 additions and 300 deletions
@@ -0,0 +1,115 @@
+# 🔄 ПАСПОРТ АЛГОРИТМА И 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С |