docs: update referral bonus tariff docs

2026-05-29 23:00:18 +03:00
parent 7fe8e676cd
commit e27886e15d
5 changed files with 26 additions and 10 deletions
@@ -51,9 +51,9 @@
 - общие параметры: язык, валюта, ссылки поддержки, документы, обязательный канал, Remnawave-доступы и поведение `/start`;
 - внешний вид и доступность Web App: название, цвет, логотип, emoji-логотип и `WEBAPP_ENABLED`;
 - инструкции подключения: `SUBSCRIPTION_GUIDES_ENABLED`, `SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED`, чтение конфига из Remnawave Panel, JSON-переопределение и резервный путь к файлу;
- legacy-цены без JSON-каталога: периоды подписки, RUB/Stars цены и пакеты трафика;
+- legacy-тарифы без JSON-каталога: периоды подписки, RUB/Stars цены, реферальные бонусы и пакеты трафика;
 - платежные провайдеры: включение методов, порядок кнопок, публичные параметры и секреты YooKassa, FreeKassa, Platega, SeverPay, Wata, CryptoPay, Heleket и Stars, а также текст и иконки кнопок оплаты;
- пробный период, реферальные бонусы, уведомления, логирование, поддержка, раздел устройств, лимит устройств и legacy-лимиты трафика.
+- пробный период, приветственный реферальный бонус, уведомления, логирование, поддержка, раздел устройств, лимит устройств и legacy-лимиты трафика.

 Секретные поля помечены как secret и не должны использоваться для произвольного просмотра старых значений. Настройки, которых нет в manifest, остаются только в `.env` или коде.

@@ -117,7 +117,7 @@
 Редактор тарифа разделен на вкладки:

 - **Основное**: ключ, модель `period`/`traffic`, видимость, названия и описания RU/EN, базовые Internal Squads, HWID-лимит, месячный лимит или курс конвертации;
- **Цены**: периоды и цены для `period`, пакеты GB и цены для `traffic`;
+- **Цены**: периоды, цены и реферальные бонусы для `period`, пакеты GB и цены для `traffic`;
 - **Докупки**: обычные пакеты докупки трафика для `period`; для `traffic` отдельные докупки не нужны, пользователь повторно покупает пакеты из `traffic_packages`;
 - **Premium**: названия premium-раздела RU/EN, premium Internal Squads, месячный premium-лимит и RUB/Stars пакеты premium-докупки;
 - **Устройства**: RUB/Stars пакеты докупки HWID-устройств.
@@ -22,7 +22,7 @@ JSON-каталог может содержать несколько тариф
 - добавление, редактирование и удаление тарифов;
 - включение и выключение тарифа на витрине;
 - выбор тарифа по умолчанию;
- настройка тарифов на срок (`period`): месячный лимит, периоды, RUB/Stars цены, пакеты докупки трафика;
+- настройка тарифов на срок (`period`): месячный лимит, периоды, RUB/Stars цены, реферальные бонусы и пакеты докупки трафика;
 - настройка тарифов по трафику (`traffic`): пакеты GB, RUB/Stars цены, курс конвертации;
 - настройка базовых Internal Squads из списка Remnawave;
 - настройка premium-раздела: названия RU/EN, premium Internal Squads, месячный premium-лимит и RUB/Stars пакеты докупки premium-трафика;
@@ -60,7 +60,9 @@ JSON-каталог может содержать несколько тариф
      "squad_uuids": ["uuid-1"],
      "billing_model": "period",
      "monthly_gb": 500,
-      "prices_rub": { "1": 150, "3": 400 },
+      "prices_rub": { "1": 200, "3": 600 },
+      "referral_bonus_days_inviter": { "1": 3, "3": 7 },
+      "referral_bonus_days_referee": { "1": 1, "3": 3 },
      "enabled_periods": [1, 3],
      "topup_packages": {
        "rub": [{ "gb": 10, "price": 99 }],
@@ -108,6 +110,8 @@ JSON-каталог может содержать несколько тариф
 | `monthly_gb` | Базовый месячный лимит трафика тарифа. `0` означает безлимит. |
 | `prices_rub` | Цены периодов в рублях, ключ - количество месяцев. |
 | `prices_stars` | Цены периодов в Telegram Stars. |
+| `referral_bonus_days_inviter` | Бонус пригласившему в днях для каждого периода. Ключ - количество месяцев, как в `enabled_periods`. |
+| `referral_bonus_days_referee` | Бонус приглашенному в днях для каждого периода. Ключ - количество месяцев, как в `enabled_periods`. |
 | `enabled_periods` | Периоды, доступные для покупки. |
 | `topup_packages` | Пакеты докупки трафика именно для этого тарифа. Если поле не задано или списки пустые, докупка для тарифа не показывается в Web App и Telegram-боте. |

@@ -314,7 +318,15 @@ Remnawave ограничивает доступ при достижении `tra

 Пробный период использует настройки `TRIAL_DURATION_DAYS`, `TRIAL_TRAFFIC_LIMIT_GB`, `TRIAL_TRAFFIC_STRATEGY` и `TRIAL_SQUAD_UUIDS`. Он не выбирает тариф из JSON-каталога, но его можно настроить на странице **Система → Тарифы** рядом с каталогом продаж. Если `TRIAL_SQUAD_UUIDS` пустой, для trial применяются squads из `USER_SQUAD_UUIDS`.

-Промокоды с бонусными днями применяются к покупке period-подписки. Реферальные бонусы по периодам также относятся к подпискам на срок; в режиме продажи трафика без JSON-каталога Web App не показывает детализацию бонусов по месяцам.
+Промокоды с бонусными днями применяются к покупке period-подписки.
+
+Реферальные бонусы за оплату в JSON-каталоге задаются прямо в period-тарифе рядом с ценами периода: `referral_bonus_days_inviter` для пригласившего и `referral_bonus_days_referee` для приглашенного. Ключи этих словарей - месяцы периода (`"1"`, `"3"`, `"6"`, `"12"` или любые другие периоды тарифа, например `"2"`, `"4"`, `"8"`, `"16"`). Для `traffic`-тарифов такие бонусы не применяются.
+
+Если приглашенный покупает один тариф, а пригласивший находится на другом, размер бонуса берется из тарифа и периода, который купил приглашенный. При этом подписка пригласившего только продлевается на бонусные дни: лимиты, Internal Squads и другие параметры его текущего тарифа не пересчитываются под тариф приглашенного.
+
+В Web App и Telegram-меню подробные строки по периодам показываются только для legacy-режима или когда активен один period-тариф. Если включено несколько period-тарифов, Web App показывает сообщение, что бонус зависит от тарифа и периода оплаты друга, затем список тарифов с диапазонами "от N до N дней" и раскрытием подробностей по иконке вопроса. Telegram-меню в этом случае показывает только диапазоны по каждому тарифу.
+
+В legacy-режиме без JSON-каталога используются переменные `REFERRAL_BONUS_DAYS_*` и `REFEREE_BONUS_DAYS_*`; при продаже трафика без JSON-каталога Web App не показывает детализацию бонусов по месяцам.

 ## Привязка существующих подписок

@@ -118,6 +118,8 @@ services:
 - Telegram deep-link: `https://t.me/<bot>?start=ref_u<code>`;
 - Web App ссылка: `https://app.domain.com/?ref=u<code>`.

+В разделе бонусов Web App показывает приветственный бонус за регистрацию и бонусы за оплату подписки. В legacy-режиме или при одном period-тарифе выводятся подробные строки по периодам. Если в JSON-каталоге включено несколько period-тарифов, Web App показывает, что бонус зависит от тарифа и периода оплаты друга, затем список тарифов с диапазоном "от N до N дней"; подробности по периодам раскрываются по иконке вопроса.
+
 Веб-приложение учитывает `ref`, `start`, `start_param` и Telegram Mini Apps `start_param`, сохраняет найденный параметр до авторизации и передает его в Telegram OAuth или вход по email.

 Для email-регистраций пользователь в Remnawave создается с username вида `em_<referral_code>`. Email добавляется в описание пользователя панели и, если API панели принимает поле `email`, передается отдельным полем. Для Telegram-регистраций используется username `tg_<telegram_id>`.