Update .gitignore to include local environment files and expand README with project details, tech stack, documentation links, and project status.

docs/vision.md

@@ -0,0 +1,125 @@
+# 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 (без перезагрузки).
+- При достижении лимита/срока конфиг помечается и (опционально) отключается в 3x-ui.
+
+### 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.
+- **Наблюдаемость**: структурные логи (Serilog), health-checks нод, метрики.
+- **Отказоустойчивость к нодам**: недоступность одной ноды не роняет панель; операции идемпотентны где возможно.
+- **Производительность**: списки с пагинацией; синхронизация трафика батчами.