Руководство по toir_tra_report

Текущая версия: 3.4

toir_tra_report — настольное приложение на Tkinter для подготовки пакетов документов ТОиР. Программа обрабатывает каталоги с исходными файлами, использует Excel-шаблоны и формирует целевые структуры для передачи в смежные команды.

Краткая история версий

• v3.4: Изменена логика формирования префиксов (-MOM-, -C-): теперь они добавляются к имени файла вне зависимости от наличия индекса документа в TZ_glob.xlsx. Исправлена опечатка в префиксе -MOM-.
• v3.3: Добавлена логика обработки файлов с меткой -MOM- (добавление префикса "Записник са састанка Организација рада"). Обновлен список отправителей.
• v3.2: Добавлен выбор отправителя трансмиттала с сохранением справочника в settings.json и автозаполнением именованной ячейки pripmem в шаблоне.
• v2.7: Учтена периодичность из TZ_glob.xlsx (колонка E) при подборе суффиксов и транслитерация значений М/Г → M/G.
• v2.6: Актуализированы шаблоны формирования документов и настройки UI.

Основные возможности

• Подготовка Excel-пакетов (CT-*-TRA-PRM-*.xlsx) по выбранным статусам.
• Выбор и сохранение отправителя трансмиттала с автоматическим заполнением шаблонов.
• Формирование индексных папок: группировка файлов CT-DR-* по ключам, основанным на колонках B/E/H файла TZ_glob.xlsx с привязкой суффиксов из колонки G.
• Создание ZIP-архивов и опциональное удаление исходных файлов после выгрузки.
• Генерация CMM-комментариев с шаблоном Template/CommentSheet_Template.xltx.
• Быстрый выбор компаний и статусов, сохранение пользовательских путей в settings.json.

Установка и запуск

1. Установите Python 3.11+ и создайте виртуальное окружение:

   python -m venv .venv
   .\.venv\Scripts\activate

2. Установите зависимости:

   pip install -r requirements.txt

   При необходимости используйте pip-compile requirements.in для обновления requirements.txt.

3. Запустите приложение:

   python toir_tra_report_v1.py

Структура проекта

• toir_tra_report_v1.py — основной GUI.
• index_folder_builder.py — логика формирования индексных папок и работы с TZ_glob.xlsx.
• cmm_builder.py — помощник по CMM-отчётам.
• Template/ — исходные шаблоны и справочник TZ_glob.xlsx.
• settings.json — пользовательские настройки путей, компаний (company_names) и отправителей трансмитталов (senders).
• tests/ — модульные тесты (pytest).

Формирование индексных папок

1. Выберите исходный каталог (CT-DR-*) и целевую папку назначения.
2. Укажите режим копирования или перемещения файлов.
3. При нажатии «Сформировать» выполняется группировка по шаблону IV.2.3-02-6M:
   • Колонка B TZ_glob.xlsx — базовый индекс (с учётом латиницы/кириллицы).
   • Колонка E — периодичность. Значения М/м преобразуются в M, Г/г — в G, остальные символы оставляются как есть.
   • Колонка H — код Reserved (нормализуется до двух символов).
   • Колонка G — возвращаемый суффикс, добавляемый к названию каталога.
4. Итоговая папка формируется как <индекс>-<reserved>-<periodicity>_<суффикс>, например: I.5.8-02-6M_CT.
5. Если опция «Группировать по суффиксу» активна, создаются подпапки по суффиксу (например, CT/I.5.8-02-6M_CT).
6. При отсутствии строки в TZ_glob.xlsx для комбинации (B, E, H) приложение сообщает об ошибке и пропускает группу.

Формирование пакетов шаблонов

1. Выберите папку с шаблонами (должна содержать Template/template_tra).
2. Отметьте статус и шаблон для генерации.
3. Укажите параметры: архивирование, удаление исходников, выбор компании.
4. Выполните запуск и дождитесь сообщений о готовности.

Быстрый запуск из кода

from pathlib import Path

from index_folder_builder import prepare_index_folders

prepare_index_folders(
    source_dir=Path("input"),
    destination_dir=Path("output"),
    tz_file_path=Path("Template/TZ_glob.xlsx"),
    use_copy=True,
    group_by_suffix=True,
)

Сборка исполняемого файла

pyinstaller --onefile --windowed
  --name toir_tra_report_v3.4
  --icon=assets/icon_toir_tra_report.ico
  --add-data "Template;Template"
  toir_tra_report_v1.py

Перед сборкой убедитесь, что settings.json и папка Template находятся рядом с исполняемым файлом: приложение ожидает эти данные по относительным путям.

Тестирование и проверка качества

• Запуск модульных тестов: pytest -q
• Линтер: ruff check .
• Форматирование: black --check .
• Статический анализ: mypy . (потребуются типы для openpyxl, например pip install types-openpyxl)

Известные ограничения

• При расхождении между данными TZ_glob.xlsx и именами файлов цепочка сопоставления потребует ручной корректировки справочника.
• Расширенные обозначения периодичности (отличные от M/G) нужно добавить в таблицу соответствий в index_folder_builder.py.
• black --check и mypy могут сообщать о проблемах в legacy-модулях (cmm_builder.py, toir_tra_report_v1.py) — устраните их перед публика