Перейти до основного вмісту

Архітектура сповіщень і нагадувань

Кожне повідомлення, яке член церкви бачить поза сторінкою, на якій він зараз перебуває, наприклад лічильник на значку, push-сповіщення чи щоденний дайджест електронною поштою, проходить через одну з двох точок входу в MessagingApi. Ця сторінка описує воронку, механізм нагадувань, який подає до неї повідомлення за розкладом, і модель налаштувань, що визначає, які повідомлення справді доходять до людини.

Огляд: два входи​

будь-що за розкладом ──▶ ReminderEngine (визначення → події → сканування) ─┐
чат / запити / робочий процес / масові відправлення ───────────────────────┼─▶ createNotifications()
│ гейт in_app → сокет → push → email
(канали нагадувань включають sms) ──▶ ReminderEngine.sendSms() ──▶ гейт sms → sendPersonText() через провайдера церкви
відповідь STOP від провайдера ──▶ POST /messaging/texting/inbound/:churchId/:token ──▶ SmsOptOutHelper.optOut()
листи щодо облікового запису та юридичні листи ──▶ TransactionalEmailHelper.sendTransactional() [за білим списком, перевіряється лінтером]
  1. Усе, що повідомляє людині щось, проходить через NotificationHelper.createNotifications() у модулі messaging. Він зберігає рядок у таблиці notifications і переходить від сокета до push і email, перевіряючи PreferenceGateHelper для кожного каналу, зокрема in_app на рівні 0.
  2. Усе заплановане є reminderDefinition (на рівні сутності або області), яке розгортається в reminderOccurrences і надсилається через ReminderEngine.scan() за періодичним таймером. Є один розгортач, один диспетчер і один журнал надсилань (reminderSentLog).
  3. Прямі листи надсилаються лише через TransactionalEmailHelper.sendTransactional(). Правило ESLint забезпечує це під час компіляції. Див. нижче.
Вхід для електронної пошти перевіряється лінтером, а не лише домовленістю

Api/tools/eslint-rules/email-door.cjs визначає правило no-direct-email-helper: будь-який виклик EmailHelper.sendTemplatedEmail() або EmailHelper.sendEmail() поза файлами NotificationHelper.ts або TransactionalEmailHelper.ts не проходить перевірку лінтера. Якщо потрібно надіслати лист, направте його через воронку (createNotifications з emailImmediate) або через TransactionalEmailHelper.sendTransactional(). Іншого способу, який проходить CI, немає.

Воронка сповіщень​

NotificationHelper.createNotifications() є єдиною точкою входу для всього, що не заплановане і не є транзакційним:

createNotifications(
peopleIds: string[],
churchId: string,
contentType: string,
contentId: string,
message: string,
link?: string,
triggeredByPersonId?: string,
options?: {
deliveryStartLevel?: number; // 0 сокет (за замовчуванням), 1 push, 2 лише email
category?: string; // вісь налаштувань; визначається з contentType, якщо не вказано
emailByPerson?: Record<string, { subject: string; html: string }>;
emailImmediate?: boolean; // надіслати лист зараз, а не чекати на дайджест
}
)

Для кожного отримувача воно зберігає рядок у notifications і викликає attemptDeliveryWithEscalation, який проходить драбину каналів, описану нижче. Непрочитаний рядок для тих самих (contentType, contentId) блокує повторне створення. Цей захист від дублювання пропускається для надсилань з emailImmediate (зміщення нагадувань, масові листи від персоналу, кроки робочого процесу мають власну перевірку на дублювання) і для особистих повідомлень, які завжди надсилають сигнал у сокет.

shared/helpers/NotificationService.ts повторює той самий підпис (NotificationServiceOptions) для викликів поза модулем messaging і реєструється в модулі messaging під час запуску.

Ланцюжок ескалації каналів​

Доставка починається з певного рівня (за замовчуванням 0, або вищого для нагадувань і явних надсилань) і переходить до наступного каналу, лише якщо попередній не спрацював. Кожен рівень перевіряється PreferenceGateHelper до будь-якої спроби.

РівеньКаналПоведінка
0in_app / сокетСпершу перевіряється гейт in_app. Якщо доставку придушено (вимкнено), рядок зберігається з isNew=false, і доставка повністю зупиняється: без сигналу в сокет, без значка, без подальшої ескалації. Інакше сервер шукає відкриті з'єднання сокета для кімнати alerts цієї людини і надсилає кадр notification (або privateMessage). Для звичайних сповіщень успішна доставка через сокет зупиняє ланцюжок на цьому рівні: таймер 30 хвилин повторно перевіряє непрочитані елементи і пізніше ескалює їх. Особисті повідомлення ніколи не зупиняються на сокеті: встановлений PWA може тримати сокет сповіщень відкритим у фоновому режимі, і це інакше пригнічувало б push на рівні ОС.
1pushЗалежить від allowPush, відмови від категорії та тихих годин. Надсилає і Expo push-токенам, і підпискам Web Push, знайденим у рядках devices людини. Дублікати видаляються за кінцевою точкою, а застарілі токени очищаються.
2emailЗалежить від emailFrequency і відмови від категорії. Негайні надсилання (emailImmediate) відображаються одразу і записують рядок у deliveryLogs. В інших випадках сповіщення лишається в очікуванні пакетного дайджесту, описаного нижче.
—smsНе є рівнем у драбині ескалації. Єдиним джерелом SMS з гейтом є механізм нагадувань: коли канали визначення містять sms, ReminderEngine.sendSms() надсилає текст кожному отримувачу додатково до push- чи email-сповіщення (див. Текстові нагадування). Масова розсилка SMS (TextingController / @churchapps/texting), дія Text Volunteers в огляді служіння (MatrixTextHelper → MessagingModuleGateway.sendPersonText) і дія кроку робочого процесу Send Text (StepActionHelper.sendText → sendPersonText) надсилають текст безпосередньо через провайдера церкви, тому налаштування сповіщень і тихі години на них не діють. Враховується лише прапорець optedOut людини.

Непрочитані сповіщення, що лишилися на рівні сокета або push, ескалює таймер 30 хвилин (NotificationHelper.escalateDelivery). Пакетні листи надсилає NotificationHelper.sendEmailNotifications(frequency), яким керує налаштування emailFrequency кожної людини: individual працює за таймером 30 хвилин, daily працює за нічним таймером. (weekly є допустимим значенням налаштування, але окремого пакетного запуску для нього ще немає.)

Механізм нагадувань​

Заплановані нагадування (про події, строки виконання завдань, призначення на служіння чи плани) проходять через один узагальнений механізм, а не через окрему логіку cron для кожної функції.

reminderDefinitions ──розгортання──▶ reminderOccurrences ──сканування (30 хв)──▶ createNotifications()
│ │ │
▼ ▼ ▼
визначення на рівні сутності один рядок для кожної deliveryStartLevel: 1
або області: зміщення/канали/ комбінації (визначення, + журнал reminderSentLog
повідомлення сутність, подія, зміщення)

Визначення (reminderDefinitions) є або на рівні сутності (встановлено entityId, тобто конкретна подія, завдання чи план), або на рівні області (entityId порожній, встановлено scopeId, наприклад кожен план у межах типу планів служіння). Визначення містить CSV зі зміщеннями в хвилинах (offsets, наприклад "1440,60" для одного дня і однієї години до події), місцевий час надсилання (sendLocalTime), CSV каналів (channels, де email означає негайний розширений лист у момент надсилання), recipientMode і необов'язкове власне повідомлення (message).

Розгортання створює рядки спрацювань на найближчий горизонт (ковзне вікно на кілька днів). Воно працює за нічним таймером і синхронно щоразу, коли визначення зберігається, щоб нагадування про подію, створену в останню мить, усе одно спрацювало. Визначення області розгортаються через loadScopeEntities адаптера, створюючи один набір подій для кожної конкретної сутності. Події на рівні сутності використовують ключ definitionId:occurrenceISO:offset, а події в області мають простір імен за ідентифікатором сутності, тож вони ніколи не збігаються. Оновлення події відновлює раніше скасований рядок. Стандартний спосіб повторно синхронізувати нагадування після зміни базової сутності: скасувати, а потім розгорнути знову. Рядки зі статусом sent, failed або processing не змінюються.

Диспетчеризація (ReminderEngine.scan()) працює за таймером 30 хвилин. Вона бере на себе події, що настали (оренда запобігає подвійній обробці), завантажує отримувачів через адаптер сутності, відфільтровує тих, кого вже записано в reminderSentLog для цієї події, і викликає createNotifications з deliveryStartLevel: 1 (одразу до push), а також emailImmediate/emailByPerson, якщо канали визначення містять email.

Текстові нагадування​

Якщо канали визначення містять sms, scan() викликає ReminderEngine.sendSms() після створення push- і email-сповіщень для тих самих нових отримувачів. Надсилання текстів є добровільним для кожного учасника:

  • Кожен отримувач проходить через PreferenceGateHelper.evaluate(..., "sms", ...), тому allowSms має бути увімкнено (за замовчуванням вимкнено, встановлюється перемикачем Text messages у B1App), а канал sms категорії не має бути вимкнений на рівні категорії. event_reminders, serving_schedule і tasks містять sms і в defaultChannels, і в allowedChannels.
  • Людям без mobilePhone або з встановленим optedOut текст не надсилається. Якщо в церкви немає провайдера SMS, решта пакета пригнічується з причиною no_provider.
  • Текст формує ReminderEngine.smsBody() у форматі "<Church name>: <message> Reply STOP to opt out.", обрізаний до одного сегмента з 160 символів.
  • Кожен отримувач має власний рядок у reminderSentLog з channel: "sms" і статусом sent / suppressed / failed. Він зберігається окремо від рядка push/email, тож помилка SMS ніколи не призводить до повторного надсилання push чи email.

Редактори пропонують Text лише тоді, коли GET /messaging/texting/status повертає { enabled: true } (перший провайдер SMS церкви увімкнено).

Відписка STOP. POST /messaging/texting/inbound/:churchId/:token є анонімним webhook, який церква вставляє в налаштування свого провайдера (B1Admin показує URL з GET /messaging/texting/inboundUrl у налаштуваннях текстових повідомлень). Токен є HMAC від ідентифікатора церкви (SmsOptOutHelper.token). SmsOptOutHelper.parse приймає поля форми у форматі Twilio та JSON у форматі Clearstream/TextInChurch. Якщо відповідь точно збігається зі стоп-словом оператора (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, REVOKE), кожній людині церкви, яка не видалена і чий мобільний номер збігається, встановлюється people.optedOut = true і allowSms = false. Інші відповіді підтверджуються і ігноруються.

Внутрішня шина подій реагує на зміни сутностей, не чекаючи нічного розгортання: події вмісту (через диспетчер webhook) і події оновлення плану/завдання запускають негайне повторне розгортання або скасування для відповідної сутності. Оновлення плану також повторно розгортає визначення області, пов'язані з типом цього плану.

Адаптери​

Механізм не залежить від типу сутності. Кожен підтримуваний тип сутності підключається через адаптер (helpers/adapters/):

Тип сутностіАдаптерПримітки
eventEventReminderAdapterОтримувачі обмежуються зареєстрованими учасниками або членами групи залежно від події та recipientMode.
planPlanReminderAdapterОтримувачі — призначення зі статусом Accepted та Unconfirmed в опублікованих (не чернеткових) планах. Непідтверджені призначення, видані через робочий процес підтвердження служіння, виключаються, доки їх не прийнято (див. нижче). buildEmails викликає DoingModuleGateway.buildPlanReminderEmails, який формує позиції, нотатки та власне повідомлення через doing/helpers/PlanReminderEmailHelper, включно з кнопками Accept/Decline, підписаними ReminderTokenHelper, які надсилають дані на публічну кінцеву точку відповіді на призначення.
taskTaskReminderAdapterОтримувачі — виконавці завдання.

Кінцеві точки​

МетодШляхПризначення
GET / POST/messaging/reminders/:entityType/:entityIdЗавантажити або зберегти визначення нагадування для однієї сутності.
GET / POST/messaging/reminders/scope/:entityType/:scopeIdЗавантажити або зберегти визначення нагадування рівня області (успадковане).
DELETE/messaging/reminders/:defIdВидалити визначення і скасувати його очікувані події.
GET/messaging/reminders/event/:eventId/previewПереглянути кількість отримувачів і наступний час спрацювання для нагадування про подію до збереження.
GET/messaging/reminders/logОстання історія подій нагадувань для церкви.
POST/messaging/reminders/muteВимкнути нагадування для конкретної сутності.

Збереження визначення запускає синхронне повторне розгортання для цієї сутності або області, тож редактори бачать актуальні «наступні спрацювання» без очікування нічного завдання.

Особисті повідомлення​

Особисті повідомлення проходять ту саму воронку, що й усе інше, а не окремий шлях ескалації. Кожна непрочитана розмова отримує один тіньовий рядок у notifications (contentType='privateMessage', contentId = ідентифікатор особистого повідомлення, category='direct_messages'), який відповідає за весь стан доставки: ескалацію через сокет/push/email, відстеження прочитання тощо. Таблиця privateMessages зберігає сам вміст повідомлення і стовпець notifyPersonId. Саме з нього береться лічильник непрочитаних на значку, і він очищається, коли одержувач прочитає розмову.

Тіньові рядки не видно в дзвіночку сповіщень: вони виключаються із запиту кількості непрочитаних, із запиту списку сповіщень і із запитів позначення прочитаного та видалення. Усі вони фільтрують за contentType <> 'privateMessage'. Кожне сигнальне повідомлення про особисте повідомлення надходить у сокет незалежно від стану прочитання (семантика живого чату, без дедуплікації). Особисті повідомлення ніколи не зупиняються на доставці через сокет, на відміну від звичайних сповіщень, оскільки PWA у фоновому режимі може тримати сокет відкритим і все одно потребувати push на рівні ОС. Якщо людина вимикає сповіщення про особисті повідомлення, тіньовий рядок призупиняється (isNew=false, notifyPersonId очищається). Розмова все ще видна всередині самої розмови, але без значків і сповіщень.

Налаштування та гейт​

Кожне надсилання проходить через PreferenceGateHelper.evaluate(), чисту функцію (уся необхідна інформація передається на вхід, без викликів до бази даних на гарячому шляху), яка повертає allow, suppress або defer. Шари виконуються по порядку, і перший, що приймає рішення, має перевагу:

  1. Заблокована категорія. Деякі категорії є обов'язковими (рівень 0) і обходять усі інші шари.
  2. Глобальне вимкнення / вимкнення каналу. masterMute, allowPush, allowSms (за замовчуванням вимкнено, учасники вмикають самостійно) або emailFrequency='never' одразу пригнічують надсилання.
  3. Тихі години. Лише для push і SMS (email вважається неінвазивним). Якщо поточний час на годиннику в часовому поясі людини потрапляє в її тихе вікно, транзакційна категорія все одно доходить, а нетранзакційна відкладається до кінця тихого вікна. Цей час обчислюється як момент UTC з урахуванням переходу на літній час через TimezoneHelper.wallClockToUtc.
  4. Перевизначення налаштувань для категорії. Явна відмова для пари категорія × канал. Відсутність запису означає типове значення категорії.
  5. Вимкнення для сутності. Вимкнення, записане для конкретної сутності (наприклад, однієї події чи одного плану), обмежує сильніше, ніж налаштування на рівні категорії, але діє лише тоді, коли викликач передає разом зі сповіщенням ідентифікатор і тип сутності.

Задіяні таблиці: notificationPreferences (глобальні: masterMute, emailFrequency зі значеннями individual|daily|weekly|never, allowPush, вікно тихих годин і часовий пояс, allowSms), notificationPreferenceOverrides (для кожної пари категорія × канал) і notificationEntityMutes (для кожної сутності).

Цей гейт застосовується до in-app (рівень 0), push (рівень 1) і email (рівень 2) усередині воронки, включно з негайними листами нагадувань і дайджестів, а також до текстів нагадувань у ReminderEngine.sendSms(). Транзакційна електронна пошта (коди авторизації, скидання паролів, запрошення, квитанції про пожертви) обходить його за задумом, і в цьому й полягає сенс другого входу.

Робочі процеси підтвердження служіння​

План може увімкнути робочий процес workflowType = "assignmentConfirmation" (plans.confirmationWorkflowId). Тоді кнопка Publish/Notify викликає POST /doing/plans/:id/issueRequests замість окремого сповіщення для кожного призначення. Кожне нове призначення зі статусом Unconfirmed отримує notified і confirmationWorkflowId, а також одну картку робочого процесу (tasks.assignmentId, унікальний followupKey). Картка надсилає сповіщення лише в застосунку (appOnly: true, без ескалації на push чи email), а потім виконує дії sendAssignmentRequest робочого процесу. Вони проходять через MessagingModuleGateway.sendServingWorkflowMessage: email через NotificationHelper.sendWorkflowEmail (гейт налаштувань + ChurchEmailLimiter, облік як workflowEmail), SMS через sendPersonText лише за наявності allowSms і гейта категорії serving_schedule. Accept/Decline (assignment.updated на шині подій) закриває картку. Таймер 30 хвилин (AssignmentWorkflowHelper.processPending) відновлює пропущені старти та події, а запит без відповіді після граничного терміну нагадування перетворює на завдання перегляду для лідера. Повний життєвий цикл описано в Api/docs/assignment-confirmation-workflows.md.

Ліміти електронної пошти, створеної церквою​

Листи, зміст яких написала церква, надсилаються з спільної ідентичності SES ChurchApps, тож їх кількість обмежується для кожної церкви через Api/src/shared/helpers/ChurchEmailLimiter.ts. Чотири шляхи викликають його: надсилання групам і за шаблонами (EmailTemplateController, тип вмісту email), листи для подальших дій з форм (FormSubmissionController, formFollowUp), дії Send email у робочих процесах (NotificationHelper з churchAuthored, workflowEmail) і листи із запитом на підтвердження служіння (NotificationHelper.sendWorkflowEmail, workflowEmail). Системна пошта (коди авторизації, квитанції, нагадування) і запрошення до ролей та груп (UserController.sendInviteEmail, фіксований шаблон) не обмежуються.

  • Гейт схвалення. Церква не надсилає нічого, доки адміністратор сервера не встановить churches.emailApprovedDate (POST /membership/churches/:id/emailApproval, Адміністрування сервера → Церкви → чіп Групова електронна пошта). Архівні церкви завжди заблоковані. Діалог Send Email у B1Admin зчитує GET /messaging/emailTemplates/sendStatus (approved, paused, remaining, requested). Якщо церква не схвалена, замість редактора показується картка Request review. Редактор кроків робочого процесу зчитує ту саму кінцеву точку (доступну і для tasks.admin, і для groupMembers.edit), щоб попередити про дії Send email, коли церква не схвалена або призупинена. Під час надсилання MessagingModuleGateway.sendTemplatedEmail повертає false без створення сповіщення, якщо ChurchEmailLimiter.remaining() менше за 1. Тож історія картки ніколи не покаже Email sent для листа, який було відкинуто. POST /messaging/emailTemplates/requestApproval надсилає лист підтримці не частіше ніж раз на тиждень для кожної церкви.
  • Заробльований ліміт. Схвалена церква отримує max(150, 2 × її найкращий день з листами, створеними церквою, за попередні 30 днів), але не більше 2 000 за ковзні 24 години. Поточні 24 години не враховуються в «найкращому дні», щоб сплеск не міг підвищити власний ліміт.
  • Резервування, потім закриття. reserve() записує один рядок у deliveryLogs для кожного отримувача до надсилання, повторно перевіряє ліміт з урахуванням цих рядків і відкочує запит, якщо два запити одночасно перевищили ліміт (надсилання повертає 429). settle() позначає кожен рядок як надісланий або невдалий.
  • Призупинення через скарги. Лямбда sesFeedback (Api/src/lambda/ses-feedback-handler.ts, отримує дані від SES → SNS) прив'язує кожне постійне повернення або скаргу до тієї церкви, чий лист, створений церквою, дійшов до цієї адреси приблизно в той час. Вона зберігається як deliveryMethod sesBounce / sesComplaint. Церкву призупиняють при 2 або більше скаргах (≥ 0,3% надсилань) чи 10 або більше жорстких поверненнях (≥ 5%) за 7 днів.

Розклад​

І механізм нагадувань, і дайджест сповіщень працюють за наявними запланованими таймерами, а не через нову інфраструктуру:

ТаймерРозкладЩо виконує
Таймер 30 хвилинкожні 30 хвилинЕскалює непрочитані сповіщення; надсилає дайджести електронною поштою з частотою individual; диспетчеризує події нагадувань, що настали (ReminderEngine.scan); дайджести схвалень; автоматичні виконання, що настали
Нічний таймер05:00 UTCНагадування про відвідуваність групи; просуває повторювані трансляційні служіння; оновлює списки з автооновленням; розгортає події нагадувань на наступний горизонт (ReminderEngine.expandAll); надсилає дайджести з частотою daily

Локально ту саму логіку можна запустити вручну командами npm run timer:30min і npm run timer:midnight з проєкту Api.

Перелік файлів​

ОбластьФайли
ВоронкаApi/src/modules/messaging/helpers/NotificationHelper.ts, PreferenceGateHelper.ts, NotificationCategoryHelper.ts, WebPushHelper.ts, ExpoPushHelper.ts, SocketHelper.ts, DeliveryHelper.ts
Спільна точка входуApi/src/shared/helpers/NotificationService.ts
Транзакційний вхідApi/src/shared/helpers/TransactionalEmailHelper.ts, правило лінтера Api/tools/eslint-rules/email-door.cjs
Ліміти електронної пошти церквиApi/src/shared/helpers/ChurchEmailLimiter.ts, Api/src/lambda/ses-feedback-handler.ts, Api/src/modules/messaging/repositories/DeliveryLogRepo.ts
Механізм нагадуваньApi/src/modules/messaging/helpers/ReminderEngine.ts, ReminderBootstrap.ts, helpers/adapters/*, controllers/ReminderController.ts
Текстові повідомлення / відписка STOPApi/src/modules/messaging/helpers/SmsOptOutHelper.ts, controllers/TextingController.ts (/status, /inboundUrl, /inbound/:churchId/:token), Api/src/modules/doing/helpers/MatrixTextHelper.ts (дія Text Volunteers в огляді служіння)
Репозиторії нагадуваньApi/src/modules/messaging/repositories/ReminderDefinitionRepo.ts, ReminderOccurrenceRepo.ts, ReminderSentLogRepo.ts
Електронна пошта про служіння та планиApi/src/modules/doing/helpers/PlanReminderEmailHelper.ts, ReminderTokenHelper.ts, Api/src/shared/modules/DoingModuleGateway.ts
Редактори нагадувань (B1Admin)serving/components/PlanTypeReminderEdit.tsx, calendars/components/EventReminderEdit.tsx, serving/tasks/components/TaskReminderEdit.tsx, hooks/useTextingEnabled.ts
Редактор нагадувань / налаштування (B1App)EventReminderEdit.tsx, NotificationPrefsPage.tsx, useRealtimeNotifications.ts

Пов'язані сторінки​

  • Архітектура реального часу — протокол WebSocket і клієнтські примітиви (SocketHelper, SubscriptionManager, ConversationStore), на яких працює рівень доставки в застосунку
  • Web Push-сповіщення — налаштування VAPID і шлях браузерного Push API, який використовує рівень ескалації push
  • Кінцеві точки messaging — повний REST-інтерфейс для повідомлень, розмов, зв'язків і маршрутів сповіщень і нагадувань