docs: update docs

2026-05-11 06:34:45 +03:00
parent 5a015fe8b4
commit 5243cc4284
7 changed files with 104 additions and 12 deletions
@@ -0,0 +1,53 @@
+# Админ-панель Web App
+
+Админ-панель доступна пользователям, чей Telegram ID указан в `ADMIN_IDS`. В Web App такие пользователи видят раздел администрирования; все API `/api/admin/*` дополнительно проверяют сессию и `ADMIN_IDS` на сервере.
+
+## Возможности
+
+- дашборд со статистикой пользователей, платежей и синхронизации с Remnawave;
+- список пользователей, карточка активной подписки, обычный и premium-трафик, платежи и действия;
+- блокировка пользователей, рассылки, промокоды и просмотр логов;
+- ручная синхронизация с Remnawave;
+- редактор разрешенных настроек приложения из manifest-файла;
+- редактор JSON-каталога тарифов;
+- загрузка Internal Squads из Remnawave для выбора в тарифах.
+
+## Настройки
+
+Раздел **Система -> Настройки** позволяет менять приложение без редактирования `.env`, но только в пределах allowlist из `bot/app/web/admin_settings_manifest.py`. Даже администратор не может менять через UI произвольные атрибуты `Settings`.
+
+Изменения сохраняются как overrides в базе данных и применяются поверх `.env` без перезапуска. Если значение сброшено, снова используется значение из `.env`. После сохранения публичный кеш настроек Web App сбрасывается, поэтому пользователи видят изменения при следующих запросах.
+
+В manifest сейчас входят:
+
+- общие параметры: язык, валюта, ссылки поддержки, документы, обязательный канал и поведение `/start`;
+- внешний вид и доступность Web App: название, цвет, логотип, emoji-логотип и `WEBAPP_ENABLED`;
+- legacy-цены без JSON-каталога: периоды подписки, RUB/Stars цены и пакеты трафика;
+- платежные провайдеры: включение методов, порядок кнопок, публичные параметры и секреты YooKassa, FreeKassa, Platega, SeverPay, CryptoPay и Stars;
+- пробный период, реферальные бонусы, уведомления, логирование, раздел устройств, лимит устройств и legacy-лимиты трафика.
+
+Секретные поля помечены как secret и не должны использоваться для произвольного просмотра старых значений. Настройки, которых нет в manifest, остаются только в `.env` или коде.
+
+## Тарифы
+
+Раздел **Система -> Тарифы** работает с файлом `TARIFFS_CONFIG_PATH` (по умолчанию `config/tariffs.json`). При сохранении backend валидирует payload через `TariffsConfig`, пишет JSON в UTF-8 и сбрасывает кеш публичных данных Web App.
+
+Если файла еще нет, админка открывает пустой каталог. Перед сохранением должен быть хотя бы один включенный тариф, а `default_tariff` должен ссылаться на включенный тариф.
+
+Редактор тарифа разделен на вкладки:
+
+- **Основное**: ключ, модель `period`/`traffic`, видимость, названия и описания RU/EN, базовые Internal Squads, HWID-лимит, месячный лимит или курс конвертации;
+- **Цены**: периоды и цены для `period`, пакеты GB и цены для `traffic`;
+- **Докупки**: обычные пакеты докупки трафика для `period`; для `traffic` отдельные докупки не нужны, пользователь повторно покупает пакеты из `traffic_packages`;
+- **Premium**: названия premium-раздела RU/EN, premium Internal Squads, месячный premium-лимит и RUB/Stars пакеты premium-докупки;
+- **Устройства**: RUB/Stars пакеты докупки HWID-устройств.
+
+Базовые и premium Internal Squads выбираются из Remnawave через `/api/admin/panel/internal-squads`. Если панель недоступна, можно сохранить уже существующие UUID в JSON, но выпадающий список не загрузится.
+
+## Практические замечания
+
+Не меняйте `key` опубликованного тарифа без миграции активных подписок: подписки, платежи и смена тарифа ссылаются на этот ключ.
+
+Отключенный тариф исчезает с витрины, но активные подписки с его `tariff_key` продолжают существовать. Удаление тарифа безопасно только если не осталось активных подписок, которым нужна докупка, продление или смена с этого тарифа.
+
+Для Docker важно, чтобы путь `TARIFFS_CONFIG_PATH` был доступен на запись контейнеру. В dev-compose каталог `./config` монтируется в `/app/config`, поэтому админка может сохранять `config/tariffs.json`.