From 32616c80abec99ffbe6f53f389f167ea9b19fe42 Mon Sep 17 00:00:00 2001 From: 3252a8 <3252a8@proton.me> Date: Fri, 29 May 2026 17:50:30 +0300 Subject: [PATCH] docs: add notifications table --- docs-site/astro.config.mjs | 1 + docs-site/scripts/sync-docs.mjs | 1 + docs/features/notifications.md | 55 +++++++++++++++++++++++++++++++++ 3 files changed, 57 insertions(+) create mode 100644 docs/features/notifications.md diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs index 98a2bc8..aa6c3e1 100644 --- a/docs-site/astro.config.mjs +++ b/docs-site/astro.config.mjs @@ -79,6 +79,7 @@ export default defineConfig({ { label: 'Основные', slug: 'features/core' }, { label: 'Платежи', slug: 'features/payments' }, { label: 'Подписки', slug: 'features/subscriptions' }, + { label: 'Уведомления', slug: 'features/notifications' }, { label: 'Тарифы', slug: 'features/tariffs' }, { label: 'Веб-приложение / Mini App', slug: 'features/web-app' }, { label: 'Telegram-авторизация', slug: 'features/telegram-auth' }, diff --git a/docs-site/scripts/sync-docs.mjs b/docs-site/scripts/sync-docs.mjs index 79aa695..acb15ca 100644 --- a/docs-site/scripts/sync-docs.mjs +++ b/docs-site/scripts/sync-docs.mjs @@ -19,6 +19,7 @@ const descriptions = { 'features/core.md': 'Пользовательские и админские сценарии Remnawave Minishop.', 'features/payments.md': 'Платежные провайдеры, кнопки оплаты и webhook-обработка.', 'features/subscriptions.md': 'Тарифы на срок и по трафику, premium-сквады, HWID-устройства и жизненный цикл подписки.', + 'features/notifications.md': 'Каналы Telegram и email для пользовательских, админских и сервисных уведомлений Remnawave Minishop.', 'features/tariffs.md': 'Каталог тарифов, модели на срок/по трафику, premium-сквады и HWID-устройства.', 'features/web-app.md': 'Telegram Mini App, публичные инструкции, проксирование и реферальные ссылки.', 'features/telegram-auth.md': 'Telegram Mini Apps initData, Telegram OAuth, BotFather и настройка входа через Telegram.', diff --git a/docs/features/notifications.md b/docs/features/notifications.md new file mode 100644 index 0000000..67c332e --- /dev/null +++ b/docs/features/notifications.md @@ -0,0 +1,55 @@ +# Уведомления + +Minishop отправляет уведомления в Telegram и на email. Telegram-канал означает личные сообщения пользователю, сообщения администраторам из `ADMIN_IDS` или сообщения в `LOG_CHAT_ID` - зависит от события. Email работает только при настроенном SMTP и наличии email у получателя. + +## Сводная таблица + +| Событие | Получатель | Telegram | Email | Условия и ограничения | +| --- | --- | :---: | :---: | --- | +| Код входа по email и magic link | Пользователь | - | ✓ | Нужны `SMTP_*` и `EMAIL_*` настройки. Magic link также требует корректный `SUBSCRIPTION_MINI_APP_URL`. | +| Код установки или смены пароля | Пользователь | - | ✓ | Нужны `SMTP_*` и `EMAIL_*` настройки. | +| Успешная оплата подписки | Пользователь | ✓ | ✓ | Email отправляется, если SMTP настроен и у пользователя есть email. | +| Успешная покупка пакета трафика | Пользователь | ✓ | ✓ | Email отправляется, если SMTP настроен и у пользователя есть 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`. | +| Исчерпан трафик пробного периода | Пользователь | ✓ | - | Отправляется локальным worker для trial-подписок. | +| Ответ администратора в тикете поддержки | Пользователь | ✓ | ✓ | Telegram отправляется пользователям с Telegram-аккаунтом, email - пользователям с привязанным email. | +| Закрытие тикета поддержки | Пользователь | ✓ | ✓ | Telegram отправляется пользователям с Telegram-аккаунтом, email - пользователям с привязанным email. | +| Слияние email- и Telegram-аккаунтов | Пользователь | - | ✓ | Email отправляется на итоговый email аккаунта после безопасного merge. | +| Новый тикет поддержки | Администраторы | ✓ | ✓ | Telegram/log уведомления зависят от `LOG_SUPPORT`; email включается через `SUPPORT_ADMIN_EMAIL_NOTIFICATIONS_ENABLED`. | +| Ответ пользователя в тикете поддержки | Администраторы | ✓ | ✓ | Telegram/log уведомления зависят от `LOG_SUPPORT`; email включается через `SUPPORT_ADMIN_EMAIL_NOTIFICATIONS_ENABLED`. | +| Новая регистрация через Telegram | Администраторы / лог-чат | ✓ | - | Управляется `LOG_NEW_USERS`. | +| Новая регистрация по email | Администраторы / лог-чат | ✓ | - | Управляется `LOG_NEW_USERS`. | +| Email привязан к Telegram-аккаунту | Администраторы / лог-чат | ✓ | - | Управляется `LOG_NEW_USERS`. | +| Telegram привязан к email-аккаунту | Администраторы / лог-чат | ✓ | - | Управляется `LOG_NEW_USERS`. | +| Email- и Telegram-аккаунты объединены | Администраторы / лог-чат | ✓ | - | Управляется `LOG_NEW_USERS`. | +| Успешная оплата | Администраторы / лог-чат | ✓ | - | Управляется `LOG_PAYMENTS`. | +| Активация trial | Администраторы / лог-чат | ✓ | - | Управляется `LOG_TRIAL_ACTIVATIONS`. | +| Активация промокода | Администраторы / лог-чат | ✓ | - | Управляется `LOG_PROMO_ACTIVATIONS`. | +| Подозрительная попытка промокода | Администраторы / лог-чат | ✓ | - | Управляется `LOG_SUSPICIOUS_ACTIVITY`. | +| Результат ручной синхронизации с Remnawave Panel | Администратор, запустивший синхронизацию | ✓ | - | Worker отправляет короткий результат в `target_chat_id`, если синхронизация запускалась через очередь. | +| Ошибка создания пользователя в Remnawave Panel | Администраторы | ✓ | - | Отправляется администраторам из `ADMIN_IDS`. | +| Архив бэкапа создан | Администраторы / backup-чат | ✓ | - | Архив отправляется в `BACKUP_CHAT_ID`, а если он пустой - в `LOG_CHAT_ID`. | +| Ошибка бэкапа | Администраторы / backup-чат | ✓ | - | Ошибка отправляется в `BACKUP_CHAT_ID`, а если он пустой - в `LOG_CHAT_ID`. | + +## Важно про окончание подписки + +Если пользователь привязал email к Telegram-аккаунту, уведомления об окончании подписки не дублируются в почту полностью. Сейчас email получает только напоминание за 3 дня до окончания, и только когда оно пришло из Remnawave Panel webhook `user.expires_in_72_hours`. Остальные стадии - 48 часов, 24 часа, почасовое предупреждение, день окончания и уведомление через сутки после окончания - отправляются только в Telegram. + +Если Remnawave webhook не настроен или используется только локальный `SubscriptionNotificationWorker`, даже напоминание за 3 дня уйдет только в Telegram. + +## Рекомендации по синхронизации каналов + +- Для пользовательских уведомлений о подписке лучше выбрать единую политику: либо 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.