manoraga/scud_orion_ai_v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2fc417f3a7c3e783ba4f4b1df96cd229a9bb3a85
scud_orion_ai_v2/PROJECT_SNAPSHOT.md
T

10 KiB
Raw Blame History

Архитектура и документация проекта СКУД v2

1. Фактическая структура проекта

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 View Git Blame Copy Permalink