Notifikační systém

Atrea User API poskytuje centralizovaný notifikační systém podporující email (SMTP + DKIM) a Web Push notifikace.

Architektura

Backend aplikace
    │
    └── POST /api/internal/notifications
            │
            ▼
    NotificationService
            │
    ┌───────┴────────┐
    │                │
    ▼                ▼
EmailService    PushService
(SMTP + DKIM)   (Web Push)
    │                │
    ▼                ▼
SMTP server    Push endpoint
(nodemailer)   (web-push)
    │
    └─ Audit log → notifications tabulka

Klíčové koncepty

Model má 3 úrovně (detaily viz Typy, šablony a jazykové verze):

NotificationType (skupina) → NotificationTemplate (pojmenovaná) → TemplateLocale (jazyk)

Notifikační typy (skupina)

Kategorie notifikace. Drží kanály a předvolby uživatele:

• emailEnabled / pushEnabled — kanály
• userCanDisable — může uživatel typ (celou skupinu) vypnout?
• defaultEmail / defaultPush — výchozí stav pro nové uživatele

Pojmenované šablony

Pod typem je 0..N šablon (key + name + variables). variables patří šabloně a jsou společné pro její jazyky.

Jazykové verze

Pod šablonou je 0..N verzí — Mustache subjectTemplate + bodyTemplate per locale.

Preference uživatele

• Globální: notificationsEnabled v UserAppPreference — master switch pro celou aplikaci
• Per-type: UserNotificationPreference — zapnout/vypnout konkrétní typ (email/push zvlášť)

Brand-aware emaily

Šablony se renderují s brandovacím contextem (barvy, logo, footer text) dle profilu uživatele.

Rozhodovací logika odesílání

Odesílám notifikaci?
    │
    ├─ Existuje NotificationType?               NE → skipped
    ├─ Existuje šablona pro locale?             NE → fallback locale z NotificationType (default "cs")
    ├─ notificationsEnabled pro aplikaci?       NE → skipped
    ├─ Preference uživatele pro typ?
    │   └─ email: true / push: true
    │                                           NE → skipped
    │
    ├─ Email?
    │   ├─ emailEnabled na typu?                NE → skip email
    │   └─ Odeslat SMTP (+ DKIM pokud nakonfig.)
    │
    └─ Push?
        ├─ pushEnabled na typu?                 NE → skip push
        ├─ Načíst subscripce uživatele
        └─ Odeslat Web Push na každé zařízení

Workflow: nastavení notifikací pro novou aplikaci

1. Vytvořte notifikační typ

POST /api/admin/notifications/types/moje-app
Authorization: Bearer <superadmin-token>
{
  "code": "new_order",
  "name": "Nová objednávka",
  "emailEnabled": true,
  "pushEnabled": true,
  "userCanDisable": true,
  "defaultEmail": true,
  "defaultPush": false
}

2. Vytvořte pojmenovanou šablonu pod typem

POST /api/admin/notifications/types/moje-app/new_order/templates
Authorization: Bearer <superadmin-token>
{
  "key": "default",
  "name": "Nová objednávka",
  "variables": [ { "key": "orderNumber", "required": true }, { "key": "customerName" } ]
}

2b. Přidejte jazykové verze (upsert per locale)

PUT /api/admin/notifications/templates/42/locales/cs
Authorization: Bearer <superadmin-token>
{
  "subjectTemplate": "Nová objednávka č. {{orderNumber}}",
  "bodyTemplate": "<h1>Přijata nová objednávka</h1><p>Objednávka č. {{orderNumber}} od {{customerName}}</p>"
}

3. Preview šablony

POST /api/admin/notifications/templates/preview
{
  "subjectTemplate": "Nová objednávka č. {{orderNumber}}",
  "bodyTemplate": "<h1>Přijata nová objednávka</h1><p>Objednávka č. {{orderNumber}} od {{customerName}}</p>",
  "data": { "orderNumber": "2024-001", "customerName": "Jan Novák" },
  "brand": "atrea"
}

4. Odesílání z backend aplikace

POST /api/internal/notifications
x-internal-api-key: <klic>
{
  "recipientEmail": "manager@firma.cz",
  "appCode": "moje-app",
  "type": "new_order",
  "template": "default",
  "data": {
    "orderNumber": "2024-042",
    "customerName": "Jan Novák"
  }
}

template je volitelné, když má typ jedinou šablonu (použije se automaticky); povinné, když jich má víc. Detaily viz Odeslání: type + template.

5. Hromadné rozeslání (1 / pole / všem)

Jeden typ lze rozeslat více příjemcům najednou — throttlovaně, na pozadí:

POST /api/admin/notifications/broadcast/moje-app
Authorization: Bearer <superadmin-token>
{
  "type": "maintenance_notice",
  "recipients": "all",          // nebo ["a@firma.cz", "b@firma.cz"]
  "data": { "from": "22:00", "to": "02:00" },
  "throttle": { "batchSize": 20, "delayMs": 1000 }
}

Vrátí job (202), průběh se polluje přes GET /admin/notifications/broadcast/jobs/:jobId. Detail viz Broadcast.

Audit log

Každá odeslání se loguje do tabulky notifications:

Pole	Popis
id	Unikátní ID záznamu
recipientEmail	Příjemce
appCode	Aplikace
type	Kód notifikačního typu (skupina)
template	Klíč použité šablony (null pro generic)
subject	Vykreslený předmět emailu
status	sent / failed / skipped
statusReason	Důvod failed nebo skipped
locale	Použité locale
payload	JSON data předaná při odesílání
createdAt	Čas odeslání

Přístup k logu

# Log konkrétního uživatele
GET /api/internal/notifications/log/uzivatel@firma.cz

# Log celé aplikace (admin)
GET /api/admin/notifications/log/moje-app

Viz také

• Typy & šablony — detaily o typech a Mustache šablonách
• Broadcast — rozeslání jedné šablony jednomu / poli / všem (throttlovaně)
• Web Push — VAPID, subscripce, odesílání push
• API: Notifikace — kompletní API reference