# Разработка

Инструкция по настройке окружения, структуре проекта и запуску из исходников.

---

## Содержание

- [Требования](#требования)
- [Настройка окружения](#настройка-окружения)
- [Запуск](#запуск)
- [Структура проекта](#структура-проекта)
- [Архитектура](#архитектура)
- [Темы оформления](#темы-оформления)
- [Добавление новых ресурсов](#добавление-новых-ресурсов)
- [Сборка EXE](#сборка-exe)

---

## Требования

- Python >= 3.11
- pip

Зависимости (перечислены в `requirements.txt`):

| Пакет          | Назначение                      |
|----------------|---------------------------------|
| PySide6 >= 6.7 | GUI-фреймворк (Qt for Python)  |
| pyserial >= 3.5 | Работа с COM-портом            |
| qtawesome >= 1.4 | Иконки FontAwesome             |
| pycryptodome >= 3.20 | AES-256 для авторизации    |

---

## Настройка окружения

```powershell
cd D:\Danil\Projects\python\plate_config_app

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

---

## Запуск

```powershell
.\.venv\Scripts\python.exe main.py
```

или после активации окружения:

```powershell
python main.py
```

---

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

```
plate_config_app/
    main.py                     # Точка входа
    requirements.txt            # Runtime-зависимости
    requirements-build.txt      # Зависимости для сборки EXE
    plate_config_app.spec       # Конфигурация PyInstaller
    settings.json               # Настройки пользователя (не в git)

    app/
        entry.py                # Создание QApplication, загрузка темы
        main_window.py          # Главное окно с вкладками
        serial_config.py        # Dataclass параметров COM-порта

        services/               # Бизнес-логика (без зависимости от UI)
            auth_service.py     # AES-256 handshake
            com_service.py      # Обёртка над pyserial
            commands_service.py # Загрузка CSV-наборов команд
            input_mappings_service.py  # Загрузка маппингов входов
            light_modes_service.py     # Загрузка режимов подсветки
            settings_service.py # Чтение/запись settings.json

        ui/                     # Визуальное оформление
            theme.py            # Палитры, QSS-шаблон, build_stylesheet()
            icons.py            # Обёртка над qtawesome

        widgets/                # UI-компоненты
            start_tab.py        # Стартовая страница
            connection_tab.py   # Вкладка подключения и управления
            title_bar.py        # Кастомный заголовок окна

            sections/           # Встраиваемые секции (базовый режим)
                firmware_section.py    # Загрузка прошивки и OTA
                input_test_section.py  # Тест входов и джойстик
                led_test_section.py    # Тест подсветки
                payment_section.py     # Монетоприёмник, хоппер, призы

            dialogs/            # Модальные диалоги (PRO-режим)
                styled_dialog.py           # Базовый класс диалогов
                command_terminal_dialog.py # Терминал ручного ввода команд
                commands_dialog.py         # Справочник команд платы
                firmware_dialog.py         # Обновление прошивки
                input_test_dialog.py       # Тест входов
                led_test_dialog.py         # Тест подсветки
                output_test_dialog.py      # Тест силовых выходов
                role_dialog.py             # Задание роли
                settings_dialog.py         # Настройки темы

    commands/                   # Наборы команд (.csv, разделитель ";")
    light_modes/                # Режимы подсветки (.lm, формат TOML)
    input_mappings/             # Маппинги входов (.mapping, формат TOML)
```

---

## Архитектура

Приложение построено по принципу разделения на слои:

1. **services/** -- бизнес-логика, не зависящая от Qt-виджетов.
   Сервисы загружают данные с диска, управляют COM-соединением,
   выполняют авторизацию. Могут использоваться без GUI.

   `ComConnection` хранит версию текущей прошивки и режим авторизации,
   определённые по стартовой строке. Маркер `no_auth` проверяется без учёта
   регистра; для неизвестной версии применяется строгий режим с AES-256
   handshake. После переподключения и OTA режим определяется заново.

2. **ui/** -- визуальное оформление. `theme.py` содержит палитры
   (`ThemePalette`) и QSS-шаблон с подстановкой переменных.
   `icons.py` -- обёртка над `qtawesome` с fallback при отсутствии
   библиотеки.

3. **widgets/** -- UI-компоненты. `ConnectionTab` управляет жизненным
   циклом подключения. Диалоги наследуются от `StyledDialog`
   (frameless QDialog с кастомным заголовком и перетаскиванием).

Потоки: тяжёлые операции (авторизация, прошивка, мониторинг входов,
health-check) вынесены в `QThread`-подклассы. Связь с UI -- через
сигналы Qt.

---

## Темы оформления

Система тем определена в `app/ui/theme.py`:

- `ThemePalette` -- frozen dataclass с полями цветов.
- Четыре палитры: `_LIGHT_GREEN`, `_LIGHT_BLUE`, `_DARK_GREEN`, `_DARK_BLUE`.
- `_QSS_TEMPLATE` -- единый QSS-шаблон с плейсхолдерами `{field_name}`.
- `build_stylesheet(palette)` -- подставляет значения палитры в шаблон.
- `get_palette(mode, accent)` -- возвращает палитру по названию темы и акцента.

Для добавления новой палитры:

1. Создайте экземпляр `ThemePalette(...)` с нужными цветами.
2. Добавьте его в словарь `PALETTES` в `theme.py`.
3. Обновите `SettingsDialog`, если нужно добавить новый акцент.

---

## Добавление новых ресурсов

### Команды платы

Создайте `.csv` файл в `commands/` с разделителем `;`. Формат:

```
КОД;Название;Описание
```

Пример: `commands/Мои команды.csv`.

### Режимы подсветки

Создайте `.lm` файл в `light_modes/` в формате TOML.
Структура описана в `app/services/light_modes_service.py`.

### Маппинги входов

Создайте `.mapping` файл в `input_mappings/` в формате TOML.
Структура описана в `app/services/input_mappings_service.py`.

После добавления файлов они подхватятся при следующем запуске.
При сборке EXE папки автоматически копируются рядом с исполняемым файлом
скриптом `build_exe.ps1`. Пересборка для обновления конфигураций **не нужна** —
достаточно отредактировать файлы рядом с EXE и перезапустить приложение.

---

## Сборка EXE

Подробная инструкция: [BUILD_EXE.md](BUILD_EXE.md).

Краткая версия:

```powershell
# Установка зависимостей сборки + билд
.\build_exe.ps1 -InstallBuildDeps
```

Результат: `dist\plate_config_app-windows-x86_64.exe`, ZIP-архив
`dist\plate_config_app-windows-x86_64.zip` и папки `dist\light_modes\`,
`dist\input_mappings\`, `dist\commands\`.