# Архитектура и документация проекта СКУД 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-файлов СКУД оператором.