plate-config-app/DEVELOPMENT.md

Разработка

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

---

Содержание

• Требования
• Настройка окружения
• Запуск
• Структура проекта
• Архитектура
• Темы оформления
• Добавление новых ресурсов
• Сборка 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 для авторизации

---

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

cd D:\Danil\Projects\python\plate_config_app

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

---

Запуск

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

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

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.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\.