Leonid Pershin
cf3d8fcad8
- Added a new endpoint for changing usernames, allowing users to update their login credentials via the API. - Integrated username change functionality into the settings page, providing a user-friendly interface for this action. - Enhanced the Telegram bot to support user registration directly through the bot, including username generation and password delivery. - Updated documentation to reflect the new username change endpoint and registration flow through the Telegram bot.
129 lines
12 KiB
Markdown
129 lines
12 KiB
Markdown
# 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 (без перезагрузки).
|
||
- **В 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/веб).
|
||
- Мультиязычность сверх RU/EN.
|
||
|
||
## Нефункциональные требования
|
||
|
||
- **Безопасность**: секреты нод шифруются at-rest; JWT с коротким TTL + refresh; rate-limiting на
|
||
auth/Telegram-эндпоинты и публичную подписку (создание конфигов им пока не покрыто).
|
||
- **Наблюдаемость**: структурные логи (Serilog), health-checks нод, метрики.
|
||
- **Отказоустойчивость к нодам**: недоступность одной ноды не роняет панель; операции идемпотентны где возможно.
|
||
- **Производительность**: списки с пагинацией; синхронизация трафика батчами.
|