# Product Vision & Scope

## Проблема

Раздача VPN-доступов через «голую» панель 3x-ui неудобна: администратор вручную заводит
клиентов, копирует ссылки, следит за трафиком и сроками. Конечные пользователи не имеют
самообслуживания — за каждым конфигом идут к админу.

## Решение

**PnvPanel** — тонкий, но красивый слой самообслуживания поверх одной или нескольких панелей
3x-ui:

- **Пользователь** регистрируется, сам создаёт себе VPN-конфиги, видит трафик/срок,
  получает ссылку-подписку и QR-код, отзывает ненужные конфиги.
- **Администратор** подключает VPN-серверы (ноды 3x-ui), выбирает какие inbounds доступны для
  самообслуживания, задаёт лимиты, управляет пользователями и видит статистику в реальном времени.

PnvPanel **не заменяет** Xray/3x-ui — он оркестрирует их через API (`ThreeXui.Net`) и хранит
свою проекцию данных (пользователи, привязки конфигов, история трафика) в PostgreSQL.

## Роли

| Роль        | Возможности                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------- |
| **Guest**   | Регистрация, вход, публичный эндпоинт подписки (`/sub/{token}`).                              |
| **User**    | После **активации** — CRUD своих конфигов (в рамках квоты роли и доступных инбаундов), просмотр трафика/срока, ссылка/QR, отзыв. |
| **Admin**   | Всё выше без лимитов + ноды, публикация inbounds с выбором ролей, роли/квоты, активация пользователей, каталог приложений, стата. |
| *(кастомные)* | Админ создаёт роли (напр. `vip`) со своей квотой конфигов и назначает их пользователям.     |

### RBAC — динамические роли с квотой
- Роли реализованы через **ASP.NET Core Identity**, но `AppRole` расширен полем `MaxConfigs`
  (квота на число конфигов). Авторизация — policy-based.
- Системные роли сидируются: `admin` (без лимита) и `user` (`MaxConfigs` из env, по умолчанию **3**).
- **Админ может создавать новые роли** с другой квотой и назначать их пользователям.
- **У пользователя ровно одна роль**; его квота = `MaxConfigs` этой роли.

### Активация пользователей
- После регистрации пользователь **не активирован** и не может создавать конфиги.
- Он отправляет **запрос на активацию** с комментарием (напр. «я Никита» — чтобы админ понял, кто это).
- Админ одобряет/отклоняет запрос **на сайте или в Telegram**. После одобрения — доступно создание конфигов.

### Аутентификация и восстановление доступа
- **Логин — по username** (email в системе не используется; SMTP не нужен).
- **Восстановление пароля**: только через привязанный Telegram (self-service). Если Telegram не
  привязан — пароль сбрасывает админ.
- Пока Telegram не привязан, панель **настойчиво напоминает** это сделать (баннер/уведомления в UI) —
  это единственный способ самому восстановить доступ.

### Сид администратора
- Учётка админа **сидируется при первом старте** из переменных окружения (username, пароль,
  Telegram id админов). Пример — [`.env.example`](../.env.example). Telegram id админа задаётся через env
  и используется для админ-действий и уведомлений в боте.

## Каналы доступа

- **Веб-панель** (React SPA) — основной интерфейс для User и Admin.
- **Telegram-бот** — вспомогательный канал для User: ссылка на сайт, просмотр своих конфигов и
  **passwordless-вход** на сайт через привязанный Telegram (вместо пароля). Детали — [telegram-bot.md](telegram-bot.md).

## Ключевые пользовательские сценарии

### U0. Регистрация и активация
1. Пользователь регистрируется → получает роль `user`, статус **не активирован**.
2. Отправляет запрос на активацию с комментарием («я Никита»).
3. Админ видит запрос (на сайте и/или в Telegram) → «Активировать» / «Отклонить».
4. После одобрения пользователь может создавать конфиги (в пределах квоты роли).

### U1. Пользователь создаёт конфиг
1. Входит в панель (активирован) → «Создать конфиг».
2. Видит только инбаунды, **доступные его роли** (напр. «Германия (Trojan)»); выбирает нужный.
3. Проверка квоты: число активных конфигов < `MaxConfigs` его роли.
4. Бэкенд создаёт клиента в 3x-ui (`AddClient`), сохраняет привязку `VpnConfig` в БД.
5. Пользователь получает connection string, ссылку-подписку и QR-код.

### U2. Пользователь следит за трафиком
- Фоновая синхронизация тянет трафик из 3x-ui; изменения приходят в UI через SignalR (без перезагрузки).
- Это только отображение: лимиты по трафику/сроку конфига не реализованы — единственная квота —
  число активных конфигов на роль. Конфиг живёт, пока его явно не отзовут.

### A1. Админ подключает ноду и публикует инбаунды
1. Вводит адрес панели 3x-ui, логин/пароль (шифруются при хранении).
2. PnvPanel проверяет доступность, синхронизирует список inbounds.
3. Админ публикует нужные inbounds (напр. «Германия (Trojan)») и **указывает роли**, которым
   разрешено создавать конфиги в этом инбаунде (напр. `user`, `vip`).

### A3. Админ управляет ролями и активацией
1. Создаёт роль (напр. `vip`) с нужной квотой конфигов, назначает пользователям.
2. Обрабатывает запросы на активацию (на сайте или в Telegram): видит комментарий заявителя, решает.

### A2. Админ управляет пользователями
- Список пользователей, их конфигов и потребления; блокировка/разблокировка; принудительный отзыв конфигов.

### T1. Пользователь привязывает Telegram и входит без пароля
1. В веб-панели (войдя по username+паролю) нажимает «Привязать Telegram» → получает deep-link в бота.
2. Открывает бота → аккаунт привязывается к его Telegram.
3. В следующий раз на сайте выбирает «Войти через Telegram» → подтверждает вход в боте → входит без пароля.
4. В боте может смотреть свои конфиги и открывать сайт.

## Функциональность

**Реализовано:**
- Регистрация/вход (JWT + Identity); сид админа из env.
- Динамические роли с квотой конфигов (сид `admin`/`user`); создание ролей и назначение админом.
- Активация пользователей по запросу с комментарием (одобрение на сайте и в Telegram).
- Управление нодами; публикация inbounds с выбором доступных ролей.
- Создание/просмотр/отзыв конфигов пользователем (проверки активации, квоты, доступа роли к инбаунду); ссылка-подписка + QR.
- Синхронизация трафика (фоновая) + realtime-обновления по SignalR.
- Базовая статистика для админа.
- Telegram-бот: ссылка на сайт, просмотр конфигов, привязка/регистрация через Telegram и passwordless-вход.
- Светлая/тёмная тема сайта.
- Страница инструкций по подключению + каталог приложений по ОС (админ ведёт, юзер видит сгруппировано).
- Единый Docker-образ (фронт+бек) + PostgreSQL в docker-compose.

**Не реализовано:**
- Тарифы/биллинг/платежи.
- Многоуровневые квоты, автопродление, промокоды.
- Балансировка нагрузки между нодами, автоскейл.
- Реферальная программа; расширенные уведомления (через Telegram/веб).
- Мультиязычность сверх RU/EN.

## Нефункциональные требования

- **Безопасность**: секреты нод шифруются at-rest; JWT с коротким TTL + refresh; rate-limiting на
  auth/Telegram-эндпоинты и публичную подписку (создание конфигов им пока не покрыто).
- **Наблюдаемость**: структурные логи (Serilog), health-checks нод, метрики.
- **Отказоустойчивость к нодам**: недоступность одной ноды не роняет панель; операции идемпотентны где возможно.
- **Производительность**: списки с пагинацией; синхронизация трафика батчами.