промежуточный положительный результат. Отчеты коррктно формируются. Перед автоматической загрузкой файлов 1С.
This commit is contained in:
+67
-118
@@ -1,133 +1,82 @@
|
||||
# Архитектура и документация проекта СКУД v2
|
||||
# 📦 ПАСПОРТ СНАПШОТА ПРОЕКТА: `scud_orion_ai_v2`
|
||||
|
||||
## 1. Фактическая структура проекта
|
||||
> **Архитектура:** Автоматизированный конвейер кадрового контроллинга и детекции аномалий
|
||||
> **Интеграционный стек:** `СКУД «Орион Pro»` ⟷ `1С:ЗУП` ⟷ `AI-Аудитор`
|
||||
> **Статус:** 🟢 **Готовая боевая сборка** с прямой SQL-интеграцией, обработкой 1С-реестров и обучением на лету.
|
||||
|
||||
```text
|
||||
scud_root_v2/
|
||||
---
|
||||
|
||||
## 📁 Итоговая структура каталогов
|
||||
|
||||
```plaintext
|
||||
scud_orion_ai_v2/
|
||||
├── .gitignore # Настройки исключений отслеживания Git
|
||||
├── exceptions.json # Реестр постоянных исключений (ОВК, подрядчики, особые роли)
|
||||
├── knowledge_base.json # Динамическая база знаний (накопленные правила ИИ из режима Human-in-the-Loop)
|
||||
├── config.py # Глобальная конфигурация путей, моделей Ollama и функций нормализации
|
||||
├── main.py # Главный оркестратор (Этапы 0–5, логика слияния, детекция аномалий)
|
||||
│
|
||||
├── config.py # Конфигурация, глобальные пути (DATA_DIR, OUTPUT_DIR), даты (DATE_TODAY, DATE_YESTERDAY)
|
||||
├── exceptions.json # Фильтры исключений (ОВК, клинеры, конкретные ФИО)
|
||||
├── PROJECT_SNAPSHOT.md # 📄 Архитектурный снимок состояния проекта
|
||||
├── main.py # Главный скрипт запуска и оркестрации всего конвейера
|
||||
├── data/ # 📂 Папка входных сырых данных
|
||||
│ ├── scud/ # [Автовыгрузка СКУД] Файлы Сотрудники_ДД.ММ.ГГГГ.xlsx из MS SQL
|
||||
│ ├── 1c/ # [Кадровые реестры] Файлы из 1С:ЗУП:
|
||||
│ │ # • Штатные сотрудники - ОУП.xlsx
|
||||
│ │ # • Отсутствия сотрудников - выгрузка.xlsx
|
||||
│ └── static_reason_workers.csv# [Справочник] Реестр постоянных причин (Удаленка и т.д.)
|
||||
│
|
||||
├── data/ # 📂 Входные файлы (Выгрузки СКУД и 1С)
|
||||
│ ├── knowledge_base.json # Накопленная база знаний и динамические правила компании
|
||||
│ ├── Штатные сотрудники - ОУП.xlsx # Выгрузка штата из 1С
|
||||
│ ├── Отсутствия сотрудников - выгрузка.xlsx # Выгрузка докум. отсутствий из 1С
|
||||
│ ├── Сотрудники_24.07.2026.xlsx # Выгрузка СКУД за ВЧЕРА (для детального отчета)
|
||||
│ └── Сотрудники_27.07.2026.xlsx # Выгрузка СКУД за СЕГОДНЯ (для оперативной сводки)
|
||||
├── output/ # 📂 Результаты работы (Excel-сводки и ИИ-отчеты в Markdown)
|
||||
│ ├── Сводка_контроллинга_ДД.ММ.ГГГГ.md
|
||||
│ ├── ДД месяца ГГГГ сводка.xlsx
|
||||
│ └── ДД месяца ГГГГ отчет.xlsx
|
||||
│
|
||||
├── modules/ # 📂 Исполняемые модули системы
|
||||
│ ├── __init__.py
|
||||
│ ├── data_validator.py # 🛡️ Детерминированный контроль актуальности и свежести входных файлов СКУД/1С
|
||||
│ ├── data_loader.py # Загрузка и объединение Excel-выгрузок СКУД и 1С
|
||||
│ ├── ai_verifier.py # Интеграция с Ollama (qwen2.5:14b) для исправления опечаток в ФИО из СКУД
|
||||
│ ├── excel_exporter.py # 📊 Единый модуль генерации Excel-файлов (Сводка + Детальный отчет за вчера)
|
||||
│ ├── text_reporter.py # 📝 ИИ-аудитор (формирование текстовой сводки с проверкой совмещений)
|
||||
│ ├── knowledge_base.py # Чтение/запись динамических правил компании
|
||||
│ └── feedback_loop.py # Модуль обратной связи для обучения базы знаний
|
||||
│
|
||||
└── output/ # 📂 Результаты работы (генерируются автоматически):
|
||||
├── 26 июля 2026 отчет.xlsx
|
||||
├── 27 июля 2026 сводка.xlsx
|
||||
└── Сводка_контроллинга_27.07.2026.md
|
||||
└── 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Подробное описание модулей и их логики
|
||||
## 🛠️ Главные технические наработки и решённые задачи
|
||||
|
||||
### ⚙️ `config.py`
|
||||
**Константы:**
|
||||
- `OLLAMA_URL = "http://localhost:11434/api/chat"`
|
||||
- `OLLAMA_MODEL = "qwen2.5:14b"`
|
||||
- `DATE_TODAY`, `DATE_YESTERDAY` — расчет рабочих дат.
|
||||
### 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`):** Вывод детальной статистики в консоль (сколько в здании, сколько ушло, сколько отсутствовало).
|
||||
|
||||
**Основные функции:**
|
||||
- `normalize_fio()` — приводит ФИО к нижнему регистру, удаляет скобки `(...)`, меняет латинские визуальные дубликаты букв на кириллицу, заменяет `ё` на `е`.
|
||||
- `clean_scud_fio_light()` — облегченная очистка ФИО из СКУД от системных символов и артефактов.
|
||||
- `load_exceptions()` — загружает фильтры и исключения из `exceptions.json`.
|
||||
### 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.
|
||||
* Выведение отдельным блоком нумерованного списка истинно неизвестных случаев.
|
||||
* Отсутствие дублирования ФИО в разделе кадровых рекомендаций.
|
||||
|
||||
---
|
||||
|
||||
### 🛡️ `modules/data_validator.py`
|
||||
Модуль детерминированного контроля актуальности данных (**Data Quality & Freshness Control**).
|
||||
## 🚀 Команды для запуска снапшота
|
||||
|
||||
- Проверяет наличие файлов за сегодня и вчера в папке `data/`.
|
||||
- Проверяет дату и время изменения файлов (`mtime`), предотвращая запуск системы на устаревших выгрузках прошлого дня.
|
||||
- В случае отсутствия или устаревания данных блокирует запуск основного конвейера и предупреждает оператора.
|
||||
|
||||
---
|
||||
|
||||
### 🛡️ `exceptions.json`
|
||||
Содержит конфигурационные списки исключений, отфильтровываемые при сборе аналитики:
|
||||
- **Департаменты:** отдел ОВК и др.
|
||||
- **Должности:** Уборщик, Клинер, Дворник и т.д.
|
||||
- **Персональные исключения:** конкретные ФИО сотрудников или подрядчиков.
|
||||
|
||||
---
|
||||
|
||||
### 📥 `modules/data_loader.py`
|
||||
- Выполняет загрузку данных из папки `data/`.
|
||||
- Определяет факт присутствия на рабочем месте (`Пришел = True`, если зафиксирован проход в СКУД).
|
||||
- Применяет правила фильтрации `is_excluded()` на основе данных из `exceptions.json`.
|
||||
|
||||
---
|
||||
|
||||
### 🤖 `modules/ai_verifier.py`
|
||||
- Отправляет список нераспознанных ФИО из СКУД и эталонный список из 1С в модель Ollama (`qwen2.5:14b`).
|
||||
- Автоматически выявляет опечатки, несоответствия в написании и возвращает JSON сопоставлений.
|
||||
|
||||
---
|
||||
|
||||
### 📊 `modules/excel_exporter.py`
|
||||
Универсальный модуль формирования отчетов в формате Excel. Автоматически формирует имена файлов с названием месяца прописью (например, `27 июля 2026 сводка.xlsx` и `26 июля 2026 отчет.xlsx`).
|
||||
|
||||
#### 1. Оперативная сводка за сегодня (`generate_summary_excel`):
|
||||
- **Древовидная группировка:** Категория *«неизвестно»* раскрыта по умолчанию, остальные категории свернуты под плюсики `[+]` / `[-]`.
|
||||
- **Настройка структуры:** Принудительно включено отображение боковой панели со значками группировки через `showOutlineSymbols = True`.
|
||||
- **Палитра:**
|
||||
- Шапка: `#D9E1F2` *(Светло-голубой)*
|
||||
- По списку: `#F2F2F2` *(Светло-серый)*
|
||||
- Неизвестно: `#FCE4D6` *(Персиковый)*
|
||||
- Категории 1С: Циклическая пастельная палитра (`#FFF2CC`, `#E1D5E7`, `#E1F5FE`, `#FFF0F5`, `#E8F8F5`, `#FCF3CF`)
|
||||
- Итого на работе: `#E2EFDA` *(Светло-зеленый)*
|
||||
|
||||
#### 2. Детальный отчет за вчера (`generate_detailed_excel`):
|
||||
- **Динамическая ширина колонок:** Ширина столбцов рассчитывается по длине самого широкого значения ячеек.
|
||||
- **Столбец G (Причина отсутствия):** Ширина фиксирована на `25.0` (180 px), включен автоперенос текста (`wrap_text = True`) с адаптивным расширением высоты строк под длинные тексты.
|
||||
- **Цветовая маркировка:**
|
||||
- `#FFF2CC` *(Желтый)* — есть официальная причина в 1С.
|
||||
- `#FCE4D6` *(Светло-красный)* — приход отсутствует, документ в 1С не найден.
|
||||
|
||||
---
|
||||
|
||||
### 📝 `modules/text_reporter.py`
|
||||
- Формирует с помощью Ollama текстовую Markdown-сводку для руководства.
|
||||
- **Форматирование нумерованного списка неизвестных:** Строгий формат `N. ФИО — [Аббревиатура], Должность`.
|
||||
- **Контроль математики:** Количество человек в поле *«Неизвестно»* строго совпадает с количеством элементов в сгенерированном нумерованном списке.
|
||||
- **Подсветка аномалий:** Выявление совмещений и сотрудников с несколькими табельными номерами/картами СКУД (например, Кондрашова Е.В.).
|
||||
|
||||
---
|
||||
|
||||
### 🚀 `main.py`
|
||||
Главный исполнительный модуль системы. Координирует конвейер обработки:
|
||||
|
||||
1. `check_file_freshness()` — **Этап 0:** жесткая проверка свежести файлов.
|
||||
2. `load_all_data()` — загрузка реестров 1С и СКУД.
|
||||
3. `ai_verify()` — сопоставление опечаток в ФИО через ИИ.
|
||||
4. `merge()` — связывание, фильтрация и категоризация данных.
|
||||
5. **Генерация отчетов** — создание `[дата] сводка.xlsx` и `[дата] отчет.xlsx`.
|
||||
6. **Вывод ИИ-сводки** — формирование и сохранение текстового итогового отчета в `output/`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Текущие и будущие задачи
|
||||
|
||||
### 🗄️ Разворачивание локальной базы данных
|
||||
- Переход от плоских файлов Excel к локальной СУБД (SQLite / PostgreSQL).
|
||||
- Хранение истории проходов и статусов сотрудников с временными метками для быстрого формирования аналитики за любой выбранный период.
|
||||
|
||||
### 🔄 Переход на прямое подключение к СКУД через T-SQL
|
||||
- Настройка прямого подключения Python к базе данных СКУД через `pyodbc` / `sqlalchemy`.
|
||||
- Отказ от ручной выгрузки Excel-файлов СКУД оператором.
|
||||
| Режим запуска | Команда в терминале |
|
||||
| :--- | :--- |
|
||||
| **Стандартный запуск** *(Экспорт СКУД из SQL + ИИ Анализ)* | `python main.py` |
|
||||
| **Режим отладки** *(С детальными логами)* | `python main.py -d` |
|
||||
| **Без повторного обращения к SQL** *(На сохраненных файлах)* | `python main.py --skip-export` |
|
||||
| **Отладка только модуля выгрузки СКУД** | `python modules/scud_export.py -d` |
|
||||
|
||||
Reference in New Issue
Block a user