Стилистическое редактирование

README.md

@@ -1,53 +1,56 @@
-# AE Anons - Automated After Effects Announcement Generator
+# AE Anons - Автоматизированный генератор спортивных анонсов After Effects
 
-Automated pipeline for generating sports announcements using After Effects templates via Nexrender, with data sourced from Synology Office spreadsheets.
+Автоматизированная система для создания спортивных анонсов с использованием шаблонов After Effects через Nexrender, с данными из электронных таблиц Synology Office.
 
-## Overview
+## Обзор
 
-AE Anons automates the creation of broadcast announcement videos by:
+AE Anons автоматизирует создание видеороликов спортивных анонсов путем:
 
-1. Connecting to Synology NAS to retrieve schedule data from Office spreadsheets (.osheet)
-2. Parsing Excel data containing sports events, teams, channels and timing information
-3. Generating Nexrender jobs with appropriate templates and assets
-4. Monitoring render completion and managing output files
+1. Подключения к NAS Synology для получения данных расписания из файлов офисных таблиц (.osheet)
+2. Парсинга Excel данных, содержащих информацию о спортивных событиях, командах, каналах и временных интервалах
+3. Генерации заданий Nexrender с соответствующими шаблонами и ресурсами
+4. Мониторинга завершения рендеринга и управления выходными файлами
 
-## Features
+## Особенности
 
-- **Synology Integration**: Seamless authentication and file retrieval from Synology NAS
-- **Office Spreadsheet Export**: Automatic conversion of .osheet files to Excel format
-- **Flexible Data Parsing**: Dynamic sheet parsing with header detection
-- **Multi-variant Generation**: Creates "Today", "Tomorrow" and dated variants for each announcement
-- **Smart Logo Management**: Automatic logo resolution and scaling based on team/sport associations
-- **Nexrender Job Orchestration**: Automated job submission, monitoring and cleanup
-- **Professional Logging**: Structured logging with configurable verbosity levels
-- **Environment-based Configuration**: All settings managed via `.env` file
+- **Интеграция с Synology**: Плавная аутентификация и загрузка файлов с NAS Synology
+- **Экспорт офисных таблиц**: Автоматическое преобразование файлов .osheet в формат Excel
+- **Гибкий парсинг данных**: Динамический парсинг листов с обнаружением заголовков
+- **Множественная генерация вариантов**: Создание "Сегодня", "Завтра" и датированных версий для каждого анонса
+- **Умное управление логотипами**: Автоматическое разрешение и масштабирование логотипов на основе связей команд/спорта
+- **Оркестрация заданий Nexrender**: Автоматическая отправка, мониторинг и очистка заданий
+- **Профессиональное логирование**: Структурированный журнал с возможностью настройки уровня детализации
+- **Конфигурация через переменные окружения**: Все параметры управляются через файл `.env`
 
-## Prerequisites
+## Предварительные требования
 
-- Rust 1.70 or higher
-- Access to Synology NAS with File Station and Office enabled
-- Nexrender server instance
-- After Effects templates configured on render nodes
+- Rust 1.70 или выше
+- Доступ к NAS Synology с включенными File Station и Office
+- Экземпляр сервера Nexrender
+- Шаблоны After Effects, настроенные на узлах рендеринга (формат Adobe After Effects 2024 .aepx)
 
-## Installation
+## Установка
 
-### 1. Clone the Repository
+### 1. Клонирование репозитория
 
 ```bash
 git clone https://github.com/your-org/ae_anons.git
 cd ae_anons
+```
 
-2. Build the Project
-bash
+### 2. Сборка проекта
 
+```bash
 cargo build --release
+```
 
-The binary will be available at target/release/ae_anons
-3. Configure Environment
+Бинарный файл будет доступен по пути `target/release/ae_anons`
 
-Create a .env file in the project root:
-env
+### 3. Настройка окружения
 
+Создайте файл `.env` в корне проекта:
+
+```env
 NAS_FQDN=https://your-synology-nas.example.com:5001
 NAS_USER=service_account
 NAS_PASS=secure_password
@@ -55,292 +58,291 @@ NAS_FILE=/Team Folder/Broadcast/Auto_Anons/schedule.osheet
 NEXRENDER_API_URL=http://nexrender-server:3000/api/v1/jobs
 OUTPUT_FOLDER=//file-server/edit/Auto_Anons
 RUST_LOG=info
+```
 
-See Configuration section for detailed options.
-Usage
-Basic Execution
-bash
+См. раздел Конфигурация для подробной информации.
 
-# Run with default configuration
+## Использование
+
+### Базовое выполнение
+
+```bash
+# Запуск с настройками по умолчанию
 ./target/release/ae_anons
 
-# Run with custom log level
+# Запуск с пользовательским уровнем логирования
 RUST_LOG=debug ./target/release/ae_anons
+```
 
-# Run with specific .env file
-dotenv -f /path/to/.env.production run ./target/release/ae_anons
+## Уровни логирования
 
-Development Mode
-bash
+Управляйте детализацией вывода через переменную окружения `RUST_LOG`:
 
-cargo run
-
-Logging Levels
-
-Control output verbosity via RUST_LOG environment variable:
-
-    error - Only critical errors
-
-    warn - Warnings and errors
-
-    info - General operational messages (default)
-
-    debug - Detailed processing information
-
-    trace - Full debugging with API call details
-
-bash
+- **error** - Только критические ошибки
+- **warn** - Предупреждения и ошибки  
+- **info** - Общие операционные сообщения (по умолчанию)
+- **debug** - Детальная информация о процессе обработки
+- **trace** - Полное отладочное логирование с деталями API вызовов
 
+```bash
 RUST_LOG=debug cargo run
+```
 
-Configuration
-Environment Variables
-Variable Required Default Description
-NAS_FQDN Yes - Synology NAS URL with protocol and port
-NAS_USER Yes - Synology account username
-NAS_PASS Yes - Synology account password
-NAS_FILE Yes - Full path to .osheet file on NAS
-NEXRENDER_API_URL 
-OUTPUT_FOLDER Network path for rendered videos
-RUST_LOG No info Logging verbosity level
-Spreadsheet Structure
+## Конфигурация
 
-The input Excel file (converted from .osheet) must contain the following sheets:
-Start Sheet
+### Переменные окружения
 
-Main data source for announcements generation.
-Column Description Example
-STATE Processing flag FALSE (active), TRUE (skip)
-SPORT Sport category Футбол, Хоккей
-LEAGUE League name Премьер-лига
-TEAM A Home team Спартак#FC Spartak#150
-TEAM B Away team Зенит#FC Zenit#150
-CHANEL Broadcast channel Матч ТВ
-TIME Event time 19:30
-DATA Event date 15.04.2026
-SPORT Sheet
+| Переменная | Обязательна | Описание |
+|------------|-------------|----------|
+| `NAS_FQDN` | Да | URL NAS Synology с протоколом и портом |
+| `NAS_USER` | Да | Имя пользователя учетной записи Synology |
+| `NAS_PASS` | Да | Пароль учетной записи Synology |
+| `NAS_FILE` | Да | Полный путь к файлу .osheet на NAS |
+| `NEXRENDER_API_URL` | Да | Конечная точка API сервера Nexrender |
+| `OUTPUT_FOLDER` | Да | Сетевой путь для рендеренных видео |
+| `RUST_LOG` | Нет | Уровень детализации логирования (по умолчанию: info) |
 
-Mapping between sports and their video pack templates.
-Column Description
-SPORT Sport identifier
-LINK Path to video pack file
-TEAMS Sheet
+## Структура электронной таблицы
 
-Team logo registry with sport associations.
-Column Description
-TEAM Team identifier
-SPORT Associated sport
-LINK Path to team logo file
-CHANELL Sheet
+Файл Excel должен содержать следующие листы со специфичными структурами:
 
-Channel logo mappings.
-Column Description
-CHANELL Channel name
-LINK Path to channel logo file
-Team Name Format
+### Лист "SPORT"
 
-Team names can include resolution hints using hash separators:
-text
+Связывает названия видов спорта с соответствующими видео пакетами.
 
-Display Name#Search Key#Target Size
+| SPORT | LINK |
+|-------|------|
+| Без оформления | \\server\share\path\to\null.mov |
+| Футбол | \\server\share\path\to\football_pack.mov |
+| Волейбол | \\server\share\path\to\volleyball_pack.mov |
 
-Example: Спартак#FC Spartak#150
+### Лист "TEAMS"
 
-    Спартак - Display name in graphics
+Сопоставляет имена команд с их видами спорта и логотипами. Колонка SPORT заполняется из выпадающего списка (заполнена из листа SPORT).
 
-    FC Spartak - Key for logo lookup
+Если несколько команд в одном виде спорта имеют одинаковые названия, но разные логотипы, используется разделитель хеш # для уникальной идентификации.
 
-    150 - Target size in pixels for logo scaling
+| TEAM | SPORT | LINK |
+|------|-------|------|
+| Галатасарай#Turki | Футбол | \\server\share\path\to\galatasaray_football.png |
+| Галатасарай | Волейбол | \\server\share\path\to\galatasaray_volleyball.png |
+| Галатасарай#UCL | Волейбол | \\server\share\path\to\galatasaray_ucl.png |
+| Сомбатей##400 | Футбол | \\server\share\path\to\szombathely.png |
 
-Output Files
-JSON Exports
+### Лист "CHANELL"
 
-During processing, JSON representations of the workbook are saved:
+Сопоставляет названия каналов с их логотипами. Поля заполняются вручную без выпадающих списков.
 
-    {filename}_workbook.json - Complete workbook structure
+| CHANEL | LINK |
+|--------|------|
+| КАНАЛ | \\server\share\path\to\channel_logo.png |
+| TRIUMPH | \\server\share\path\to\triumph_logo.png |
 
-    {filename}_{SheetName}.json - Individual sheet data
+### Лист "Start"
 
-Rendered Videos
+Основной источник данных для генерации анонсов. Большинство полей заполняются из выпадающих списков, основанных на других листах.
 
-Output videos are saved to OUTPUT_FOLDER with naming pattern:
-text
+Обязательные колонки: DATA, TIME, CHANEL, SPORT, LEAGUE, TEAM A, TEAM B
 
+**Примечание**: Колонка LEAGUE обязательна для заполнения, но не имеет выпадающего списка. Проверка орфографии и опечаток отсутствует!
+
+| STATE | TRIPPLE | DATA | TIME | SPORT | LEAGUE | CHANEL | TEAM A | TEAM B |
+|-------|---------|------|------|-------|--------|--------|--------|--------|
+| TRUE | TRUE | 27.2.2026 | 23:40 | Футбол | Чемпионат Португалии | START | Спортинг#ll#550 | Эшторил#ll#550 |
+| FALSE | TRUE | 28.2.2026 | 12:55 | Волейбол | Чемпионат Турции. Женщины | TRIUMPH | Бешикташ | Галатасарай#Turki |
+
+### Формат имен команд
+
+Имена команд поддерживают два типа разделителей хэш #:
+
+1. **Первый хеш**: Уникальный идентификатор для команд с одинаковыми названиями в одном виде спорта, или одинаковым названием в разных видах спорта.
+Примеры:
+
+- `Динамо#Футбол`, `Динамо#Волейбол` - Одно название разный вид спорта
+- `Спартак#ЖенскийФ`, `Спартак#МужскойФ` Одно название _разный_ вид спорта
+
+1. **Второй хеш**: Целевой размер в пикселях для масштабирования логотипа
+
+Формат: `DisplayName#UniqueID#TargetSize`
+
+Примеры:
+
+- `Галатасарай#Turki` - только уникальный идентификатор
+- `Сомбатей##400` - только целевой размер (обратите внимание на двойной хеш)
+- `Спортинг#ll#550` - оба идентификатор и целевой размер
+
+**Важно**: Обрабатывается **только второй хеш** для масштабирования логотипа. Если уникальный идентификатор не требуется, используйте двойной хеш ## перед целевым размером.
+
+## Выходные файлы
+
+### Экспорт JSON
+
+Во время обработки сохраняются представления таблицы в формате JSON:
+
+- `{filename}_workbook.json` - Полная структура книги
+- `{filename}_{SheetName}.json` - Данные отдельного листа
+
+### Рендеренные видео
+
+Рендерные видео сохраняются в `OUTPUT_FOLDER` по следующему шаблону именования:
+
+```
 YYYYMMDD_Sport_League_TeamA_TeamB_Channel[_Variant].mp4
+```
 
-Examples:
+Имена файлов транслитерируются в латиницу. Примеры:
 
-    20260415_Футбол_Премьер-лига_Спартак_Зенит_Матч-ТВ.mp4 (Base version)
+- `20260228_Volleyball_Championship-Turkey-Women_Beşiktaş_Galatasaray_TRIUMPH.mp4`
+- `20260228_Volleyball_Championship-Turkey-Women_Beşiktaş_Galatasaray_TRIUMPH_Today.mp4`
+- `20260228_Volleyball_Championship-Turkey-Women_Beşiktaş_Galatasaray_TRIUMPH_Tomorrow.mp4`
 
-    20260415_Футбол_Премьер-лига_Спартак_Зенит_Матч-ТВ_Today.mp4
+## Рабочий процесс
 
-    20260415_Футбол_Премьер-лига_Спартак_Зенит_Матч-ТВ_Tomorrow.mp4
+1. **Аутентификация**: Подключение к NAS Synology с использованием предоставленных учетных данных
+2. **Получение файла**: Поиск и экспорт указанного файла .osheet в Excel
+3. **Парсинг данных**: Чтение всех листов и структурирование данных
+4. **Разрешение ресурсов**: Сопоставление видов спорта, команд и каналов с визуальными элементами
+5. **Генерация заданий**: Создание заданий Nexrender для каждой активной строки с вариантами
+6. **Очистка**: Удаление завершенных/неудачных заданий из предыдущих запусков
+7. **Отправка**: Отправка заданий на API Nexrender
+8. **Мониторинг**: Слежение за прогрессом выполнения до завершения
+9. **Завершение сеанса**: Закрытие сессии Synology
 
-Workflow
+## Требования к шаблонам After Effects
 
-    Authentication: Connects to Synology NAS using provided credentials
+Шаблоны должны быть предварительно настроены на узлах рендеринга со следующими именами слоев:
 
-    File Retrieval: Locates and exports the specified .osheet file as Excel
+### Типы шаблонов
 
-    Data Parsing: Reads all sheets and structures the data
+| Файл шаблона | Назначение |
+|--------------|------------|
+| `PackShot_DOUBLE.aepx` | Сопоставление с двумя командами |
+| `PackShot_SINGLE.aepx` | Анонсы для одной команды |
 
-    Asset Resolution: Matches sports, teams and channels with their visual assets
+### Обязательные слои
 
-    Job Generation: Creates Nexrender jobs for each active row with variants
+| Имя слоя | Тип | Описание |
+|----------|-----|----------|
+| DATA | Text | Отображение даты (автоматически подстраивается) |
+| TIME / TIME_H / TIME_M | Text | Отображение времени |
+| LEAGUE | Text | Название лиги |
+| SPORT | Text | Категория спорта |
+| TEAMS | Text | Скомбинированные имена команд |
+| TEAM_A_LOGO | Image | Логотип домашней команды |
+| TEAM_B_LOGO | Image | Логотип гостевой команды |
+| CHANEL | Image | Логотип канала |
+| TOP | Video | Наложение видео оформления |
 
-    Cleanup: Removes completed/failed jobs from previous runs
+### Настройки композиции
 
-    Submission: Sends jobs to Nexrender API
+- Имя композиции: `pack`
+- Выходной модуль: `Start_h264`
+- Формат вывода: `mp4`
+- Формат проекта: Adobe After Effects 2024 .aepx
 
-    Monitoring: Tracks job progress until completion
+## Устранение неисправностей
 
-    Logout: Terminates Synology session
+### Частые проблемы
 
-After Effects Template Requirements
+**Ошибка подключения к NAS**
 
-Templates must be pre-configured on render nodes with specific layer names:
-Template Types
-Template File Use Case
-Double Team PackShot_DOUBLE.aepx Matches with two teams
-Single Team PackShot_SINGLE.aepx Single team announcements
-Required Layers
-Layer Name Type Description
-DATA Text Date display (auto-adjusted)
-TIME / TIME_H / TIME_M Text Time display
-LEAGUE Text League name
-SPORT Text Sport category
-TEAMS Text Combined team names
-TEAM_A_LOGO Image Home team logo
-TEAM_B_LOGO Image Away team logo
-CHANELL Image Channel logo
-TOP Video Sport pack overlay
-Composition Settings
+- Проверьте, что `NAS_FQDN` включает протокол и порт (например, `https://nas.example.com:5001`)
+- Проверьте сетевую связность с NAS
+- Убедитесь, что сервисы File Station и Office включены
 
-    Composition name: pack
+**Файл не найден**
 
-    Output module: Start_h264
+- Убедитесь, что путь в `NAS_FILE` точно соответствует пути в Synology Drive
+- Путь должен начинаться с `/Team Folder/` для рабочих папок
+- Проверьте права доступа к файлу для учетной записи сервиса
 
-    Output format: mp4
+**Ошибка отправки задания Nexrender**
 
-Troubleshooting
-Common Issues
-Connection to NAS failed
+- Подтвердите доступность сервера Nexrender
+- Убедитесь, что `NEXRENDER_API_URL` правильный
+- Проверьте существование файлов шаблонов на узлах рендеринга
 
-    Verify NAS_FQDN includes protocol and port (e.g., https://nas.example.com:5001)
+### Режим отладки
 
-    Check network connectivity to NAS
-
-    Ensure File Station and Office services are enabled
-
-File not found
-
-    Verify the path in NAS_FILE exactly matches the Synology Drive path
-
-    Path should start with /Team Folder/ for team folders
-
-    Check file permissions for the service account
-
-Nexrender job submission fails
-
-    Confirm Nexrender server is accessible
-
-    Verify NEXRENDER_API_URL is correct
-
-    Check that template files exist on render nodes
-
-Debug Mode
-
-Enable debug logging for detailed troubleshooting:
-bash
+Включите подробное логирование для детального анализа:
 
+```bash
 RUST_LOG=debug ./target/release/ae_anons
+```
 
-This will output:
+Это выведет:
 
-    API request/response details
+- Детали API запросов/ответов
+- Информацию о парсинге листов
+- Детали создания заданий
+- Процесс разрешения ресурсов
 
-    Sheet parsing information
+## Возможные ограничения по производительности
 
-    Job creation details
+- **Большие таблицы**: Ограничение обработки до 10,000 строк на лист
+- **Задержка сети**: Загрузка файлов с NAS может занимать время для больших файлов
+- **Параллельные задания**: Nexrender управляет очередью заданий внутренне
+- **Использование памяти**: Парсинг Excel сохраняет всю книгу в памяти
 
-    Asset resolution process
+## Примечания по безопасности
 
-Performance Considerations
+- Храните учетные данные только в файле `.env` (исключен из git)
+- Используйте специальные аккаунты с минимально необходимыми правами
+- Сессии Synology завершаются после выполнения
+- HTTPS рекомендуется для подключений NAS в продакшене
 
-    Large Spreadsheets: Processing limited to 10,000 rows per sheet
+## Разработка
 
-    Network Latency: File downloads from NAS may take time for large files
-
-    Concurrent Jobs: Nexrender handles job queuing internally
-
-    Memory Usage: Excel parsing keeps entire workbook in memory
-
-Security Notes
-
-    Store credentials only in .env file (excluded from git)
-
-    Use dedicated service accounts with minimal required permissions
-
-    Synology sessions are properly terminated after execution
-
-    HTTPS recommended for NAS connections in production
-
-Development
-Running Tests
-bash
-
-cargo test
-
-Code Structure
-text
+### Структура кода
 
+```
 src/
-├── main.rs       # Application entry point and orchestration
-├── config.rs     # Configuration management
-├── nexrender.rs  # Nexrender job generation and structures
-└── synology.rs   # Synology API client
+├── main.rs       # Точка входа и оркестрация приложения
+├── config.rs     # Управление конфигурацией
+├── nexrender.rs  # Генерация заданий Nexrender и структура данных
+└── synology.rs   # Клиент API Synology
+```
 
-Adding New Features
+### Планируемые новые возможностеи
 
-    Extend JobData in nexrender.rs for new data fields
+1. Расширь `JobData` в `nexrender.rs` для новых полей данных
+2. Обновить логику парсинга листов при необходимости добавления новых колонок  
+3. Добавьть соответствующие слои After Effects в шаблоны
+4. Обновите метод `to_nexrender_job()` с новыми сопоставлениями ресурсов
 
-    Update sheet parsing logic if new columns are required
+## Зависимости
 
-    Add corresponding After Effects layers to templates
+| Crate | Версия | Назначение |
+|-------|--------|------------|
+| reqwest | 0.12 | HTTP клиент для коммуникации API |
+| serde / serde_json | 1.0 | Сериализация JSON |
+| calamine | 0.26 | Парсинг файлов Excel |
+| chrono | 0.4 | Обработка дат и времени |
+| tokio | 1.0 | Асинхронная среда выполнения |
+| dotenv | 0.15 | Конфигурация через переменные окружения |
+| log / env_logger | 0.11 | Инфраструктура логирования |
+| thiserror | 2.0 | Определение типов ошибок |
+| anyhow | 1.0 | Обработка ошибок |
 
-    Update to_nexrender_job() method with new asset mappings
+## Лицензия
 
-Dependencies
-Crate Version Purpose
-reqwest 0.12 HTTP client for API communication
-serde / serde_json 1.0 JSON serialization
-calamine 0.26 Excel file parsing
-chrono 0.4 Date/time handling
-tokio 1.0 Async runtime
-dotenv 0.15 Environment configuration
-log / env_logger 0.4 Logging infrastructure
-thiserror 2.0 Error type definitions
-anyhow 1.0 Error handling
-License
+Ещё не выбранна
 
-[Specify your license here]
-Support
+## Поддержка
 
-For issues and feature requests, please contact:
+Для вопросов и запросов функций обращайтесь:
 
-    [Your Team Email]
+- <a.barabanov@tvstart.ru>
+- [README.md](https://git.tvstart.ru/lexx/AE_Anons)
 
-    [Internal Documentation Link]
+## История изменений
 
-Changelog
-v0.1.0
+### v0.1.0
 
-    Initial release
-
-    Synology Office integration
-
-    Basic Nexrender job generation
-
-    Excel parsing with dynamic sheet detection
-
-    Multi-variant job creation
+- Первый выпуск
+- Интеграция с Synology Office
+- Базовая генерация заданий Nexrender
+- Парсинг Excel с динамическим обнаружением листов
+- Создание множественных вариантов
+- Автоматические настройки размера шрифта и позиции
+- Умное масштабирование логотипов по целевому размеру