Первичная зашифрованная версия проекта
This commit is contained in:
@@ -0,0 +1,133 @@
|
||||
# Архитектура и документация проекта СКУД 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-файлов СКУД оператором.
|
||||
Reference in New Issue
Block a user