133 lines
10 KiB
Markdown
133 lines
10 KiB
Markdown
# Архитектура и документация проекта СКУД v2
|
||
|
||
## 1. Фактическая структура проекта
|
||
|
||
```text
|
||
scud_root_v2/
|
||
│
|
||
├── config.py # Конфигурация, глобальные пути (DATA_DIR, OUTPUT_DIR), даты (DATE_TODAY, DATE_YESTERDAY)
|
||
├── exceptions.json # Фильтры исключений (ОВК, клинеры, конкретные ФИО)
|
||
├── PROJECT_SNAPSHOT.md # 📄 Архитектурный снимок состояния проекта
|
||
├── main.py # Главный скрипт запуска и оркестрации всего конвейера
|
||
│
|
||
├── data/ # 📂 Входные файлы (Выгрузки СКУД и 1С)
|
||
│ ├── knowledge_base.json # Накопленная база знаний и динамические правила компании
|
||
│ ├── Штатные сотрудники - ОУП.xlsx # Выгрузка штата из 1С
|
||
│ ├── Отсутствия сотрудников - выгрузка.xlsx # Выгрузка докум. отсутствий из 1С
|
||
│ ├── Сотрудники_24.07.2026.xlsx # Выгрузка СКУД за ВЧЕРА (для детального отчета)
|
||
│ └── Сотрудники_27.07.2026.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
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Подробное описание модулей и их логики
|
||
|
||
### ⚙️ `config.py`
|
||
**Константы:**
|
||
- `OLLAMA_URL = "http://localhost:11434/api/chat"`
|
||
- `OLLAMA_MODEL = "qwen2.5:14b"`
|
||
- `DATE_TODAY`, `DATE_YESTERDAY` — расчет рабочих дат.
|
||
|
||
**Основные функции:**
|
||
- `normalize_fio()` — приводит ФИО к нижнему регистру, удаляет скобки `(...)`, меняет латинские визуальные дубликаты букв на кириллицу, заменяет `ё` на `е`.
|
||
- `clean_scud_fio_light()` — облегченная очистка ФИО из СКУД от системных символов и артефактов.
|
||
- `load_exceptions()` — загружает фильтры и исключения из `exceptions.json`.
|
||
|
||
---
|
||
|
||
### 🛡️ `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-файлов СКУД оператором. |