09 Notifications

09 · Уведомления

← Home

Рассылки об оплатах, гостевые ссылки, объявления и аварийные алерты — через очередь с ретраями и любые каналы: e-mail (собственный SMTP-клиент), Telegram, SMS, WhatsApp, webhook, журнал.

Конвейер

Событие (начисление, пропуск, напоминание, рассылка из UI)
   │  Message::forResident(…) + шаблон + контекст
   ▼
NotificationService::resolve()      — каналы → контакты жителя
   ▼                                 (primary-first, флаг «слать сюда»,
таблица `outbox`                     fallback на email/phone карточки)
   ▼
QueueWorker (cron каждую минуту или queue:work демоном)
   — claim с lease (два воркера не задвоят), ретраи 60с→3ч,
     статусы pending/sent/failed, счётчики батча
   ▼
Каналы: log · mail · telegram · sms · whatsapp · webhook

Ничего не теряется: даже без настроенных каналов всё пишется в log.

Каналы

Канал	Включение	Реквизиты
log	всегда	уровень; полезно для отладки
mail	notify.channels.mail.enabled	SMTP: host/port/encryption(tls|ssl|none)/username/password/from/reply_to; собственный SMTP-клиент — внешних библиотек не нужно
telegram	.channels.telegram.enabled	bot_token (@BotFather), parse_mode HTML; личные сообщения — если житель указал @username (контакт типа telegram); служебные — в admin_chat_id
sms	.channels.sms.enabled	HTTP-шлюз: endpoint/login/password/sender/template
whatsapp	.channels.whatsapp.enabled	Cloud API: endpoint/token/phone_id
webhook	.channels.webhook.enabled	POST JSON {to, subject, body, meta} на url + HMAC-подпись secret

Секреты храните шифрованными: secret:set TELEGRAM_BOT_TOKEN → 'bot_token' => '${secret:TELEGRAM_BOT_TOKEN}'.

Куда попадёт сообщение: каналы из notify.default (или из настроек UI / конкретной рассылки), затем контакты жителя нужного типа, упорядоченные is_primary desc; one_per_channel: true — берётся первый подходящий контакт (не спамим на все номера). Контакты с notify=0 пропускаются. Если контактов нет — fallback на residents.email/phone.

Шаблоны

Шаблоны живут в config.notify.templates.*, переопределяются из UI (Админка → Уведомления → Шаблоны; хранение в БД, кнопка «сбросить к дефолту»).

Стандартный набор: payment_new, payment_reminder, payment_overdue, payment_received, charge_recalculated, guest_created, guest_invite, guest_used, gate_opened, system_alert, welcome.

Плейсхолдеры: {name} (короткое имя), {full_name}, {apartment}, {amount} (уже отформатирован с символом валюты), {currency} (ISO-код), {period}, {due_date}, {deadline}, {pay_link}, {balance}, {debt}, {invoice_no}, {charge_no}, {organisation}, {support_phone}, {support_email}, {today}, для гостей — {code}, {link}, {pin}, {expires_at}, {ttl_hours}, {guest_name}, {used_at}, {used_count}.

Модификаторы: {due_date|date:d.m.Y}, {due_date|datetime}, {name|upper}, {name|lower}, {text|limit:80}, {amount_raw|money}, {count|plural:житель,жителя,жителей}, {value|default:—}, {phone|mask}.

Неизвестный плейсхолдер остаётся видимым {like_this} — опечатка заметна сразу. Строки, где после подстановки осталось только «Подпись:» (пустая ссылка на оплату), автоматически удаляются.

Массовые рассылки

• По начислению: при выставлении счетов (--notify / галка в мастере) или повторно — карточка начисления → «Рассылка» (выборочно по жителям).
• Напоминания должникам: /admin/billing/debtors → «Напомнить», billing:remind, cron по расписанию billing.reminder.
• Произвольная: Админка → Уведомления → «Рассылка» — текст/шаблон, аудитория (все активные / корпус / должники / с e-mail), каналы, тестовая отправка себе, очередь.
• Объявления: баннеры в UI жителей (не письма) — текст, срок, важность.

Батч рассылки виден в очереди: сколько встало, отправлено, упало, пропущено (отключённые жители и рассылки никогда не учитывают неактивных).

Очередь

• queue:run — разобрать раз (вызывается из schedule:run, т.е. из cron);
• queue:work --sleep=5 — демон (systemd-юнит в 01 · Установка);
• queue:stats — состояние;
• ретраи: max_attempts: 5, задержки [60, 300, 900, 3600, 10800] сек;
• throttle_ms: 150 — вежливая пауза между отправками (не злим SMTP/Telegram);
• UI: Админка → Уведомления → Очередь — failed можно ретраить вручную.
• driver: sync — отправка сразу (для тестов/микро-установок).

Telegram-бот (интеграция)

integrations.telegram_bot: команды /open (для staff), /status, /guest (выпустить пропуск), /balance, /help; webhook POST /webhook/telegram с секретом (без CSRF/сессии). Алерты системы — в admin_chat_id.

Отладка

php bin/bas-ip notify:test --to=admin --message="Проверка"   # тестовая отправка
php bin/bas-ip notify:send --resident=5 --template=payment_reminder
php bin/bas-ip logs:tail notify --lines=50                   # журнал канала
php bin/bas-ip queue:stats

Журнал notify содержит: получателя (маскируется по политике логов), канал, шаблон, результат, ошибку провайдера.

---

Дальше: 10 · REST API