docs: mermaid architecture/payment/node-add diagrams, stability notes, troubleshooting

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -17,22 +17,43 @@
 
 ## Архитектура
 
+```mermaid
+flowchart LR
+    tg["Telegram юзер"] -->|кнопки| bot["bot.py (aiogram)"]
+    browser["Браузер / Happ-клиент"] -->|"/sub/{token}"| api["api.py (FastAPI)"]
+    admin["Админ в браузере"] -->|"/admin/api/*"| api
+
+    bot --> db[("SQLite (db.py)")]
+    api --> db
+
+    api -->|локально| xray["Xray на этой же ноде"]
+    api -->|SSH, paramiko| remote["Управляемые ноды"]
+
+    subgraph node1 [Управляемая нода]
+        remote --> xray2["Xray"]
+    end
 ```
-┌─────────────┐       ┌──────────────────────────────┐
-│  Telegram    │──────▶│  bot.py (aiogram)             │
-│  юзер        │       │  выдаёт токен подписки         │
-└─────────────┘       └──────────────┬────────────────┘
-                                       │ SQLite (db.py)
-┌─────────────┐       ┌──────────────▼────────────────┐
-│  браузер /   │──────▶│  api.py (FastAPI)              │
-│  Happ клиент │       │  /sub/{token}, /admin/api/*    │
-└─────────────┘       │  админка на / (admin.html)     │
-                       └──────────────┬────────────────┘
-                                       │ SSH (paramiko)
-                       ┌──────────────▼────────────────┐
-                       │  Xray на этой же ноде          │
-                       │  + управляемые ноды по SSH     │
-                       └─────────────────────────────────┘
+
+Панель и первая VPN-нода живут на одном сервере. Дополнительные ноды подключаются по SSH (management-ключ, генерится сам при первом добавлении ноды) — панель не устанавливает на себя ничего от ноды, только управляет клиентами через SSH-команды и Xray Stats API.
+
+### Поток оплаты (когда `PAYMENTS_ENABLED=true`)
+
+```mermaid
+sequenceDiagram
+    participant U as Юзер (бот)
+    participant B as bot.py
+    participant P as ЮKassa/Platega
+    participant A as api.py
+    participant X as Xray
+
+    U->>B: выбрал тариф
+    B->>P: создать платёж
+    P-->>B: ссылка на оплату
+    B-->>U: кнопка "Оплатить"
+    U->>P: оплатил
+    P->>A: webhook (подпись проверяется)
+    A->>X: добавить клиента
+    A->>U: уведомление в Telegram
 ```
 
 Панель и первая VPN-нода живут на одном сервере. На 443 порту нельзя одновременно держать и настоящий HTTPS (для сайта/подписки), и замаскированный под HTTPS VLESS+Reality трафик — поэтому перед Xray стоит `nginx stream` модуль с `ssl_preread`, который смотрит SNI входящего TLS-соединения и роутит: домены панели/подписки идут на nginx-бэкенд, всё остальное (в том числе Reality-трафик с левым SNI) — на Xray.
@@ -91,6 +112,21 @@ bash <(curl -Ls https://panel.example.com/install/ТОКЕН.sh)
 
 Вставляешь на чистый сервер (тот же Ubuntu 22/24 или Debian 11/12) — нода сама всё ставит и регистрируется. Если включал WS+TLS — скрипт выпустит для неё отдельный Let's Encrypt сертификат (нужна ещё одна A-запись, см. таблицу выше). Если включал Hysteria2 — поднимет отдельный процесс на UDP.
 
+```mermaid
+sequenceDiagram
+    participant Admin as Админ
+    participant Panel as Панель
+    participant Node as Новая нода
+
+    Admin->>Panel: Ноды → Добавить ноду
+    Panel->>Panel: генерит Reality-ключи, токен
+    Panel-->>Admin: команда bash <(curl ...ТОКЕН.sh)
+    Admin->>Node: вставляет команду по SSH
+    Node->>Node: ставит Xray, настраивает transports
+    Node->>Panel: POST /nodes/register/ТОКЕН
+    Panel->>Panel: нода активна, доступна в боте
+```
+
 ## Приём оплаты
 
 По умолчанию бот выдаёт подписки бесплатно по кнопке — платежи выключены (`PAYMENTS_ENABLED=false`). Чтобы продавать доступ:
@@ -108,6 +144,19 @@ bash <(curl -Ls https://panel.example.com/install/ТОКЕН.sh)
 
 Выключено по умолчанию (`HWID_LIMIT_ENABLED=false`) — клиенты, которые не шлют `x-hwid`, при включённом лимите вообще не получат подписку, так что включай только если знаешь, что твои пользователи сидят на приложениях с поддержкой этого заголовка. `HWID_FALLBACK_LIMIT` — лимит по умолчанию для всех, в админке (Подписки → кнопка «Устройства» у юзера) можно посмотреть/удалить привязанные устройства и задать индивидуальный лимит.
 
+## Стабильность и производительность
+
+- `install.sh` ретраит все сетевые шаги (apt, git, pip, certbot, установка Xray) — 3 попытки с паузой, типичная причина падения свежих VPS-установок это не баги, а моргнувшая сеть/зеркало пакетов.
+- SQLite в WAL-режиме + `synchronous=NORMAL` (стандартная безопасная связка для этого режима) — меньше блокировок между ботом и апи, которые пишут в одну базу параллельно.
+- Индексы на всех горячих путях (`subscriptions(active, expires_at)` — дергается ботом каждые 90 секунд на проверку истечения; `subscriptions(tg_id)`, `devices(tg_id)`, `payments(status)`) — на паре сотен юзеров разницы не увидишь, но на тысячах — увидишь.
+- CI гоняет не только синтаксис, а реальный импорт `api.py`/`bot.py` целиком плюс smoke-тесты платёжной и HWID-логики на живом Ubuntu — ловит баги при импорте/вайринге модулей до того, как они попадут на прод.
+
+## Частые проблемы при установке
+
+- **Certbot не может выпустить сертификат** — почти всегда значит DNS A-записи ещё не проехали (обнови и подожди 5-10 минут) или порт 80 занят чем-то ещё (`ss -ltnp | grep :80`).
+- **Xray не стартует после установки** — `mbs logs xray`, почти всегда конфликт порта 443 с чем-то другим, что уже там висит (другая панель, старый nginx на 443 напрямую).
+- **Панель недоступна, но сервисы `active`** — проверь `nginx -t` и `systemctl status nginx`, скорее всего SNI-роутер (`/etc/nginx/stream.d/mbs.conf`) не подхватился — `nginx -s reload` после любых правок туда вручную.
+
 ## Разработка / вклад
 
 Код простой — без сборки фронта, без ORM, без лишних абстракций. `admin.html` — один файл, vanilla JS. Питон-часть — обычные функции, SQLite напрямую.