# Архитектура 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-логика:

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

Важно: уникальность дополнительно защищена индексом `users.callsign`, поэтому дубль не пройдет даже при одновременной регистрации.

### 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. Жизненный цикл пользователя

```text
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

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