xlx/docs/ARCHITECTURE.md

Архитектура XLX Server

1. Назначение

XLX Server — это управляемая платформа для DMR-пользователей, построенная вокруг XLX reflector и собственной системы регистрации, оплаты, проверки позывных и контроля доступа.

Главная идея: пользователь не просто подключается к открытому XLX, а проходит понятный жизненный цикл:

1. регистрация;
2. проверка позывного;
3. оплата;
4. получение ID и пароля;
5. подключение Pi-Star;
6. продление доступа или блокировка после окончания тарифа.

2. Основные компоненты

2.1 XLX Core

Отвечает за работу самого рефлектора.

Задачи:

• установка XLX reflector;
• управление системным сервисом;
• хранение конфигурации;
• контроль модулей;
• перезапуск после изменения настроек;
• сбор статуса.

2.2 Web Panel

Личный кабинет пользователя и админка.

Пользовательские функции:

• регистрация по позывному;
• вход в кабинет;
• статус проверки;
• статус оплаты;
• данные для подключения Pi-Star;
• срок действия доступа;
• история оплат;
• инструкция подключения.

Админские функции:

• список пользователей;
• ручная проверка/блокировка;
• ручное продление доступа;
• управление тарифами;
• просмотр оплат;
• просмотр логов подключений;
• управление ID-диапазонами;
• настройки сервера.

2.3 Callsign Verifier

Модуль проверки позывного по внешним источникам.

MVP-логика:

• пользователь вводит позывной;
• система нормализует его в верхний регистр;
• проверяет формат;
• делает запрос к настроенной базе;
• сохраняет результат проверки;
• при ошибке отправляет заявку в ручную модерацию.

Важно: внешний источник проверки должен быть заменяемым адаптером, чтобы не прибивать проект гвоздями к одной базе.

2.4 ID Allocator

Модуль выдачи внутренних ID.

Требования:

• ID уникален;
• ID закрепляется за пользователем;
• диапазон ID задаётся в настройках;
• повторная регистрация того же позывного не создаёт новый ID;
• заблокированный пользователь не освобождает ID автоматически;
• ручное переназначение возможно только админом.

2.5 Billing

Модуль платной регистрации и продления.

MVP:

• тарифы;
• ручное подтверждение оплаты;
• дата окончания доступа;
• блокировка после окончания срока.

Дальше:

• YooKassa;
• ЮMoney;
• СБП/карта через ручное подтверждение;
• webhooks оплат;
• счета/чеки при необходимости.

2.6 Access Gateway

Слой контроля доступа к серверу.

Задачи:

• хранить пароль пользователя;
• проверять активность подписки;
• формировать allowlist/auth-файл для XLX/DMR-шлюза;
• применять изменения без ручного редактирования конфигов;
• логировать попытки подключения.

На первом этапе допускается генерация конфигурационных файлов и перезапуск сервиса. Позже можно вынести это в отдельный daemon.

2.7 Installer/Updater

Обязательный компонент, чтобы проект нормально ставился на чистый сервер.

Функции:

• установка системных пакетов;
• установка зависимостей;
• настройка Nginx;
• настройка PHP/Python runtime;
• создание БД;
• миграции;
• установка systemd-сервисов;
• выпуск/подготовка SSL;
• бэкап перед обновлением;
• откат при ошибке.

3. Роли

User

• регистрируется;
• оплачивает;
• получает данные подключения;
• видит статус доступа.

Moderator

• проверяет спорные позывные;
• подтверждает ручные оплаты;
• блокирует пользователей.

Admin

• управляет системой полностью;
• меняет настройки сервера;
• управляет тарифами;
• управляет ID-диапазонами;
• запускает обновления.

4. Жизненный цикл пользователя

new -> callsign_pending -> callsign_verified -> payment_pending -> active -> expired
                                      |              |
                                      v              v
                                  rejected        blocked

5. Подключение Pi-Star

Пользователь получает в кабинете:

• адрес сервера;
• порт;
• позывной/логин;
• пароль;
• ID;
• модуль по умолчанию;
• готовую инструкцию.

6. База данных

Минимальные сущности:

• users;
• callsign_checks;
• dmr_ids;
• tariffs;
• payments;
• access_credentials;
• server_settings;
• connection_logs;
• audit_logs.

7. Безопасность

• пароли хранить только в виде хэша;
• пароль для подключения генерировать отдельно от пароля кабинета;
• админские действия писать в audit log;
• закрыть прямой доступ к служебным файлам;
• не хранить платёжные данные карт;
• все webhooks проверять по подписи.

8. Дорожная логика версий

v0.1.x

Каркас, документация, установщик, БД, базовая панель.

v0.2.x

Регистрация, пользователи, проверка позывных, выдача ID.

v0.3.x

Оплаты, тарифы, ручное подтверждение, срок доступа.

v0.4.x

Генерация доступа для Pi-Star и управление auth/allowlist.

v0.5.x

Интеграция с XLX reflector и статус сервера.

v1.0.0

Готовый продукт: установка, админка, кабинет, оплата, доступ, мониторинг и обновления.