From dab70d5a97e8be0ef086b05d32c8a2a5ea7c1163 Mon Sep 17 00:00:00 2001 From: 3252a8 <3252a8@proton.me> Date: Sat, 23 May 2026 16:22:57 +0300 Subject: [PATCH] docs: update install guides documentation --- README.md | 6 ++++-- docs/admin.md | 10 ++++++++++ docs/configuration.md | 12 ++++++++---- docs/env-vars.md | 8 ++++++++ docs/webapp-themes.md | 3 ++- docs/webapp.md | 25 +++++++++++++++++++++++++ 6 files changed, 57 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 1fde3f3..3dad18a 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи - просмотр статуса подписки, даты окончания, ссылки подключения и трафика; - покупка подписок, пакетов трафика, обычная и premium-докупка трафика, докупка устройств по настроенному каталогу тарифов; - Web App / Mini App с входом через Telegram или email; +- встроенные инструкции установки в Mini App: личный экран `/install` и публичная ссылка `/s/` для передачи инструкции; - пробный период, промокоды и реферальная программа; - оплата через YooKassa, FreeKassa, Platega, SeverPay, Wata, CryptoPay, Heleket и Telegram Stars; - тикеты поддержки в Web App и внешняя ссылка на поддержку; @@ -26,6 +27,7 @@ Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи - список пользователей с поиском, фильтрами и колонкой premium-трафика; - блокировка пользователей, поддержка через тикеты, рассылки, промокоды, логи действий и настройка разрешенных параметров приложения поверх `.env`; - редактор JSON-каталога тарифов с period/traffic-моделями, Internal Squads, premium-сквадами и HWID-пакетами; +- настройки инструкций подключения: чтение конфига Subscription Page из Remnawave Panel, опциональный JSON-override и переключатель поведения кнопок бота; - ручная синхронизация пользователей и подписок с панелью. ## Документация @@ -34,7 +36,7 @@ Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи - [Переменные `.env`](docs/env-vars.md) - полный справочник всех env-ключей по разделам. - [Тарифы](docs/tariffs.md) - каталог тарифов, period- и traffic-модели, обычные и premium-докупки, premium-сквады, смена тарифа, HWID-лимиты и обработка трафика. - [Админ-панель](docs/admin.md) - права доступа, настройки, редактор тарифов, premium-сквады и сохранение JSON-каталога. -- [Web App / Mini App](docs/webapp.md) - отдельный порт, домен, Telegram OAuth, email-вход и реферальные ссылки. +- [Web App / Mini App](docs/webapp.md) - отдельный порт, домен, Telegram OAuth, email-вход, инструкции установки и реферальные ссылки. - [Поддержка](docs/support.md) - тикеты в Mini App, входящий список админки, уведомления, лимиты и внешняя ссылка поддержки. - [Темы Web App](docs/webapp-themes.md) - кастомные темы, настройка внешнего вида, логотипы, CSS/ассеты и пайплайн создания новой темы. - [Развертывание](docs/deployment.md) - Docker Compose, reverse proxy, Nginx, Caddy, вебхуки, запуск из образа и обновление версии (`IMAGE_TAG`). @@ -86,7 +88,7 @@ docker compose logs -f backend worker frontend - `PANEL_API_URL`, `PANEL_API_KEY`, `PANEL_WEBHOOK_SECRET` - доступ к Remnawave; - остальные настройки удобнее задать в Web App админке. -После первого входа в админку настройте тарифы, платежные провайдеры, внешний вид, поддержку и уведомления через UI. Полный справочник env-переменных: [docs/env-vars.md](docs/env-vars.md). +После первого входа в админку настройте тарифы, платежные провайдеры, внешний вид, поддержку, уведомления и инструкции подключения через UI. Инструкции установки включены по умолчанию, читают Subscription Page config из Remnawave Panel и при проблемах с конфигом откатываются к обычной ссылке подключения. Полный справочник env-переменных: [docs/env-vars.md](docs/env-vars.md). Для каталога тарифов используется `TARIFFS_CONFIG_PATH` со значением по умолчанию `data/tariffs.json`. Пример формата лежит в [data/tariffs.example.json](data/tariffs.example.json), подробности - в [docs/tariffs.md](docs/tariffs.md). diff --git a/docs/admin.md b/docs/admin.md index 20182df..507b667 100644 --- a/docs/admin.md +++ b/docs/admin.md @@ -10,6 +10,7 @@ - ручная синхронизация с Remnawave; - редактор разрешенных настроек приложения из manifest-файла; - раздел **Внешний вид** для логотипа, emoji-логотипа, выбора темы, accent-цвета, масштаба логотипа и предпросмотра тем; +- раздел **Инструкции подключения** для встроенной страницы установки, поведения кнопок бота и Remnawave Subscription Page config; - редактор JSON-каталога тарифов; - загрузка Internal Squads из Remnawave для выбора в тарифах. @@ -41,6 +42,7 @@ - общие параметры: язык, валюта, ссылки поддержки, документы, обязательный канал, Remnawave-доступы и поведение `/start`; - внешний вид и доступность Web App: название, цвет, логотип, emoji-логотип и `WEBAPP_ENABLED`; +- инструкции подключения: `SUBSCRIPTION_GUIDES_ENABLED`, `SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED`, чтение конфига из Remnawave Panel, JSON-override и fallback-путь к файлу; - legacy-цены без JSON-каталога: периоды подписки, RUB/Stars цены и пакеты трафика; - платежные провайдеры: включение методов, порядок кнопок, публичные параметры и секреты YooKassa, FreeKassa, Platega, SeverPay, Wata, CryptoPay, Heleket и Stars, а также текст и иконки кнопок оплаты; - пробный период, реферальные бонусы, уведомления, логирование, поддержка, раздел устройств, лимит устройств и legacy-лимиты трафика. @@ -49,6 +51,14 @@ Для каждого платежного метода в разделе провайдера доступны presentation-настройки `PAYMENT__WEBAPP_LABEL_RU`, `PAYMENT__WEBAPP_LABEL_EN`, `PAYMENT__WEBAPP_ICON`, `PAYMENT__TELEGRAM_LABEL_RU`, `PAYMENT__TELEGRAM_LABEL_EN` и `PAYMENT__TELEGRAM_EMOJI`. Пустое значение возвращает мультиязычный дефолт из модуля платежного провайдера. Иконка Web App выбирается из уже подключённых lucide-иконок (`frontend/src/lib/components/ui/icons.js`) через модалку в админке. +### Инструкции подключения + +Секция **Система -> Настройки -> Инструкции подключения** управляет встроенным экраном установки. `SUBSCRIPTION_GUIDES_ENABLED` включает `/install` в личном кабинете, а `SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED` заставляет кнопки подключения в Telegram-боте открывать Mini App вместо финальной Remnawave Subscription Page. Оба переключателя включены по умолчанию. + +По умолчанию Minishop читает Remnawave Subscription Page config из панели (`SUBSCRIPTION_PAGE_CONFIG_PANEL_ENABLED=True`). Это основной режим, потому что один и тот же конфиг используется и в панели, и во встроенной инструкции. JSON-поле `SUBSCRIPTION_PAGE_CONFIG_JSON` применяется только когда явно включен `SUBSCRIPTION_PAGE_CONFIG_JSON_OVERRIDE_ENABLED`; иначе оно может храниться в админке, но не влияет на пользователей. `SUBSCRIPTION_PAGE_CONFIG_PATH` остается fallback-путем к локальному v1 JSON-файлу, если конфиг панели отключен или недоступен. + +При сохранении backend валидирует JSON-override как Remnawave Subscription Page v1 config. Ошибки показываются как обычные validation errors настроек, а если рабочий конфиг недоступен, пользовательская кнопка подключения откатывается к старой финальной ссылке подписки. + ## Поддержка Раздел **Коммуникации -> Поддержка** показывает входящий список тикетов из Mini App. В списке доступны фильтры по статусу, приоритету, категории и назначенному администратору, поиск по теме и пользователю, сортировка по обновлению, созданию или важности. diff --git a/docs/configuration.md b/docs/configuration.md index 93eabc0..4808805 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -30,6 +30,7 @@ nano .env | `WEBAPP_SESSION_SECRET` | Стабильный секрет сессий Web App. | | `WEBHOOK_SECRET_TOKEN` | Стабильный secret token Telegram webhook. | | `SUBSCRIPTION_MINI_APP_URL` | Публичный HTTPS URL Mini App/frontend, например `https://app.domain.com/`. Это URL, который открывают кнопки Telegram и который указывается в BotFather; не добавляйте сюда `/api` или webhook-пути. | +| `SUBSCRIPTION_GUIDES_ENABLED`, `SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED` | Встроенные инструкции установки в Web App и кнопках бота. По умолчанию включены; обычно их достаточно менять в админке. | | `PANEL_API_URL`, `PANEL_API_KEY`, `PANEL_WEBHOOK_SECRET` | Базовая интеграция с Remnawave. Эти значения стоит хранить в `.env`, но при необходимости их можно переопределить из админки. | `WEBAPP_SESSION_SECRET` и `WEBHOOK_SECRET_TOKEN` можно сгенерировать так: @@ -58,10 +59,11 @@ openssl rand -hex 32 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. **Общие настройки**: заполните ссылки на поддержку, документы, статус сервиса и обязательный канал, если он нужен. +3. **Система -> Настройки -> Инструкции подключения**: проверьте, что Remnawave Panel отдает нужный Subscription Page config. JSON-override включайте только если нужно временно заменить конфиг панели. +4. **Система -> Настройки -> Платежи**: включите нужные провайдеры и заполните их ключи. +5. **Внешний вид**: настройте название, тему, логотип, favicon и accent. +6. **Система -> Настройки -> Поддержка / Уведомления**: настройте тикеты, лог-чат, email-уведомления и напоминания. +7. **Общие настройки**: заполните ссылки на поддержку, документы, статус сервиса и обязательный канал, если он нужен. Изменения из админки пишутся в таблицу `app_setting_overrides`. При сбросе override снова используется значение из `.env` или дефолт из кода. @@ -76,6 +78,8 @@ openssl rand -hex 32 - `WEBAPP_THEMES_DIR`, `TARIFFS_CONFIG_PATH` и низкоуровневые TTL/pool/worker-параметры; - Remnawave-доступы как базовый источник правды, даже если для удобства они доступны в админке. +Конфиг инструкций установки обычно не нужно хранить в локальном `data`-файле: по умолчанию приложение читает Subscription Page config из Remnawave Panel. `SUBSCRIPTION_PAGE_CONFIG_PATH` и `SUBSCRIPTION_PAGE_CONFIG_JSON` нужны как fallback или явный override из админки. + ## Файловые данные В штатном `docker-compose.yml` данные хранятся в named volume `shop-data`. Внутри него лежат тарифы, темы, логотипы и прочие файловые данные приложения. diff --git a/docs/env-vars.md b/docs/env-vars.md index 467a2be..b426a39 100644 --- a/docs/env-vars.md +++ b/docs/env-vars.md @@ -113,6 +113,12 @@ | --- | --- | --- | | `WEBAPP_ENABLED` | `.env` / админка | Включает Web App. Если `False`, пользовательский Web App и админка недоступны до включения через `.env` и рестарта. | | `SUBSCRIPTION_MINI_APP_URL` | `.env` / админка | Публичный HTTPS URL Mini App/frontend, например `https://app.domain.com/`. Используется в Telegram-кнопках, referral-ссылках, email-входе и BotFather Mini App settings. Не указывайте здесь `/api` или webhook-пути. | +| `SUBSCRIPTION_GUIDES_ENABLED` | `.env` / админка | Включает встроенные инструкции установки в Web App. По умолчанию `True`; если конфиг недоступен или невалиден, кнопка подключения открывает обычную финальную ссылку подписки. | +| `SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED` | `.env` / админка | Включает открытие Mini App `/install` из кнопок бота и показ публичной ссылки инструкции `/s/`. По умолчанию `True`; если выключить, бот ведет на финальную Remnawave Subscription Page. | +| `SUBSCRIPTION_PAGE_CONFIG_PANEL_ENABLED` | `.env` / админка | Читать Remnawave Subscription Page config из панели для встроенных инструкций. По умолчанию `True`, чтобы не дублировать настройку страницы подписки в приложении. | +| `SUBSCRIPTION_PAGE_CONFIG_JSON_OVERRIDE_ENABLED` | `.env` / админка | Включает использование JSON из поля `SUBSCRIPTION_PAGE_CONFIG_JSON` вместо конфига панели. По умолчанию `False`. | +| `SUBSCRIPTION_PAGE_CONFIG_PATH` | `.env` / админка | Fallback-путь к локальному Remnawave Subscription Page v1 JSON config, если конфиг панели выключен или недоступен. По умолчанию `data/subpage-config/multiapp.json`; файл не создается автоматически. | +| `SUBSCRIPTION_PAGE_CONFIG_JSON` | Админка | Опциональный JSON-override Remnawave Subscription Page v1. Применяется только при включенном `SUBSCRIPTION_PAGE_CONFIG_JSON_OVERRIDE_ENABLED`; backend валидирует JSON при сохранении. | | `WEBAPP_TITLE` | Админка | Заголовок Web App. | | `WEBAPP_THEMES_DIR` | `.env` | Каталог кастомных тем. | | `WEBAPP_DEFAULT_THEME` | `.env` / админка | Ключ темы по умолчанию. | @@ -131,6 +137,8 @@ | `WEBAPP_FAVICON_URL` | Админка | Устаревшее env-поле, игнорируется. | | `WEBAPP_LOGO_FAVICON_URL` | Админка | Устаревшее env-поле, игнорируется. | +Инструкции установки совместимы с Remnawave Subscription Page v1 config: `version`, `locales`, `brandingSettings`, `uiConfig`, `baseSettings`, `baseTranslations`, `svgLibrary` и `platforms`. Текстовые поля рендерятся как текст, а SVG из `svgLibrary` проходит санитарную проверку перед отдачей в Web App. + ## SMTP и email-вход Email-вход появляется только если заполнены `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD` и `SMTP_FROM_EMAIL`. diff --git a/docs/webapp-themes.md b/docs/webapp-themes.md index 43b3642..cc3cd57 100644 --- a/docs/webapp-themes.md +++ b/docs/webapp-themes.md @@ -21,6 +21,7 @@ Web App поддерживает файловые темы, предпросмо - базовые цвета Mini App и админки; - радиусы, семейства шрифтов и размер главного логотипа; - любые компоненты через CSS: карточки, навигацию, таблицы, модалки, кнопки, скелетоны, прогресс-бары, состояния hover/active и мобильную/desktop-верстку; +- экран инструкций установки (`/install` и `/s/`): topbar, выбор платформы, карточки приложений, шаги инструкции и QR-блок личной страницы; - иконки и изображения, если CSS ссылается на ассеты темы; - стили только пользовательской части, только админки или обеих частей сразу. @@ -311,7 +312,7 @@ CSS можно писать для пользовательской части } ``` - Начинайте с переопределения CSS-переменных на `.theme-key-neon.app-shell`, затем переходите к конкретным компонентам. Проверяйте минимум: главная, оплата, настройки, модалки, админский дашборд, таблица пользователей, редактор тарифов. + Начинайте с переопределения CSS-переменных на `.theme-key-neon.app-shell`, затем переходите к конкретным компонентам. Проверяйте минимум: главная, `/install`, публичная `/s/`, оплата, настройки, модалки, админский дашборд, таблица пользователей, редактор тарифов. 9. Добавьте ассеты при необходимости. diff --git a/docs/webapp.md b/docs/webapp.md index 388dbbe..9b1ccac 100644 --- a/docs/webapp.md +++ b/docs/webapp.md @@ -10,6 +10,7 @@ Web App собирается в отдельный `frontend` image и отда - отдельную карточку premium-трафика, если у активного тарифа настроены premium-сквады и premium-лимит; - доступные тарифы, способы оплаты и платежный статус; - смену тарифа, обычную докупку трафика и докупку premium-трафика при настроенном каталоге тарифов; +- встроенную инструкцию установки: подбор платформы, список приложений, deeplink-кнопки, QR и действия со ссылкой подписки; - раздел "Мои устройства" при `MY_DEVICES_SECTION_ENABLED=True`; - раздел "Поддержка" с тикетами и внешней ссылкой `SUPPORT_LINK` при включенном `SUPPORT_TICKETS_ENABLED`; - реферальную ссылку и статистику приглашений; @@ -24,6 +25,10 @@ WEBAPP_ENABLED=True WEBAPP_SERVER_HOST=0.0.0.0 WEBAPP_SERVER_PORT=8081 SUBSCRIPTION_MINI_APP_URL=https://app.domain.com/ +SUBSCRIPTION_GUIDES_ENABLED=True +SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED=True +SUBSCRIPTION_PAGE_CONFIG_PANEL_ENABLED=True +SUBSCRIPTION_PAGE_CONFIG_JSON_OVERRIDE_ENABLED=False WEBAPP_TITLE="Моя подписка" WEBAPP_THEMES_DIR=data/themes WEBAPP_DEFAULT_THEME= @@ -54,6 +59,26 @@ SUPPORT_TICKET_RATE_LIMIT_PER_HOUR=5 `SUBSCRIPTION_MINI_APP_URL` - это публичный HTTPS URL именно frontend/Mini App, обычно отдельный домен вроде `https://app.domain.com/`. Его указывают в BotFather в Mini Apps, а бот использует его для кнопок личного кабинета, referral-ссылок и email-входа. Не добавляйте в него `/api`, `/webhook` или путь конкретной страницы. +## Инструкции установки + +Если `SUBSCRIPTION_GUIDES_ENABLED=True`, кнопка **Установить и настроить** в личном кабинете открывает внутренний экран `/install`. Если инструкции выключены, конфиг не загрузился или не прошел валидацию, сохраняется старое поведение: кнопка открывает финальную ссылку подключения из панели. + +Экран `/install` доступен только авторизованному пользователю Web App. Он получает данные из `/api/subscription-guides`, определяет платформу по Telegram Mini Apps platform, `navigator.userAgentData.platform` и `navigator.userAgent`, а затем показывает приложения и шаги из Remnawave Subscription Page v1 config. Ссылки типа `happ://...` и другие deeplink-кнопки открываются прямо из Mini App; в шаблонах заменяются `{{SUBSCRIPTION_LINK}}`, `{{USERNAME}}`, `{{HAPP_CRYPT3_LINK}}` и `{{HAPP_CRYPT4_LINK}}`. + +Конфиг инструкций загружается в таком порядке: + +1. JSON из админки, только если включен `SUBSCRIPTION_PAGE_CONFIG_JSON_OVERRIDE_ENABLED`. +2. Subscription Page config из Remnawave Panel, если включен `SUBSCRIPTION_PAGE_CONFIG_PANEL_ENABLED`. +3. Локальный файл `SUBSCRIPTION_PAGE_CONFIG_PATH` как fallback. + +По умолчанию используются инструкции из Remnawave Panel, чтобы не дублировать настройку страницы подписки в Minishop. Локальный файл в `data/subpage-config/multiapp.json` не создается автоматически. Конфиг кешируется на backend и обновляется при изменении связанных настроек; ошибки загрузки кешируются кратко, чтобы не дергать панель на каждый пользовательский запрос. + +Личный экран показывает QR-код финальной ссылки подписки, кнопку копирования и кнопку **Поделиться**. Для передачи инструкции генерируется публичная ссылка `/s/`: она открывает тот же интерфейс инструкций без авторизации и нижней навигации, но без QR-блока. Публичный payload отдается через `/api/subscription-guides/public/{share_token}` только для активной локальной подписки с валидным share token. + +`SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED=True` включает такое же поведение в Telegram-боте: кнопки подключения открывают Mini App `/install`, а после успешной оплаты, trial или промокода пользователь получает публичную ссылку `/s/`. Если настройку выключить, бот снова отправляет пользователя на финальную Remnawave Subscription Page. + +Конфиг совместим с Remnawave Subscription Page v1 (`version`, `locales`, `brandingSettings`, `uiConfig`, `baseSettings`, `baseTranslations`, `svgLibrary`, `platforms`). Backend проверяет обязательные locale-строки, допустимые платформы и типы кнопок, ссылки на `svgIconKey`, а SVG из `svgLibrary` санитизирует перед отдачей в UI. + Если `WEBAPP_ENABLED=False`, пользовательский Web App и админ-панель не регистрируются. Чтобы снова попасть в админку, включите `WEBAPP_ENABLED=True` в `.env` и перезапустите backend/frontend контейнеры. Внешний вид настраивается в админке: раздел **Внешний вид** управляет логотипом, emoji-логотипом, accent-цветом, выбранной темой и масштабом логотипа. Кастомные темы читаются из `WEBAPP_THEMES_DIR`, а `WEBAPP_DEFAULT_THEME` может принудительно выбрать тему по ключу. Подробный контракт `theme.json`, CSS/asset-роуты и пайплайн создания темы описаны в [webapp-themes.md](webapp-themes.md).