PnvPanel/docs/vision.md

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. Telegram id админа задаётся через env и используется для админ-действий и уведомлений в боте.

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

• Веб-панель (React SPA) — основной интерфейс для User и Admin.
• Telegram-бот — вспомогательный канал для User: ссылка на сайт, просмотр своих конфигов и passwordless-вход на сайт через привязанный Telegram (вместо пароля). Детали — 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 (без перезагрузки).
• В MVP это только отображение: лимиты по трафику/сроку конфига не реализованы — единственная квота — число активных конфигов на роль. Конфиг живёт, пока его явно не отзовут.

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. В боте может смотреть свои конфиги и открывать сайт.

Границы MVP

В MVP входит:

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

За рамками MVP (backlog):

• Полная регистрация аккаунта через Telegram (в MVP — только привязка существующего).
• Тарифы/биллинг/платежи.
• Многоуровневые квоты, автопродление, промокоды.
• Балансировка нагрузки между нодами, автоскейл.
• Реферальная программа; расширенные уведомления (через Telegram/веб).
• Мультиязычность сверх RU/EN.

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

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