feat: mirror subscription lifecycle notifications

2026-05-29 18:08:28 +03:00
parent 6fbb8eebec
commit 19f0f27a3b
13 changed files with 864 additions and 182 deletions
@@ -385,6 +385,7 @@ PAYMENT_HELEKET_TELEGRAM_EMOJI
 | `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_EMAIL_NOTIFICATIONS_ENABLED` | Дублирует пользовательские уведомления жизненного цикла подписки на email, если SMTP настроен и у пользователя есть email. |
 | `SUBSCRIPTION_NOTIFY_ON_EXPIRE` | Уведомлять в день окончания. |
 | `SUBSCRIPTION_NOTIFY_AFTER_EXPIRE` | Уведомлять после окончания. |
 | `SUBSCRIPTION_NOTIFY_DAYS_BEFORE` | За сколько дней предупреждать. |
@@ -105,4 +105,4 @@ docker compose logs -f backend
 - Код сразу устаревает: проверьте `EMAIL_CODE_TTL_SECONDS` и время на сервере.
 - Пользователь получает `rate_limited`: подождите `EMAIL_CODE_RESEND_SECONDS` или проверьте brute-force настройки.

-Email-уведомления поддержки и платежей используют тот же SMTP-контур. Сценарий поддержки описан в [разделе тикетов](support.md).
+Email-уведомления поддержки, платежей и жизненного цикла подписки используют тот же SMTP-контур. Сценарий поддержки описан в [разделе тикетов](support.md), сводка по каналам - в разделе [уведомления](notifications.md).
@@ -2,6 +2,8 @@

 Minishop отправляет уведомления в Telegram и на email. Telegram-канал означает личные сообщения пользователю, сообщения администраторам из `ADMIN_IDS` или сообщения в `LOG_CHAT_ID` - зависит от события. Email работает только при настроенном SMTP и наличии email у получателя.

+Для уведомлений жизненного цикла подписки есть отдельный флаг `SUBSCRIPTION_EMAIL_NOTIFICATIONS_ENABLED`. Если он включен, пользовательские уведомления об окончании подписки отправляются в Telegram при наличии привязанного Telegram-аккаунта и на email при наличии привязанной почты.
+
 ## Сводная таблица

 | Событие | Получатель | Telegram | Email | Условия и ограничения |
@@ -13,13 +15,13 @@ Minishop отправляет уведомления в Telegram и на email.
 | Успешная покупка premium-трафика | Пользователь | ✓ | ✓ | Email отправляется, если SMTP настроен и у пользователя есть email. |
 | Успешная покупка HWID-устройств | Пользователь | ✓ | - | Отправляется после оплаты `hwid_devices` или `hwid_devices_renewal`. |
 | Ошибка оплаты по webhook провайдера | Пользователь | ✓ | - | Отправляется, когда платежный провайдер сообщает о неуспешном платеже. |
-| Напоминание за 3 дня до окончания подписки | Пользователь | ✓ | ✓ | Telegram отправляет Remnawave webhook или локальный worker. Email отправляет только webhook `user.expires_in_72_hours`. |
-| Напоминание за 2 дня до окончания подписки | Пользователь | ✓ | - | Работает, если `SUBSCRIPTION_NOTIFY_DAYS_BEFORE >= 2`. |
-| Предупреждение о списании автопродления за 48 часов | Пользователь | ✓ | - | Отправляется вместо обычного 48-часового напоминания для YooKassa-подписок с включенным автопродлением. |
-| Напоминание за 1 день до окончания подписки | Пользователь | ✓ | - | Работает, если `SUBSCRIPTION_NOTIFY_DAYS_BEFORE >= 1`. Для YooKassa auto-renew 24-часовой webhook сначала пытается списать продление и может не отправить напоминание. |
-| Напоминание за несколько часов до окончания подписки | Пользователь | ✓ | - | Отправляется локальным worker, если `SUBSCRIPTION_NOTIFY_HOURS_BEFORE` задан от 1 до 23. |
-| Уведомление в день окончания подписки | Пользователь | ✓ | - | Управляется `SUBSCRIPTION_NOTIFY_ON_EXPIRE`. |
-| Уведомление через сутки после окончания подписки | Пользователь | ✓ | - | Управляется `SUBSCRIPTION_NOTIFY_AFTER_EXPIRE`. |
+| Напоминание за 3 дня до окончания подписки | Пользователь | ✓ | ✓ | Управляется `SUBSCRIPTION_NOTIFY_DAYS_BEFORE` и `SUBSCRIPTION_EMAIL_NOTIFICATIONS_ENABLED`. |
+| Напоминание за 2 дня до окончания подписки | Пользователь | ✓ | ✓ | Работает, если `SUBSCRIPTION_NOTIFY_DAYS_BEFORE >= 2`; email требует `SUBSCRIPTION_EMAIL_NOTIFICATIONS_ENABLED=True`. |
+| Предупреждение о списании автопродления за 48 часов | Пользователь | ✓ | ✓ | Отправляется вместо обычного 48-часового напоминания для YooKassa-подписок с включенным автопродлением. |
+| Напоминание за 1 день до окончания подписки | Пользователь | ✓ | ✓ | Работает, если `SUBSCRIPTION_NOTIFY_DAYS_BEFORE >= 1`. Для YooKassa auto-renew 24-часовой webhook сначала пытается списать продление и может не отправить напоминание. |
+| Напоминание за несколько часов до окончания подписки | Пользователь | ✓ | ✓ | Отправляется локальным worker, если `SUBSCRIPTION_NOTIFY_HOURS_BEFORE` задан от 1 до 23. |
+| Уведомление в день окончания подписки | Пользователь | ✓ | ✓ | Управляется `SUBSCRIPTION_NOTIFY_ON_EXPIRE`; email требует `SUBSCRIPTION_EMAIL_NOTIFICATIONS_ENABLED=True`. |
+| Уведомление через сутки после окончания подписки | Пользователь | ✓ | ✓ | Управляется `SUBSCRIPTION_NOTIFY_AFTER_EXPIRE`; email требует `SUBSCRIPTION_EMAIL_NOTIFICATIONS_ENABLED=True`. |
 | Исчерпан трафик пробного периода | Пользователь | ✓ | - | Отправляется локальным worker для trial-подписок. |
 | Ответ администратора в тикете поддержки | Пользователь | ✓ | ✓ | Telegram отправляется пользователям с Telegram-аккаунтом, email - пользователям с привязанным email. |
 | Закрытие тикета поддержки | Пользователь | ✓ | ✓ | Telegram отправляется пользователям с Telegram-аккаунтом, email - пользователям с привязанным email. |
@@ -42,14 +44,18 @@ Minishop отправляет уведомления в Telegram и на email.

 ## Важно про окончание подписки

-Если пользователь привязал email к Telegram-аккаунту, уведомления об окончании подписки не дублируются в почту полностью. Сейчас email получает только напоминание за 3 дня до окончания, и только когда оно пришло из Remnawave Panel webhook `user.expires_in_72_hours`. Остальные стадии - 48 часов, 24 часа, почасовое предупреждение, день окончания и уведомление через сутки после окончания - отправляются только в Telegram.
+Если пользователь привязал email к Telegram-аккаунту, уведомления об окончании подписки дублируются в оба канала: Telegram и email. Если привязан только Telegram - уйдет только Telegram. Если есть только email - уйдет только email.

-Если Remnawave webhook не настроен или используется только локальный `SubscriptionNotificationWorker`, даже напоминание за 3 дня уйдет только в Telegram.
+Email-доставка требует одновременно:

-## Рекомендации по синхронизации каналов
+- `SUBSCRIPTION_EMAIL_NOTIFICATIONS_ENABLED=True`;
+- настроенный SMTP-контур;
+- email у пользователя.

- Для пользовательских уведомлений о подписке лучше выбрать единую политику: либо email дублирует все важные стадии, либо email используется только для мягкого раннего напоминания за 3 дня. Текущее поведение ближе ко второму варианту.
- Если нужно полное дублирование, стоит вынести отправку lifecycle-уведомлений подписки в общий сервис и вызывать его и из Remnawave webhook, и из локального worker. Тогда одна и та же стадия будет одинаково обрабатываться для Telegram и email.
- Дедупликацию лучше вести отдельно по каналу, например `before_3d:telegram` и `before_3d:email`, чтобы сбой Telegram не блокировал email и наоборот.
- Для email-канала стоит добавить отдельный флаг вроде `SUBSCRIPTION_EMAIL_NOTIFICATIONS_ENABLED` и, при необходимости, настройки по стадиям: за 3 дня, за 1 день, в день окончания, после окончания.
- Если одновременно включены Remnawave webhook и локальный worker, стоит синхронизировать их через одну таблицу отправленных уведомлений. Сейчас worker пишет историю `subscription_notifications`, а webhook-уведомления обрабатываются отдельно, поэтому при близких расписаниях возможны повторы в Telegram.
+## Синхронизация каналов
+
+Remnawave webhook и локальный `SubscriptionNotificationWorker` используют общий сервис отправки и общую таблицу дедупликации `subscription_notifications`.
+
+Дедупликация ведется отдельно по каналам: например, `before_3d:telegram` и `before_3d:email`. Благодаря этому сбой одного канала не блокирует второй, а повторное событие из webhook или worker не отправляет уже доставленное уведомление повторно.
+
+Старые записи без канала, например `before_3d`, считаются Telegram-историей. Они блокируют повторное Telegram-сообщение, но не мешают отправить email после обновления.