docs: update docs and minimize env.example

docs/admin.md

@@ -6,7 +6,7 @@
 
 - дашборд со статистикой пользователей, платежей и синхронизации с Remnawave;
 - список пользователей с поиском, фильтрами и колонкой premium-трафика; карточка пользователя с активной подпиской, обычным и premium-трафиком, платежами и действиями (подробнее в разделе «Пользователи» ниже);
-- блокировка пользователей, рассылки, промокоды и просмотр логов;
+- блокировка пользователей, входящий список тикетов поддержки, рассылки, промокоды и просмотр логов;
 - ручная синхронизация с Remnawave;
 - редактор разрешенных настроек приложения из manifest-файла;
 - раздел **Внешний вид** для логотипа, emoji-логотипа, выбора темы, accent-цвета, масштаба логотипа и предпросмотра тем;
@@ -39,16 +39,24 @@
 
 В manifest сейчас входят:
 
-- общие параметры: язык, валюта, ссылки поддержки, документы, обязательный канал и поведение `/start`;
+- общие параметры: язык, валюта, ссылки поддержки, документы, обязательный канал, Remnawave-доступы и поведение `/start`;
 - внешний вид и доступность Web App: название, цвет, логотип, emoji-логотип и `WEBAPP_ENABLED`;
 - legacy-цены без JSON-каталога: периоды подписки, RUB/Stars цены и пакеты трафика;
-- платежные провайдеры: включение методов, порядок кнопок, публичные параметры и секреты YooKassa, FreeKassa, Platega, SeverPay, Wata, CryptoPay и Stars, а также текст и иконки кнопок оплаты;
-- пробный период, реферальные бонусы, уведомления, логирование, раздел устройств, лимит устройств и legacy-лимиты трафика.
+- платежные провайдеры: включение методов, порядок кнопок, публичные параметры и секреты YooKassa, FreeKassa, Platega, SeverPay, Wata, CryptoPay, Heleket и Stars, а также текст и иконки кнопок оплаты;
+- пробный период, реферальные бонусы, уведомления, логирование, поддержка, раздел устройств, лимит устройств и legacy-лимиты трафика.
 
 Секретные поля помечены как secret и не должны использоваться для произвольного просмотра старых значений. Настройки, которых нет в manifest, остаются только в `.env` или коде.
 
 Для каждого платежного метода в разделе провайдера доступны presentation-настройки `PAYMENT_<METHOD>_WEBAPP_LABEL_RU`, `PAYMENT_<METHOD>_WEBAPP_LABEL_EN`, `PAYMENT_<METHOD>_WEBAPP_ICON`, `PAYMENT_<METHOD>_TELEGRAM_LABEL_RU`, `PAYMENT_<METHOD>_TELEGRAM_LABEL_EN` и `PAYMENT_<METHOD>_TELEGRAM_EMOJI`. Пустое значение возвращает мультиязычный дефолт из модуля платежного провайдера. Иконка Web App выбирается из уже подключённых lucide-иконок (`frontend/src/lib/components/ui/icons.js`) через модалку в админке.
 
+## Поддержка
+
+Раздел **Коммуникации -> Поддержка** показывает входящий список тикетов из Mini App. В списке доступны фильтры по статусу, приоритету, категории и назначенному администратору, поиск по теме и пользователю, сортировка по обновлению, созданию или важности.
+
+В карточке тикета администратор видит диалог, пользовательский контекст и действия: ответить пользователю, оставить внутреннюю заметку, изменить статус, приоритет, категорию или исполнителя, закрыть тикет и перейти в карточку пользователя. Внутренние заметки не показываются пользователю.
+
+Счетчик непрочитанных обращений отображается в навигации админки. Уведомления о новых тикетах и ответах пользователя настраиваются через `LOG_SUPPORT`, `LOG_SUPPORT_THREAD_ID` и параметры `SUPPORT_*`. Подробности: [support.md](support.md).
+
 ## Внешний вид
 
 Раздел **Внешний вид** объединяет настройки бренда и темы Web App. Логотип можно загрузить файлом или по HTTPS-ссылке; backend сохраняет файл в `data/webapp-logo/uploads` и подставляет локальный URL. Если включен emoji-логотип, картинка скрывается, а для emoji можно выбрать системный, Twemoji, Noto Color, animated Noto и другие варианты отрисовки.

docs/configuration.md

@@ -1,256 +1,94 @@
 # Настройка окружения
 
-Конфигурация читается из `.env`. За основу удобно взять `.env.example` и заполнить значения под свою панель, домены и платежные провайдеры.
+Проект поддерживает два слоя конфигурации:
+
+- `.env` - bootstrap, инфраструктура, стабильные секреты и базовые доступы к Remnawave;
+- Web App админка - основной рекомендуемый способ менять продуктовые настройки после первого запуска.
+
+Админка сохраняет overrides в базе данных и применяет их поверх `.env`. Это удобно для платежей, внешнего вида, поддержки, уведомлений, legacy-цен и большинства пользовательских параметров. Тарифы редактируются отдельно в разделе **Система -> Тарифы** и сохраняются в JSON-файл `TARIFFS_CONFIG_PATH`.
+
+Полный справочник всех переменных вынесен в [env-vars.md](env-vars.md).
+
+## Минимальный `.env`
+
+Начните с короткого примера:
 
 ```bash
 cp .env.example .env
 nano .env
 ```
 
-## Основные настройки
+Минимально заполните:
 
-| Переменная | Назначение |
+| Переменная | Зачем нужна |
 | --- | --- |
 | `BOT_TOKEN` | Токен Telegram-бота. |
-| `ADMIN_IDS` | Telegram ID администраторов через запятую. |
-| `DEFAULT_LANGUAGE` | Язык по умолчанию для пользователей: `ru` или `en`. |
-| `DEFAULT_CURRENCY_SYMBOL` | Символ валюты по умолчанию в интерфейсе (например `RUB`, `USD`). |
-| `SUPPORT_LINK` | Ссылка на поддержку. |
-| `SERVER_STATUS_URL` | Ссылка на страницу статуса сервиса. |
-| `TERMS_OF_SERVICE_URL` | Ссылка на условия использования (отдельно от пользовательского соглашения). |
-| `PRIVACY_POLICY_URL` | Ссылка на политику конфиденциальности в Web App. |
-| `USER_AGREEMENT_URL` | Ссылка на пользовательское соглашение в Web App. |
-| `REQUIRED_CHANNEL_ID` | ID канала, на который пользователь должен подписаться перед использованием. |
-| `REQUIRED_CHANNEL_LINK` | Ссылка на канал для кнопки проверки подписки. |
-| `WEBHOOK_BASE_URL` | Публичный базовый URL для вебхуков (Telegram, платежи, панель). **Обязателен:** без него приложение не запускается. |
-| `TRUSTED_PROXIES` | Список IP или CIDR reverse proxy, которым доверяют заголовок `X-Forwarded-For` (через запятую). |
-| `START_COMMAND_DESCRIPTION` | Текст описания команды `/start` для меню Telegram (BotFather). |
-| `DISABLE_WELCOME_MESSAGE` | Если `true`, приветственное сообщение на `/start` не отправляется. |
+| `ADMIN_IDS` | Telegram ID администраторов через запятую; без этого не попасть в Web App админку. |
+| `WEBHOOK_BASE_URL` | Публичный URL webhook-домена backend. |
+| `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | Доступы PostgreSQL для Compose и backend. |
+| `WEBAPP_SESSION_SECRET` | Стабильный секрет сессий Web App. |
+| `WEBHOOK_SECRET_TOKEN` | Стабильный secret token Telegram webhook. |
+| `SUBSCRIPTION_MINI_APP_URL` | Публичный URL Mini App, чтобы бот мог открыть личный кабинет. |
+| `PANEL_API_URL`, `PANEL_API_KEY`, `PANEL_WEBHOOK_SECRET` | Базовая интеграция с Remnawave. Эти значения стоит хранить в `.env`, но при необходимости их можно переопределить из админки. |
 
-Если используется проверка подписки на канал, добавьте бота администратором в этот канал. После первой успешной проверки пользователь продолжает работу без повторной блокировки действий.
-
-## Remnawave
-
-| Переменная | Назначение |
-| --- | --- |
-| `PANEL_API_URL` | URL API панели Remnawave, например `https://panel.domain.com/api`. |
-| `PANEL_API_KEY` | API-ключ панели. |
-| `PANEL_WEBHOOK_SECRET` | Секрет для проверки вебхуков Remnawave. |
-| `USER_SQUAD_UUIDS` | Internal Squads, в которые добавляются пользователи. |
-| `USER_EXTERNAL_SQUAD_UUID` | External Squad для пользователей, если он используется. |
-| `USER_TRAFFIC_LIMIT_GB` | Лимит трафика для режима без JSON-каталога тарифов. `0` означает безлимит. |
-| `USER_TRAFFIC_STRATEGY` | Стратегия лимита трафика для режима без JSON-каталога тарифов. |
-| `USER_HWID_DEVICE_LIMIT` | Лимит HWID-устройств для пользователей. `0` означает безлимит. |
-
-При включенном каталоге тарифов значения `squad_uuids`, `monthly_gb`, `traffic_packages` и `hwid_device_limit` берутся из выбранного тарифа. Подробно это описано в [tariffs.md](tariffs.md).
-
-## Платежи
-
-| Переменная | Назначение |
-| --- | --- |
-| `PAYMENT_METHODS_ORDER` | Порядок кнопок оплаты через запятую: `severpay`, `wata`, `freekassa`, `platega`, `yookassa`, `stars`, `cryptopay`. |
-| `SUBSCRIPTION_PURCHASE_DESCRIPTION_ENABLED` | Показывать описание подписки перед выбором срока покупки или продления в Telegram и Web App. |
-| `SUBSCRIPTION_PURCHASE_DESCRIPTION_RU` / `SUBSCRIPTION_PURCHASE_DESCRIPTION_EN` | Текст описания подписки для русской и английской локалей; эти же значения можно переопределить в админке. |
-| `PAYMENT_<METHOD>_WEBAPP_LABEL_RU` / `PAYMENT_<METHOD>_WEBAPP_LABEL_EN` / `PAYMENT_<METHOD>_WEBAPP_ICON` | Необязательная мультиязычная кастомизация текста и lucide-иконки кнопки оплаты в Web App. |
-| `PAYMENT_<METHOD>_TELEGRAM_LABEL_RU` / `PAYMENT_<METHOD>_TELEGRAM_LABEL_EN` / `PAYMENT_<METHOD>_TELEGRAM_EMOJI` | Необязательная мультиязычная кастомизация текста и эмодзи кнопки оплаты в Telegram-боте. |
-| `YOOKASSA_ENABLED` | Включает YooKassa. |
-| `YOOKASSA_SHOP_ID` / `YOOKASSA_SECRET_KEY` | Данные магазина YooKassa. |
-| `YOOKASSA_RETURN_URL` | URL возврата пользователя после оплаты. |
-| `YOOKASSA_DEFAULT_RECEIPT_EMAIL` | Email по умолчанию для чеков YooKassa. |
-| `YOOKASSA_VAT_CODE` | Код НДС для чеков. |
-| `YOOKASSA_AUTOPAYMENTS_ENABLED` | Включает автопродление через сохраненные способы оплаты YooKassa. |
-| `YOOKASSA_AUTOPAYMENTS_REQUIRE_CARD_BINDING` | Управляет обязательной привязкой карты при оплате. |
-| `FREEKASSA_ENABLED` | Включает FreeKassa. |
-| `FREEKASSA_MERCHANT_ID` / `FREEKASSA_API_KEY` / `FREEKASSA_SECOND_SECRET` | Данные FreeKassa и секрет уведомлений. |
-| `FREEKASSA_PAYMENT_IP` | Внешний IP сервера для запроса оплаты FreeKassa. |
-| `FREEKASSA_PAYMENT_METHOD_ID` | ID метода оплаты FreeKassa. |
-| `FREEKASSA_TRUSTED_IPS` | Список IP источников вебхуков FreeKassa (через запятую). |
-| `PLATEGA_ENABLED` | Включает Platega. |
-| `PLATEGA_BASE_URL` | Базовый URL API Platega. |
-| `PLATEGA_MERCHANT_ID` / `PLATEGA_SECRET` | Данные Platega. |
-| `PLATEGA_PAYMENT_METHOD` | Общий ID метода в API Platega; при отдельных кнопках СБП/крипто может использоваться как fallback для метода СБП (см. `PLATEGA_SBP_METHOD`). |
-| `PLATEGA_SBP_ENABLED` / `PLATEGA_CRYPTO_ENABLED` | Отдельные кнопки «СБП» и «крипто» в Platega. |
-| `PLATEGA_SBP_METHOD` / `PLATEGA_CRYPTO_METHOD` | ID методов Platega для СБП и крипто. |
-| `PLATEGA_RETURN_URL` / `PLATEGA_FAILED_URL` | URL возврата после оплаты или ошибки. |
-| `SEVERPAY_ENABLED` | Включает SeverPay. |
-| `SEVERPAY_MID` / `SEVERPAY_TOKEN` | Данные SeverPay. |
-| `SEVERPAY_BASE_URL` | Базовый URL API SeverPay. |
-| `SEVERPAY_RETURN_URL` | URL возврата после оплаты. |
-| `SEVERPAY_LIFETIME_MINUTES` | Время жизни платежной ссылки. |
-| `WATA_ENABLED` | Включает Wata. |
-| `WATA_API_TOKEN` | Bearer-токен терминала Wata. |
-| `WATA_BASE_URL` | Базовый URL API Wata (`https://api.wata.pro/api/h2h`, для песочницы `https://api-sandbox.wata.pro/api/h2h`). |
-| `WATA_RETURN_URL` / `WATA_FAILED_URL` | URL возврата после успешной или неуспешной оплаты. |
-| `WATA_PAYMENT_LINK_TTL_DAYS` | Время жизни платежной ссылки в днях, от 1 до 30. |
-| `WATA_WEBHOOK_VERIFY_SIGNATURE` | Проверять `X-Signature` вебхука через RSA/SHA512. |
-| `WATA_PUBLIC_KEY` | Необязательный публичный ключ Wata для проверки вебхуков; если пусто, backend загрузит его из API. |
-| `WATA_TRUSTED_IPS` | IP-адреса Wata, с которых принимаются вебхуки. |
-| `CRYPTOPAY_ENABLED` | Включает CryptoPay. |
-| `CRYPTOPAY_TOKEN` | Токен CryptoPay App. |
-| `CRYPTOPAY_NETWORK` | Сеть: `mainnet` или `testnet`. |
-| `CRYPTOPAY_CURRENCY_TYPE` | Тип валюты: `fiat` или `crypto`. |
-| `CRYPTOPAY_ASSET` | Актив (например `RUB`, `USDT`). |
-| `STARS_ENABLED` | Включает Telegram Stars. |
-
-Вебхуки платежных систем должны проксироваться на порт `WEB_SERVER_PORT`. Примеры маршрутов есть в [deployment.md](deployment.md).
-
-## Тарифы
-
-| Переменная | Назначение |
-| --- | --- |
-| `TARIFFS_CONFIG_PATH` | Путь к JSON-каталогу тарифов. По умолчанию `data/tariffs.json`. |
-| `TARIFF_TRAFFIC_WARNING_LEVELS` | Проценты предупреждений по трафику, например `85,90,95`. |
-| `RUB_PRICE_1_MONTH`, `RUB_PRICE_3_MONTHS`, `RUB_PRICE_6_MONTHS`, `RUB_PRICE_12_MONTHS` | Цены подписок в рублях для режима без JSON-каталога. |
-| `STARS_PRICE_1_MONTH`, `STARS_PRICE_3_MONTHS`, `STARS_PRICE_6_MONTHS`, `STARS_PRICE_12_MONTHS` | Цены подписок в Telegram Stars для режима без JSON-каталога. |
-| `1_MONTH_ENABLED`, `3_MONTHS_ENABLED`, `6_MONTHS_ENABLED`, `12_MONTHS_ENABLED` | Доступность периодов подписки для режима без JSON-каталога. |
-| `TRAFFIC_PACKAGES` | Пакеты трафика в рублях для режима без JSON-каталога, например `10:199,50:799`. |
-| `STARS_TRAFFIC_PACKAGES` | Пакеты трафика в Telegram Stars для режима без JSON-каталога. |
-
-Если файл из `TARIFFS_CONFIG_PATH` существует, бот использует каталог тарифов. Если файла нет, применяется конфигурация из переменных `.env`.
-
-В штатном `docker-compose.yml` данные хранятся в named volumes. Если для локальной разработки включён bind mount `./data:/app/data`, админка сможет сохранять `data/tariffs.json`, каталог тем (`data/themes`), кеш логотипа Web App (`data/webapp-logo`) и animated emoji (`data/webapp-emoji`) прямо в рабочую копию. Если bind mount включён на Ubuntu-сервере, создайте подкаталоги и отдайте `data` UID `10001`, под которым работает приложение внутри контейнера:
-
-```bash
-mkdir -p data/themes data/webapp-logo data/webapp-emoji
-chown -R 10001:10001 data
-chmod -R u+rwX data
-```
-
-После изменения compose-файла или прав пересоздайте контейнер:
-
-```bash
-docker compose up -d --build --force-recreate
-```
-
-Переопределения из веб-админки сохраняются в БД и применяются поверх `.env` без перезапуска. Для платежных методов кнопка отображается только если соответствующий `*_ENABLED=true` и сервис настроен.
-
-Редактор тарифов в админке сохраняет не override в БД, а сам JSON-файл `TARIFFS_CONFIG_PATH`. Редактор настроек админки, наоборот, работает через allowlist из `backend/bot/app/web/admin_settings_manifest.py` и сохраняет overrides в БД. Через него можно менять только заявленные в manifest параметры приложения; остальные параметры остаются в `.env`. Подробнее: [admin.md](admin.md).
-
-## Web App и email-вход
-
-| Переменная | Назначение |
-| --- | --- |
-| `WEBAPP_ENABLED` | Включает Web App в том же контейнере. |
-| `WEBAPP_SERVER_HOST` / `WEBAPP_SERVER_PORT` | Внутренний aiohttp server для WebApp API/auth/theme assets. По умолчанию порт `8081`; статический frontend отдается отдельным nginx image. |
-| `SUBSCRIPTION_MINI_APP_URL` | Публичный URL Web App. |
-| `WEBAPP_TITLE` | Заголовок Web App. |
-| `WEBAPP_THEMES_DIR` | Каталог тем Web App. По умолчанию `data/themes`; внутри ожидаются папки `<key>/theme.json` и опциональные CSS/ассеты. |
-| `WEBAPP_DEFAULT_THEME` | Опциональный override темы по ключу, например `light` или `neon`. Если пусто, используется `default` из дескрипторов тем. |
-| `WEBAPP_SESSION_SECRET` | HMAC-секрет сессий Web App. |
-| `WEBHOOK_SECRET_TOKEN` | Секретный токен, с которым Telegram шлёт обновления на вебхук. |
-| `WEBAPP_SESSION_TTL_SECONDS` | Время жизни сессии Web App. |
-| `WEBAPP_AUTH_MAX_AGE_SECONDS` | Максимальный возраст `initData` Telegram Mini App. |
-| `WEBAPP_LOGIN_TOKEN_TTL_SECONDS` | Время жизни ссылки «войти с другого устройства» / внешнего логина. |
-| `TELEGRAM_OAUTH_CLIENT_ID` / `TELEGRAM_OAUTH_CLIENT_SECRET` | Данные Telegram OAuth / OpenID Connect из BotFather. |
-| `TELEGRAM_OAUTH_REQUEST_ACCESS` | Дополнительные разрешения Telegram Login, например `write`. |
-| `SMTP_HOST`, `SMTP_PORT`, `SMTP_FALLBACK_PORTS` | SMTP-подключение для email-кодов; резервные порты перебираются при ошибке основного. |
-| `SMTP_TIMEOUT_SECONDS` | Таймаут одной попытки подключения и отправки. |
-| `SMTP_STARTTLS` / `SMTP_USE_SSL` | STARTTLS на обычном порту (например 587) и SSL-обёртка (часто порт 465). |
-| `SMTP_USERNAME` / `SMTP_PASSWORD` | Логин и пароль или SMTP key. |
-| `SMTP_FROM_EMAIL` / `SMTP_FROM_NAME` | Отправитель писем с кодом; адрес из `SMTP_FROM_EMAIL` должен быть разрешён у провайдера. |
-| `EMAIL_CODE_TTL_SECONDS` | Срок действия email-кода. |
-| `EMAIL_CODE_RESEND_SECONDS` | Пауза перед повторной отправкой кода. |
-| `EMAIL_CODE_MAX_ATTEMPTS` | Максимум попыток ввода одного кода. |
-| `BRUTE_FORCE_MAX_FAILURES` | Количество неудачных попыток до временной блокировки. |
-| `BRUTE_FORCE_WINDOW_SECONDS` | Окно учета неудачных попыток. |
-| `BRUTE_FORCE_LOCK_SECONDS` | Длительность временной блокировки. |
-| `MY_DEVICES_SECTION_ENABLED` | Показывает раздел "Мои устройства" и включает API устройств. |
-
-Логотип, emoji-логотип, основной accent-цвет и тема редактируются в разделе **Админка -> Внешний вид** и сохраняются как overrides в базе. Переменные `WEBAPP_PRIMARY_COLOR`, `WEBAPP_LOGO_URL`, `WEBAPP_LOGO_USE_EMOJI`, `WEBAPP_LOGO_EMOJI` и `WEBAPP_LOGO_EMOJI_FONT` в `.env` считаются устаревшими для первичной настройки и игнорируются при загрузке env. Настройка домена, BotFather и callback URL описана в [webapp.md](webapp.md), а создание кастомных тем - в [webapp-themes.md](webapp-themes.md).
-
-### SMTP и вход по email
-
-Вход по email в Web App включается только если заполнены все обязательные поля SMTP: **`SMTP_HOST`**, **`SMTP_PORT`**, **`SMTP_USERNAME`**, **`SMTP_PASSWORD`**, **`SMTP_FROM_EMAIL`**. Имя отправителя **`SMTP_FROM_NAME`** необязательно. Пока конфигурация неполная, интерфейс входа по email не показывается.
-
-Рекомендуемый типичный вариант — **порт 587** с **STARTTLS** (`SMTP_STARTTLS=True`, `SMTP_USE_SSL=False`), как в примере для Brevo в `.env.example`. Для **порта 465** обычно используют обёртку SSL: выставьте `SMTP_USE_SSL=True` и при необходимости `SMTP_STARTTLS=False`; приложение также считает порт 465 SSL-режимом автоматически при отправке.
-
-Если основной порт недоступен, перебираются порты из **`SMTP_FALLBACK_PORTS`** (список через запятую, после `SMTP_PORT`). Таймаут одной попытки подключения и отправки задаёт **`SMTP_TIMEOUT_SECONDS`**.
-
-Порядок действий при подключении нового SMTP:
-
-1. В панели почтового провайдера создайте SMTP-доступ и подтвердите адрес отправителя (**from**), совпадающий с `SMTP_FROM_EMAIL`.
-2. Перенесите хост, порт, логин и пароль (или API-ключ SMTP) в `.env`.
-3. Перезапустите контейнер приложения, чтобы подхватить переменные.
-4. Проверьте вход: на странице Web App запросите код на почту; при ошибках смотрите логи контейнера.
-
-Для ограничений по частоте отправки кодов см. `EMAIL_CODE_*` и `BRUTE_FORCE_*` в таблице выше.
-
-## Пробный период
-
-| Переменная | Назначение |
-| --- | --- |
-| `TRIAL_ENABLED` | Включает пробный период. |
-| `TRIAL_DURATION_DAYS` | Длительность пробного периода в днях. |
-| `TRIAL_TRAFFIC_LIMIT_GB` | Лимит трафика пробного периода. `0` означает безлимит. |
-| `TRIAL_TRAFFIC_STRATEGY` | Стратегия лимита трафика пробного периода. |
-
-## Реферальная программа
-
-| Переменная | Назначение |
-| --- | --- |
-| `REFERRAL_WELCOME_BONUS_DAYS` | Бонус пользователю, который пришел по реферальной ссылке. |
-| `REFERRAL_ONE_BONUS_PER_REFEREE` | Ограничивает бонусы одним успешным платежом приглашенного пользователя. |
-| `REFERRAL_BONUS_DAYS_*` | Бонусные дни пригласившему по периодам подписки. |
-| `REFEREE_BONUS_DAYS_*` | Бонусные дни приглашенному по периодам подписки. |
-| `LEGACY_REFS` | Разрешает ссылки формата `ref_<telegram_id>`. |
-
-В режиме продажи трафика без JSON-каталога бонусы по периодам не отображаются, потому что покупка не привязана к сроку подписки.
-
-## Уведомления о подписке
-
-| Переменная | Назначение |
-| --- | --- |
-| `SUBSCRIPTION_NOTIFICATIONS_ENABLED` | Включает напоминания о подписке в Telegram. |
-| `SUBSCRIPTION_NOTIFY_ON_EXPIRE` | Уведомлять в день окончания. |
-| `SUBSCRIPTION_NOTIFY_AFTER_EXPIRE` | Уведомлять после окончания. |
-| `SUBSCRIPTION_NOTIFY_DAYS_BEFORE` | За сколько дней до окончания напоминать. |
-
-## Чеки самозанятого (LKNPD)
-
-Интеграция с API lknpd.nalog.ru использует переменные с префиксом **`NALOGO_`**:
-
-| Переменная | Назначение |
-| --- | --- |
-| `NALOGO_INN` | ИНН самозанятого. |
-| `NALOGO_PASSWORD` | Пароль для LKNPD / «Мой налог». |
-| `NALOGO_API_URL` | Базовый URL API (по умолчанию `https://lknpd.nalog.ru/api`). |
-| `NALOGO_RECEIPT_NAME_SUBSCRIPTION` | Название позиции чека для подписки; в тексте можно использовать `{months}`. |
-| `NALOGO_RECEIPT_NAME_TRAFFIC` | Название для пакета трафика; плейсхолдер `{gb}`. |
-
-Нужны **оба** поля `NALOGO_INN` и `NALOGO_PASSWORD`; иначе отправка чеков отключается (в логах будет предупреждение).
-
-## Happ crypt4 для ссылок подключения
-
-| Переменная | Назначение |
-| --- | --- |
-| `CRYPT4_ENABLED` | Включить шифрование ссылок happ crypt4. |
-| `CRYPT4_REDIRECT_URL` | Базовый URL редиректа для кнопки подключения (обёртка с query, например `?url=`). |
-
-## Логирование и уведомления в Telegram
-
-| Переменная | Назначение |
-| --- | --- |
-| `LOG_LEVEL` | Уровень логов: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. |
-| `LOGS_PAGE_SIZE` | Размер страницы журнала в админке. |
-| `LOG_CHAT_ID` | ID чата или группы для служебных уведомлений. |
-| `LOG_THREAD_ID` | ID топика в супергруппе (опционально). |
-| `LOG_NEW_USERS` | Уведомлять о новых регистрациях. |
-| `LOG_PAYMENTS` | Уведомлять об успешных платежах. |
-| `LOG_PROMO_ACTIVATIONS` | Уведомлять об активации промокодов. |
-| `LOG_TRIAL_ACTIVATIONS` | Уведомлять об активации пробного периода. |
-| `LOG_SUSPICIOUS_ACTIVITY` | Уведомлять о подозрительных попытках. |
-| `LOG_ADMIN_ACTIONS` | Писать в журнал админки действия пользователей из `ADMIN_IDS`. |
-
-Часть этих переключателей доступна для правки через Web App (allowlist в `backend/bot/app/web/admin_settings_manifest.py`), см. [admin.md](admin.md).
-
-## Миниатюры inline-режима
-
-Превью для inline-результатов задаются `INLINE_REFERRAL_THUMBNAIL_URL`, `INLINE_USER_STATS_THUMBNAIL_URL`, `INLINE_FINANCIAL_STATS_THUMBNAIL_URL`, `INLINE_SYSTEM_STATS_THUMBNAIL_URL` (значения по умолчанию есть в `.env.example`).
-
-## Секреты
-
-`WEBAPP_SESSION_SECRET` и `WEBHOOK_SECRET_TOKEN` могут генерироваться при старте, но для рабочего окружения их лучше задать явно. Иначе после рестарта сессии Web App станут невалидными, а Telegram получит новый `secret_token` для вебхука (старые запросы от API Telegram могут перестать проходить проверку до следующей переустановки вебхука).
+`WEBAPP_SESSION_SECRET` и `WEBHOOK_SECRET_TOKEN` можно сгенерировать так:
 
 ```bash
 openssl rand -hex 32
 ```
+
+Если оставить эти секреты пустыми, приложение сгенерирует их на процесс, но после рестарта Web App-сессии станут невалидными, а Telegram webhook получит новый `secret_token`.
+
+## Настройка через админку
+
+После запуска откройте Mini App под аккаунтом, чей Telegram ID указан в `ADMIN_IDS`, и перейдите в админ-панель.
+
+Рекомендуемый порядок первичной настройки:
+
+1. **Система -> Настройки -> Remnawave**: проверьте `PANEL_API_URL`, `PANEL_API_KEY`, `PANEL_WEBHOOK_SECRET`, базовые squads.
+2. **Система -> Тарифы**: создайте JSON-каталог тарифов, выберите Internal Squads, настройте period/traffic-модели, premium-сквады и HWID-пакеты.
+3. **Система -> Настройки -> Платежи**: включите нужные провайдеры и заполните их ключи.
+4. **Внешний вид**: настройте название, тему, логотип, favicon и accent.
+5. **Система -> Настройки -> Поддержка / Уведомления**: настройте тикеты, лог-чат, email-уведомления и напоминания.
+6. **Общие настройки**: заполните ссылки на поддержку, документы, статус сервиса и обязательный канал, если он нужен.
+
+Изменения из админки пишутся в таблицу `app_setting_overrides`. При сбросе override снова используется значение из `.env` или дефолт из кода.
+
+## Что оставить только в `.env`
+
+Не все настройки стоит переносить в базу. В `.env` остаются:
+
+- токен бота и `ADMIN_IDS`;
+- параметры PostgreSQL, Redis, портов и Compose;
+- `WEBHOOK_BASE_URL`, потому что Telegram webhook устанавливается при старте;
+- стабильные секреты `WEBAPP_SESSION_SECRET` и `WEBHOOK_SECRET_TOKEN`;
+- `WEBAPP_THEMES_DIR`, `TARIFFS_CONFIG_PATH` и низкоуровневые TTL/pool/worker-параметры;
+- Remnawave-доступы как базовый источник правды, даже если для удобства они доступны в админке.
+
+## Файловые данные
+
+В штатном `docker-compose.yml` данные хранятся в named volume `shop-data`. Внутри него лежат тарифы, темы, логотипы и прочие файловые данные приложения.
+
+Если для локальной разработки включаете bind mount `./data:/app/data`, заранее создайте каталоги и отдайте их пользователю контейнера:
+
+```bash
+mkdir -p data/themes data/webapp-logo data/webapp-emoji data/tariffs
+chown -R 10001:10001 data
+chmod -R u+rwX data
+docker compose up -d --force-recreate backend worker
+```
+
+Проверить права можно так:
+
+```bash
+docker compose exec backend sh -lc 'id; touch /app/data/themes/test && rm /app/data/themes/test'
+```
+
+## Дополнительные разделы
+
+- [env-vars.md](env-vars.md) - полный справочник переменных `.env`.
+- [admin.md](admin.md) - как устроены overrides и allowlist настроек.
+- [tariffs.md](tariffs.md) - JSON-каталог тарифов и редактор тарифов.
+- [webapp.md](webapp.md) - домен Mini App, Telegram OAuth и email-вход.
+- [support.md](support.md) - тикеты поддержки и уведомления.
+- [deployment.md](deployment.md) - Docker Compose, reverse proxy, Caddy/Nginx и обновления.

docs/deployment.md

@@ -1,7 +1,7 @@
 # Развертывание
 
 Документ описывает продакшен-запуск после разделения проекта на `backend`, `frontend` и `worker`.
-Перед стартом заполните `.env` по [configuration.md](configuration.md).
+Перед стартом заполните минимальный `.env` по [configuration.md](configuration.md). Полный справочник переменных лежит в [env-vars.md](env-vars.md); после первого входа большинство продуктовых настроек удобнее менять через Web App админку.
 
 ## Быстрый старт
 

docs/env-vars.md

@@ -0,0 +1,408 @@
+# Переменные окружения
+
+`.env` нужен прежде всего для bootstrap: токен бота, доступ к базе, публичный webhook URL и стабильные секреты. После первого входа большая часть продуктовых настроек меняется в Web App админке и сохраняется в БД как override поверх `.env`.
+
+Рекомендуемый порядок:
+
+1. Заполнить минимальный `.env` по `.env.example`.
+2. Запустить стек и войти в Web App под Telegram ID из `ADMIN_IDS`.
+3. Настроить Remnawave, платежи, внешний вид, поддержку, уведомления и тарифы через админку.
+
+## Минимальный bootstrap
+
+| Переменная | Где менять | Назначение |
+| --- | --- | --- |
+| `BOT_TOKEN` | Только `.env` | Токен Telegram-бота. |
+| `ADMIN_IDS` | Только `.env` | Telegram ID администраторов через запятую. Нужен для первого входа в админку. |
+| `WEBHOOK_BASE_URL` | `.env` | Публичный URL backend/webhook-домена. Используется для Telegram, платежных и Remnawave webhook URL. |
+| `POSTGRES_USER` | `.env` / Compose | Пользователь PostgreSQL. |
+| `POSTGRES_PASSWORD` | `.env` / Compose | Пароль PostgreSQL. |
+| `POSTGRES_DB` | `.env` / Compose | Имя базы PostgreSQL. |
+| `WEBAPP_SESSION_SECRET` | `.env` | Стабильный HMAC-секрет сессий Web App. Если пустой, генерируется на процесс, но сессии сбросятся после рестарта. |
+| `WEBHOOK_SECRET_TOKEN` | `.env` | Секрет Telegram webhook. Если пустой, генерируется на процесс. |
+
+## Инфраструктура и Compose
+
+| Переменная | Где менять | Назначение |
+| --- | --- | --- |
+| `APP_ENV_FILE` | CLI/Compose | Путь к env-файлу вместо `.env`. |
+| `IMAGE_TAG` | CLI/Compose | Тег Docker-образов. |
+| `FRONTEND_PORT` | `.env` / Compose | Хостовый порт frontend nginx. По умолчанию `8082`. |
+| `WEB_SERVER_HOST` | `.env` | Внутренний host backend webhook server. Обычно `0.0.0.0`. |
+| `WEB_SERVER_PORT` | `.env` / Compose | Хостовый порт backend webhook server. По умолчанию `8080`. |
+| `WEBAPP_SERVER_HOST` | `.env` | Внутренний host Web App API server. Обычно `0.0.0.0`. |
+| `WEBAPP_SERVER_PORT` | `.env` | Внутренний порт Web App API server. По умолчанию `8081`. |
+| `POSTGRES_HOST` | Compose | Host PostgreSQL. В штатном Compose задается как `postgres`. |
+| `POSTGRES_PORT` | `.env` | Порт PostgreSQL. |
+| `DB_POOL_SIZE` | `.env` | Размер async SQLAlchemy pool. |
+| `DB_MAX_OVERFLOW` | `.env` | Дополнительные transient DB-соединения сверх pool. |
+| `DB_POOL_TIMEOUT_SECONDS` | `.env` | Таймаут ожидания соединения из pool. |
+| `DB_POOL_RECYCLE_SECONDS` | `.env` | Период recycling DB-соединений. |
+| `REDIS_URL` | Compose | Redis для FSM, кеша, rate-limit, очередей и locks. В Compose задается автоматически. |
+| `REDIS_KEY_PREFIX` | `.env` | Префикс Redis-ключей. |
+| `TRUSTED_PROXIES` | `.env` | IP/CIDR reverse proxy, которым доверяется `X-Forwarded-For`. |
+| `HTTP_BIND` / `HTTPS_BIND` | Caddy Compose | Адреса публикации Caddy-варианта. |
+| `NEWT_ID` / `NEWT_SECRET` | Dev Compose | Доступы Newt в dev-compose. |
+
+## Кеши, rate limits и worker
+
+Обычно эти значения не требуют правки.
+
+| Переменная | Назначение |
+| --- | --- |
+| `WEBAPP_ME_CACHE_TTL_SECONDS` | TTL кеша `/api/me`. |
+| `WEBAPP_DEVICES_CACHE_TTL_SECONDS` | TTL кеша устройств Web App. |
+| `PANEL_USER_CACHE_TTL_SECONDS` | TTL кеша Remnawave `/users/{uuid}`. |
+| `PANEL_DEVICES_CACHE_TTL_SECONDS` | TTL кеша устройств пользователя Remnawave. |
+| `PANEL_ALL_USERS_CACHE_TTL_SECONDS` | TTL кеша полных сканов пользователей Remnawave. |
+| `PANEL_ALL_USERS_PAGE_SIZE` | Размер страницы Remnawave `/users`. |
+| `ADMIN_PANEL_STATS_CACHE_TTL_SECONDS` | TTL статистики Remnawave в админке. |
+| `ADMIN_DB_STATS_CACHE_TTL_SECONDS` | TTL дорогих DB-агрегатов админки. |
+| `ADMIN_USERS_LIST_CACHE_TTL_SECONDS` | TTL списка пользователей админки. |
+| `PROFILE_SYNC_CACHE_TTL_SECONDS` | Минимальная пауза между sync Telegram-профиля пользователя. |
+| `PANEL_SYNC_LIFETIME_TRAFFIC_MIN_INTERVAL_SECONDS` | Минимальная пауза записи lifetime-трафика. |
+| `PANEL_SYNC_LIFETIME_TRAFFIC_MIN_DELTA_BYTES` | Дельта lifetime-трафика для более ранней записи. |
+| `WEBAPP_RATE_LIMIT_TTL_SECONDS` | Окно Web App rate limit. |
+| `WEBAPP_RATE_LIMIT_MAX_REQUESTS` | Количество запросов в окне rate limit. |
+| `WEBHOOK_QUEUE_NAME` | Redis queue для тяжелой обработки webhook. |
+| `WEBHOOK_QUEUE_CONCURRENCY` | Количество worker consumers для webhook queue. |
+| `WORKER_PANEL_SYNC_INTERVAL_SECONDS` | Интервал фоновой синхронизации с панелью. |
+| `TARIFF_WORKER_LOCK_TTL_SECONDS` | TTL Redis lock для tariff worker. |
+| `TARIFF_WORKER_TICK_SECONDS` | Интервал tariff worker. |
+| `TARIFF_WORKER_BULK_PANEL_FETCH_THRESHOLD` | Порог активных подписок для bulk fetch пользователей панели. |
+
+## Общие настройки
+
+Эти поля доступны в админке: **Система -> Настройки**.
+
+| Переменная | Назначение |
+| --- | --- |
+| `DEFAULT_LANGUAGE` | Язык по умолчанию: `ru` или `en`. |
+| `DEFAULT_CURRENCY_SYMBOL` | Символ/код валюты в интерфейсе. |
+| `SUPPORT_LINK` | Внешняя ссылка поддержки. |
+| `SERVER_STATUS_URL` | Страница статуса сервиса. |
+| `TERMS_OF_SERVICE_URL` | Условия использования. |
+| `PRIVACY_POLICY_URL` | Политика конфиденциальности. |
+| `USER_AGREEMENT_URL` | Пользовательское соглашение. |
+| `REQUIRED_CHANNEL_ID` | ID обязательного Telegram-канала. |
+| `REQUIRED_CHANNEL_LINK` | Ссылка на обязательный канал. |
+| `START_COMMAND_DESCRIPTION` | Описание `/start` для меню Telegram. |
+| `DISABLE_WELCOME_MESSAGE` | Отключить приветствие на `/start`. |
+
+## Remnawave
+
+Эти поля стоит держать в `.env` как базовую конфигурацию интеграции с панелью. Они также доступны в админке, чтобы можно было быстро поправить доступы или временно переопределить их без ручного редактирования файла и перезапуска.
+
+| Переменная | Назначение |
+| --- | --- |
+| `PANEL_API_URL` | URL API панели, например `https://panel.example.com/api`. |
+| `PANEL_API_KEY` | API-ключ панели. |
+| `PANEL_WEBHOOK_SECRET` | Секрет проверки Remnawave webhook. |
+| `USER_SQUAD_UUIDS` | Internal Squads по умолчанию для legacy-режима без JSON-каталога. |
+| `USER_EXTERNAL_SQUAD_UUID` | Необязательный External Squad. |
+| `USER_TRAFFIC_LIMIT_GB` | Legacy-лимит трафика пользователя. |
+| `USER_TRAFFIC_STRATEGY` | Legacy-стратегия лимита трафика. |
+| `USER_HWID_DEVICE_LIMIT` | Legacy-лимит HWID-устройств по умолчанию. |
+
+## Web App, внешний вид и Telegram Login
+
+Часть внешнего вида (`WEBAPP_PRIMARY_COLOR`, `WEBAPP_LOGO_*`, `WEBAPP_FAVICON_*`) сохранена для совместимости, но env-значения этих полей игнорируются при загрузке. Настраивайте их в **Админка -> Внешний вид**.
+
+| Переменная | Где менять | Назначение |
+| --- | --- | --- |
+| `WEBAPP_ENABLED` | Админка | Включает Web App. |
+| `SUBSCRIPTION_MINI_APP_URL` | Админка | Публичный URL Mini App. |
+| `WEBAPP_TITLE` | Админка | Заголовок Web App. |
+| `WEBAPP_THEMES_DIR` | `.env` | Каталог кастомных тем. |
+| `WEBAPP_DEFAULT_THEME` | `.env` / админка | Ключ темы по умолчанию. |
+| `WEBAPP_SESSION_TTL_SECONDS` | `.env` | Время жизни Web App-сессии. |
+| `WEBAPP_AUTH_MAX_AGE_SECONDS` | `.env` | Максимальный возраст Telegram Mini Apps `initData`. |
+| `WEBAPP_LOGIN_TOKEN_TTL_SECONDS` | `.env` | TTL ссылки внешнего логина. |
+| `TELEGRAM_OAUTH_CLIENT_ID` | `.env` | Client ID Telegram OAuth / OpenID Connect. Если пусто, берется bot ID из `BOT_TOKEN`. |
+| `TELEGRAM_OAUTH_CLIENT_SECRET` | `.env` | Client Secret Telegram OAuth / OpenID Connect. |
+| `TELEGRAM_OAUTH_REQUEST_ACCESS` | `.env` | Дополнительные permissions, например `write`. |
+| `WEBAPP_PRIMARY_COLOR` | Админка | Устаревшее env-поле, игнорируется. |
+| `WEBAPP_LOGO_URL` | Админка | Устаревшее env-поле, игнорируется. |
+| `WEBAPP_LOGO_USE_EMOJI` | Админка | Устаревшее env-поле, игнорируется. |
+| `WEBAPP_LOGO_EMOJI` | Админка | Устаревшее env-поле, игнорируется. |
+| `WEBAPP_LOGO_EMOJI_FONT` | Админка | Устаревшее env-поле, игнорируется. |
+| `WEBAPP_FAVICON_USE_CUSTOM` | Админка | Устаревшее env-поле, игнорируется. |
+| `WEBAPP_FAVICON_URL` | Админка | Устаревшее env-поле, игнорируется. |
+| `WEBAPP_LOGO_FAVICON_URL` | Админка | Устаревшее env-поле, игнорируется. |
+
+## SMTP и email-вход
+
+Email-вход появляется только если заполнены `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD` и `SMTP_FROM_EMAIL`.
+
+| Переменная | Назначение |
+| --- | --- |
+| `SMTP_HOST` | SMTP host. |
+| `SMTP_PORT` | Основной SMTP port. |
+| `SMTP_FALLBACK_PORTS` | Резервные порты через запятую. |
+| `SMTP_TIMEOUT_SECONDS` | Таймаут SMTP-попытки. |
+| `SMTP_USERNAME` | SMTP login. |
+| `SMTP_PASSWORD` | SMTP password/API key. |
+| `SMTP_FROM_EMAIL` | Подтвержденный адрес отправителя. |
+| `SMTP_FROM_NAME` | Имя отправителя. |
+| `SMTP_STARTTLS` | Использовать STARTTLS. |
+| `SMTP_USE_SSL` | Использовать SSL-wrapper. |
+| `EMAIL_CODE_TTL_SECONDS` | TTL email-кода. |
+| `EMAIL_CODE_RESEND_SECONDS` | Пауза перед повторной отправкой. |
+| `EMAIL_CODE_MAX_ATTEMPTS` | Максимум попыток ввода кода. |
+| `BRUTE_FORCE_MAX_FAILURES` | Количество ошибок до временной блокировки. |
+| `BRUTE_FORCE_WINDOW_SECONDS` | Окно учета ошибок. |
+| `BRUTE_FORCE_LOCK_SECONDS` | Длительность блокировки. |
+
+## Платежи
+
+Все включатели, секреты и presentation-настройки провайдеров доступны в админке: **Система -> Настройки -> Платежи**.
+
+| Переменная | Назначение |
+| --- | --- |
+| `PAYMENT_METHODS_ORDER` | Порядок кнопок оплаты: `severpay,wata,freekassa,platega,yookassa,stars,cryptopay,heleket`. |
+| `SUBSCRIPTION_PURCHASE_DESCRIPTION_ENABLED` | Показывать описание подписки перед выбором срока. |
+| `SUBSCRIPTION_PURCHASE_DESCRIPTION_RU` / `SUBSCRIPTION_PURCHASE_DESCRIPTION_EN` | Локализованное описание подписки. |
+| `PAYMENT_<METHOD>_WEBAPP_LABEL_RU` / `PAYMENT_<METHOD>_WEBAPP_LABEL_EN` | Текст кнопки провайдера в Web App. |
+| `PAYMENT_<METHOD>_WEBAPP_ICON` | Lucide-иконка кнопки в Web App. |
+| `PAYMENT_<METHOD>_TELEGRAM_LABEL_RU` / `PAYMENT_<METHOD>_TELEGRAM_LABEL_EN` | Текст кнопки в Telegram. |
+| `PAYMENT_<METHOD>_TELEGRAM_EMOJI` | Emoji кнопки в Telegram. |
+| `STARS_ENABLED` | Включает Telegram Stars. |
+| `YOOKASSA_ENABLED` | Включает YooKassa. |
+| `FREEKASSA_ENABLED` | Включает FreeKassa. |
+| `PLATEGA_ENABLED` | Включает Platega. |
+| `PLATEGA_SBP_ENABLED` / `PLATEGA_CRYPTO_ENABLED` | Отдельные кнопки СБП/крипто Platega. |
+| `SEVERPAY_ENABLED` | Включает SeverPay. |
+| `WATA_ENABLED` | Включает Wata. |
+| `CRYPTOPAY_ENABLED` | Включает CryptoPay. |
+| `HELEKET_ENABLED` | Включает Heleket. |
+
+Конкретные presentation-ключи:
+
+```text
+PAYMENT_YOOKASSA_WEBAPP_LABEL_RU
+PAYMENT_YOOKASSA_WEBAPP_LABEL_EN
+PAYMENT_YOOKASSA_WEBAPP_ICON
+PAYMENT_YOOKASSA_TELEGRAM_LABEL_RU
+PAYMENT_YOOKASSA_TELEGRAM_LABEL_EN
+PAYMENT_YOOKASSA_TELEGRAM_EMOJI
+PAYMENT_FREEKASSA_WEBAPP_LABEL_RU
+PAYMENT_FREEKASSA_WEBAPP_LABEL_EN
+PAYMENT_FREEKASSA_WEBAPP_ICON
+PAYMENT_FREEKASSA_TELEGRAM_LABEL_RU
+PAYMENT_FREEKASSA_TELEGRAM_LABEL_EN
+PAYMENT_FREEKASSA_TELEGRAM_EMOJI
+PAYMENT_PLATEGA_SBP_WEBAPP_LABEL_RU
+PAYMENT_PLATEGA_SBP_WEBAPP_LABEL_EN
+PAYMENT_PLATEGA_SBP_WEBAPP_ICON
+PAYMENT_PLATEGA_SBP_TELEGRAM_LABEL_RU
+PAYMENT_PLATEGA_SBP_TELEGRAM_LABEL_EN
+PAYMENT_PLATEGA_SBP_TELEGRAM_EMOJI
+PAYMENT_PLATEGA_CRYPTO_WEBAPP_LABEL_RU
+PAYMENT_PLATEGA_CRYPTO_WEBAPP_LABEL_EN
+PAYMENT_PLATEGA_CRYPTO_WEBAPP_ICON
+PAYMENT_PLATEGA_CRYPTO_TELEGRAM_LABEL_RU
+PAYMENT_PLATEGA_CRYPTO_TELEGRAM_LABEL_EN
+PAYMENT_PLATEGA_CRYPTO_TELEGRAM_EMOJI
+PAYMENT_SEVERPAY_WEBAPP_LABEL_RU
+PAYMENT_SEVERPAY_WEBAPP_LABEL_EN
+PAYMENT_SEVERPAY_WEBAPP_ICON
+PAYMENT_SEVERPAY_TELEGRAM_LABEL_RU
+PAYMENT_SEVERPAY_TELEGRAM_LABEL_EN
+PAYMENT_SEVERPAY_TELEGRAM_EMOJI
+PAYMENT_WATA_WEBAPP_LABEL_RU
+PAYMENT_WATA_WEBAPP_LABEL_EN
+PAYMENT_WATA_WEBAPP_ICON
+PAYMENT_WATA_TELEGRAM_LABEL_RU
+PAYMENT_WATA_TELEGRAM_LABEL_EN
+PAYMENT_WATA_TELEGRAM_EMOJI
+PAYMENT_STARS_WEBAPP_LABEL_RU
+PAYMENT_STARS_WEBAPP_LABEL_EN
+PAYMENT_STARS_WEBAPP_ICON
+PAYMENT_STARS_TELEGRAM_LABEL_RU
+PAYMENT_STARS_TELEGRAM_LABEL_EN
+PAYMENT_STARS_TELEGRAM_EMOJI
+PAYMENT_CRYPTOPAY_WEBAPP_LABEL_RU
+PAYMENT_CRYPTOPAY_WEBAPP_LABEL_EN
+PAYMENT_CRYPTOPAY_WEBAPP_ICON
+PAYMENT_CRYPTOPAY_TELEGRAM_LABEL_RU
+PAYMENT_CRYPTOPAY_TELEGRAM_LABEL_EN
+PAYMENT_CRYPTOPAY_TELEGRAM_EMOJI
+PAYMENT_HELEKET_WEBAPP_LABEL_RU
+PAYMENT_HELEKET_WEBAPP_LABEL_EN
+PAYMENT_HELEKET_WEBAPP_ICON
+PAYMENT_HELEKET_TELEGRAM_LABEL_RU
+PAYMENT_HELEKET_TELEGRAM_LABEL_EN
+PAYMENT_HELEKET_TELEGRAM_EMOJI
+```
+
+### YooKassa
+
+| Переменная | Назначение |
+| --- | --- |
+| `YOOKASSA_SHOP_ID` | ID магазина. |
+| `YOOKASSA_SECRET_KEY` | Secret key. |
+| `YOOKASSA_RETURN_URL` | URL возврата после оплаты. |
+| `YOOKASSA_DEFAULT_RECEIPT_EMAIL` | Email для чеков по умолчанию. |
+| `YOOKASSA_VAT_CODE` | Код НДС. |
+| `YOOKASSA_AUTOPAYMENTS_ENABLED` | Автопродление через сохраненные способы оплаты. |
+| `YOOKASSA_AUTOPAYMENTS_REQUIRE_CARD_BINDING` | Требовать привязку карты. |
+
+### FreeKassa
+
+| Переменная | Назначение |
+| --- | --- |
+| `FREEKASSA_MERCHANT_ID` | ID магазина. |
+| `FREEKASSA_API_KEY` | API key. |
+| `FREEKASSA_SECOND_SECRET` | Секрет уведомлений. |
+| `FREEKASSA_PAYMENT_IP` | Публичный IP сервера для запроса оплаты. |
+| `FREEKASSA_PAYMENT_METHOD_ID` | ID метода оплаты. |
+| `FREEKASSA_TRUSTED_IPS` | IP-allowlist webhook-источников. |
+
+### Platega
+
+| Переменная | Назначение |
+| --- | --- |
+| `PLATEGA_BASE_URL` | Базовый URL API. |
+| `PLATEGA_MERCHANT_ID` | Merchant ID. |
+| `PLATEGA_SECRET` | API secret. |
+| `PLATEGA_PAYMENT_METHOD` | Legacy/fallback method ID. |
+| `PLATEGA_SBP_METHOD` | Method ID для СБП. |
+| `PLATEGA_CRYPTO_METHOD` | Method ID для крипто. |
+| `PLATEGA_RETURN_URL` | URL успешного возврата. |
+| `PLATEGA_FAILED_URL` | URL неуспешного возврата. |
+
+### SeverPay
+
+| Переменная | Назначение |
+| --- | --- |
+| `SEVERPAY_BASE_URL` | Базовый URL API. |
+| `SEVERPAY_MID` | Merchant MID. |
+| `SEVERPAY_TOKEN` | API token/secret. |
+| `SEVERPAY_RETURN_URL` | URL возврата. |
+| `SEVERPAY_LIFETIME_MINUTES` | Время жизни платежной ссылки. |
+
+### Wata
+
+| Переменная | Назначение |
+| --- | --- |
+| `WATA_BASE_URL` | Базовый URL API. |
+| `WATA_API_TOKEN` | Bearer token. |
+| `WATA_RETURN_URL` | URL успешного возврата. |
+| `WATA_FAILED_URL` | URL неуспешного возврата. |
+| `WATA_PAYMENT_LINK_TTL_DAYS` | TTL платежной ссылки в днях. |
+| `WATA_WEBHOOK_VERIFY_SIGNATURE` | Проверять `X-Signature`. |
+| `WATA_PUBLIC_KEY` | Cached public key; если пусто, загружается из API. |
+| `WATA_TRUSTED_IPS` | IP-allowlist webhook-источников. |
+
+### CryptoPay
+
+| Переменная | Назначение |
+| --- | --- |
+| `CRYPTOPAY_TOKEN` | API token CryptoPay. |
+| `CRYPTOPAY_NETWORK` | `mainnet` или `testnet`. |
+| `CRYPTOPAY_CURRENCY_TYPE` | `fiat` или `crypto`. |
+| `CRYPTOPAY_ASSET` | Актив, например `RUB`, `USDT`, `BTC`. |
+
+### Heleket
+
+| Переменная | Назначение |
+| --- | --- |
+| `HELEKET_BASE_URL` | Базовый URL API. |
+| `HELEKET_MERCHANT_ID` | UUID мерчанта. |
+| `HELEKET_API_KEY` | Payment API key. |
+| `HELEKET_CURRENCY` | Валюта инвойса. |
+| `HELEKET_TO_CURRENCY` | Целевая криптовалюта для конвертации. |
+| `HELEKET_NETWORK` | Сеть, например `tron`, `bsc`, `eth`. |
+| `HELEKET_RETURN_URL` | URL после отмены/истечения. |
+| `HELEKET_SUCCESS_URL` | URL после успешной оплаты. |
+| `HELEKET_LIFETIME_SECONDS` | TTL инвойса: 300..43200. |
+| `HELEKET_VERIFY_WEBHOOK_SIGNATURE` | Проверять подпись webhook. |
+| `HELEKET_TRUSTED_IPS` | IP-allowlist webhook-источников. |
+
+## Тарифы и legacy-цены
+
+Рекомендуемый способ настройки тарифов - раздел **Система -> Тарифы** в админке. Он сохраняет JSON в `TARIFFS_CONFIG_PATH`.
+
+| Переменная | Назначение |
+| --- | --- |
+| `TARIFFS_CONFIG_PATH` | Путь к JSON-каталогу тарифов. |
+| `TARIFF_TRAFFIC_WARNING_LEVELS` | Уровни предупреждений по трафику в процентах. |
+| `1_MONTH_ENABLED` | Legacy-доступность периода 1 месяц без JSON-каталога. |
+| `3_MONTHS_ENABLED` | Legacy-доступность периода 3 месяца без JSON-каталога. |
+| `6_MONTHS_ENABLED` | Legacy-доступность периода 6 месяцев без JSON-каталога. |
+| `12_MONTHS_ENABLED` | Legacy-доступность периода 12 месяцев без JSON-каталога. |
+| `RUB_PRICE_1_MONTH`, `RUB_PRICE_3_MONTHS`, `RUB_PRICE_6_MONTHS`, `RUB_PRICE_12_MONTHS` | Legacy-цены RUB. |
+| `STARS_PRICE_1_MONTH`, `STARS_PRICE_3_MONTHS`, `STARS_PRICE_6_MONTHS`, `STARS_PRICE_12_MONTHS` | Legacy-цены Stars. |
+| `TRAFFIC_PACKAGES` | Legacy-пакеты трафика RUB, формат `10:199,50:799`. |
+| `STARS_TRAFFIC_PACKAGES` | Legacy-пакеты трафика Stars. |
+
+## Trial, referral и уведомления
+
+Эти настройки доступны в админке.
+
+| Переменная | Назначение |
+| --- | --- |
+| `TRIAL_ENABLED` | Включает пробный период. |
+| `TRIAL_DURATION_DAYS` | Длительность пробного периода. |
+| `TRIAL_TRAFFIC_LIMIT_GB` | Лимит трафика пробного периода. |
+| `TRIAL_TRAFFIC_STRATEGY` | Стратегия лимита пробного периода. |
+| `REFERRAL_ONE_BONUS_PER_REFEREE` | Ограничить бонусы одним успешным платежом приглашенного. |
+| `REFERRAL_WELCOME_BONUS_DAYS` | Приветственный бонус пришедшему по реферальной ссылке. |
+| `LEGACY_REFS` | Разрешить ссылки `ref_<telegram_id>`. |
+| `REFERRAL_BONUS_DAYS_1_MONTH`, `REFERRAL_BONUS_DAYS_3_MONTHS`, `REFERRAL_BONUS_DAYS_6_MONTHS`, `REFERRAL_BONUS_DAYS_12_MONTHS` | Legacy-бонусы пригласившему. |
+| `REFEREE_BONUS_DAYS_1_MONTH`, `REFEREE_BONUS_DAYS_3_MONTHS`, `REFEREE_BONUS_DAYS_6_MONTHS`, `REFEREE_BONUS_DAYS_12_MONTHS` | Legacy-бонусы приглашенному. |
+| `SUBSCRIPTION_NOTIFICATIONS_ENABLED` | Включает напоминания о подписке. |
+| `SUBSCRIPTION_NOTIFY_ON_EXPIRE` | Уведомлять в день окончания. |
+| `SUBSCRIPTION_NOTIFY_AFTER_EXPIRE` | Уведомлять после окончания. |
+| `SUBSCRIPTION_NOTIFY_DAYS_BEFORE` | За сколько дней предупреждать. |
+
+## Поддержка
+
+Подробный сценарий описан в [support.md](support.md).
+
+| Переменная | Назначение |
+| --- | --- |
+| `SUPPORT_TICKETS_ENABLED` | Включает тикеты в Mini App. |
+| `SUPPORT_ADMIN_EMAIL_NOTIFICATIONS_ENABLED` | Email-уведомления администраторам. |
+| `SUPPORT_TICKET_MAX_BODY_LENGTH` | Максимальная длина сообщения. |
+| `SUPPORT_TICKET_MAX_SUBJECT_LENGTH` | Максимальная длина темы. |
+| `SUPPORT_TICKET_RATE_LIMIT_PER_HOUR` | Лимит новых тикетов в час. |
+| `SUPPORT_ADMIN_NOTIFICATION_COOLDOWN_SECONDS` | Cooldown Telegram/log уведомлений. |
+| `SUPPORT_ADMIN_EMAIL_COOLDOWN_SECONDS` | Cooldown email-уведомлений. |
+
+## Логирование
+
+Часть настроек доступна в админке.
+
+| Переменная | Назначение |
+| --- | --- |
+| `LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. |
+| `LOGS_PAGE_SIZE` | Размер страницы логов в админке. |
+| `LOG_CHAT_ID` | Telegram chat/group ID для служебных уведомлений. |
+| `LOG_THREAD_ID` | Topic/thread ID общего лог-чата. |
+| `LOG_SUPPORT_THREAD_ID` | Topic/thread ID поддержки. |
+| `LOG_NEW_USERS` | Логировать новые регистрации. |
+| `LOG_PAYMENTS` | Логировать платежи. |
+| `LOG_SUPPORT` | Логировать тикеты поддержки. |
+| `LOG_PROMO_ACTIVATIONS` | Логировать активации промокодов. |
+| `LOG_TRIAL_ACTIVATIONS` | Логировать активации trial. |
+| `LOG_SUSPICIOUS_ACTIVITY` | Логировать подозрительную активность. |
+| `LOG_ADMIN_ACTIONS` | Логировать действия администраторов. |
+
+## Чеки, ссылки подключения и inline
+
+| Переменная | Назначение |
+| --- | --- |
+| `NALOGO_INN` | ИНН самозанятого для LKNPD. |
+| `NALOGO_PASSWORD` | Пароль LKNPD / «Мой налог». |
+| `NALOGO_API_URL` | Базовый URL LKNPD API. |
+| `NALOGO_RECEIPT_NAME_SUBSCRIPTION` | Название позиции чека подписки. |
+| `NALOGO_RECEIPT_NAME_TRAFFIC` | Название позиции чека пакета трафика. |
+| `CRYPT4_ENABLED` | Включает happ crypt4 для ссылок подключения. |
+| `CRYPT4_REDIRECT_URL` | URL-обертка для кнопки подключения. |
+| `CRYPT4_LINK_CACHE_TTL_SECONDS` | TTL кеша crypt4-ссылок. |
+| `MY_DEVICES_SECTION_ENABLED` | Показывать раздел «Мои устройства». |
+| `INLINE_REFERRAL_THUMBNAIL_URL` | Превью inline-результата рефералов. |
+| `INLINE_USER_STATS_THUMBNAIL_URL` | Превью inline-результата пользовательской статистики. |
+| `INLINE_FINANCIAL_STATS_THUMBNAIL_URL` | Превью inline-результата финансовой статистики. |
+| `INLINE_SYSTEM_STATS_THUMBNAIL_URL` | Превью inline-результата системной статистики. |

docs/support.md

@@ -0,0 +1,82 @@
+# Поддержка
+
+В проекте есть два канала поддержки:
+
+- внешняя ссылка `SUPPORT_LINK`, которая ведет пользователя в Telegram-чат, канал, форму или любой другой публичный URL;
+- встроенные тикеты Web App / Mini App, если включен `SUPPORT_TICKETS_ENABLED`.
+
+Внешняя ссылка остается простым резервным каналом. Тикеты дают полноценный диалог внутри личного кабинета: пользователь создает обращение, видит историю ответов, получает счетчик непрочитанных сообщений, а администратор отвечает из админ-панели.
+
+## Пользовательский сценарий
+
+Раздел **Поддержка** появляется в Web App, когда `SUPPORT_TICKETS_ENABLED=True`. Пользователь может:
+
+- создать тикет с темой, категорией, приоритетом и первым сообщением;
+- выбрать категорию `billing`, `technical`, `account` или `other`;
+- выбрать приоритет `normal` или `high`;
+- открыть список своих тикетов с фильтром по активным и всем обращениям;
+- отвечать в открытом тикете и видеть ответы поддержки;
+- перейти по `SUPPORT_LINK`, если нужна внешняя поддержка.
+
+Заблокированные пользователи не могут создавать тикеты и отвечать в них. Для пользователей показываются только обычные сообщения: внутренние заметки администраторов скрыты.
+
+## Админский сценарий
+
+В админ-панели тикеты доступны в разделе **Коммуникации -> Поддержка**. Доступ проверяется так же, как и для остальных `/api/admin/*`: нужна Web App-сессия пользователя, чей Telegram ID указан в `ADMIN_IDS`.
+
+Администратор может:
+
+- видеть сводку по открытым, ожидающим ответа, закрытым и непрочитанным тикетам;
+- фильтровать обращения по статусу, приоритету, категории и назначенному администратору;
+- искать по теме, username, имени и email пользователя;
+- сортировать по обновлению, созданию или важности;
+- отвечать пользователю, менять статус, категорию, приоритет и исполнителя;
+- оставлять внутренние заметки, которые видны только администраторам;
+- открыть карточку пользователя и видеть контекст подписки: тариф, статус, остаток времени, обычный и premium-трафик.
+
+Статусы тикета: `open`, `awaiting_user`, `awaiting_admin`, `resolved`, `closed`. При создании тикет сразу получает статус `awaiting_admin`; ответ пользователя переводит незакрытый тикет в `awaiting_admin`, ответ администратора - в `awaiting_user`. Закрытые статусы считаются `resolved` и `closed`.
+
+## Уведомления
+
+Новые тикеты и ответы пользователя могут отправляться в Telegram-уведомления администраторам и в лог-чат. Для отдельного топика поддержки используйте `LOG_SUPPORT_THREAD_ID`; если он пустой, сообщения идут в общий `LOG_THREAD_ID`/чат по настройкам логирования.
+
+Повторные уведомления по одному непрочитанному тикету ограничиваются cooldown-настройками, чтобы не заспамить админов:
+
+- `SUPPORT_ADMIN_NOTIFICATION_COOLDOWN_SECONDS` - пауза для Telegram/log уведомлений;
+- `SUPPORT_ADMIN_EMAIL_COOLDOWN_SECONDS` - пауза для email-уведомлений.
+
+Email-уведомления администраторам включаются через `SUPPORT_ADMIN_EMAIL_NOTIFICATIONS_ENABLED=True`. Письма отправляются только администраторам из `ADMIN_IDS`, у которых в базе есть email. Для отправки нужен рабочий SMTP-конфиг, как и для входа по email.
+
+Ответ администратора и закрытие тикета дополнительно отправляются пользователю в Telegram, если у него есть Telegram-аккаунт, и на email, если он привязан.
+
+## Настройки
+
+| Переменная | Назначение |
+| --- | --- |
+| `SUPPORT_LINK` | Внешняя ссылка поддержки. Показывается в боте и Web App как быстрый способ связаться с командой. |
+| `SUPPORT_TICKETS_ENABLED` | Включает раздел тикетов в Mini App и разрешает создание обращений. |
+| `SUPPORT_TICKET_MAX_BODY_LENGTH` | Максимальная длина сообщения тикета. |
+| `SUPPORT_TICKET_MAX_SUBJECT_LENGTH` | Максимальная длина темы тикета. |
+| `SUPPORT_TICKET_RATE_LIMIT_PER_HOUR` | Сколько новых тикетов пользователь может создать за час; `0` отключает лимит. |
+| `LOG_SUPPORT` | Включает Telegram/log уведомления по тикетам поддержки. |
+| `LOG_SUPPORT_THREAD_ID` | Необязательный ID топика в лог-чате для сообщений поддержки. |
+| `SUPPORT_ADMIN_EMAIL_NOTIFICATIONS_ENABLED` | Включает email-уведомления администраторам о новых тикетах и ответах пользователей. |
+| `SUPPORT_ADMIN_NOTIFICATION_COOLDOWN_SECONDS` | Минимальная пауза между повторными Telegram/log уведомлениями по одному непрочитанному тикету. |
+| `SUPPORT_ADMIN_EMAIL_COOLDOWN_SECONDS` | Минимальная пауза между повторными email-уведомлениями по одному непрочитанному тикету. |
+
+Все эти параметры описаны в [env-vars.md](env-vars.md). Основной рекомендуемый способ менять их - админка **Система -> Настройки -> Поддержка**; значения применяются как override поверх `.env`.
+
+## API и хранение
+
+Пользовательские маршруты:
+
+- `GET /api/support/tickets` - список тикетов пользователя;
+- `POST /api/support/tickets` - создать тикет;
+- `GET /api/support/tickets/{id}` - открыть тикет;
+- `POST /api/support/tickets/{id}/messages` - отправить ответ;
+- `POST /api/support/tickets/{id}/read` - отметить сообщения прочитанными;
+- `GET /api/support/unread` - счетчик непрочитанных ответов поддержки.
+
+Админские маршруты находятся под `/api/admin/support/*`: список, карточка тикета, ответ, изменение статуса/приоритета/категории/исполнителя, отметка прочитанного и статистика.
+
+Данные хранятся в таблицах `support_tickets` и `support_ticket_messages`; миграция применяется автоматически сервисом `migrate` при `docker compose up -d --build`.

docs/webapp.md

@@ -11,10 +11,11 @@ Web App собирается в отдельный `frontend` image и отда
 - доступные тарифы, способы оплаты и платежный статус;
 - смену тарифа, обычную докупку трафика и докупку premium-трафика при настроенном каталоге тарифов;
 - раздел "Мои устройства" при `MY_DEVICES_SECTION_ENABLED=True`;
+- раздел "Поддержка" с тикетами и внешней ссылкой `SUPPORT_LINK` при включенном `SUPPORT_TICKETS_ENABLED`;
 - реферальную ссылку и статистику приглашений;
 - привязку email и Telegram к одному аккаунту.
 
-Для администраторов из `ADMIN_IDS` Web App также показывает админ-панель: статистику, **пользователей** (поиск, фильтры, premium-трафик), рассылки, промокоды, логи, настройки и редактор тарифов. Подробности: [admin.md](admin.md).
+Для администраторов из `ADMIN_IDS` Web App также показывает админ-панель: статистику, **пользователей** (поиск, фильтры, premium-трафик), поддержку, рассылки, промокоды, логи, настройки и редактор тарифов. Подробности: [admin.md](admin.md).
 
 ## Настройки `.env`
 
@@ -45,12 +46,18 @@ SMTP_USERNAME=<smtp-login>
 SMTP_PASSWORD=<smtp-password-or-key>
 SMTP_FROM_EMAIL=no-reply@domain.com
 SMTP_FROM_NAME=Remnawave Minishop
+
+SUPPORT_LINK=https://t.me/your_support_link
+SUPPORT_TICKETS_ENABLED=True
+SUPPORT_TICKET_RATE_LIMIT_PER_HOUR=5
 ```
 
 Внешний вид настраивается в админке: раздел **Внешний вид** управляет логотипом, emoji-логотипом, accent-цветом, выбранной темой и масштабом логотипа. Кастомные темы читаются из `WEBAPP_THEMES_DIR`, а `WEBAPP_DEFAULT_THEME` может принудительно выбрать тему по ключу. Подробный контракт `theme.json`, CSS/asset-роуты и пайплайн создания темы описаны в [webapp-themes.md](webapp-themes.md).
 
 Если SMTP-настройки не заполнены, вход по email скрывается.
 
+Тикеты поддержки включаются через `SUPPORT_TICKETS_ENABLED`; внешний резервный контакт задается `SUPPORT_LINK`. Полный сценарий пользователя, админа и уведомлений описан в [support.md](support.md).
+
 ## Telegram-авторизация
 
 Внутри Telegram Mini App пользователь авторизуется через Telegram Mini Apps `initData`. При открытии страницы вне Telegram используется Telegram OAuth / OpenID Connect Authorization Code Flow с PKCE, callback `/auth/telegram/callback`, `nonce` и серверной проверкой `id_token` по JWKS Telegram.