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

Notifikační typy

Definují, jaké notifikace aplikace posílá. Každý typ má:

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

Šablony

Mustache-style šablony s subjectTemplate a bodyTemplate (HTML). Podporují více 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 na "cs" nebo skipped
    ├─ 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 šablonu

POST /api/admin/notifications/templates/moje-app
Authorization: Bearer <superadmin-token>
{
  "type": "new_order",
  "locale": "cs",
  "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",
  "data": {
    "orderNumber": "2024-042",
    "customerName": "Jan Novák"
  }
}

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
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
• Web Push — VAPID, subscripce, odesílání push
• API: Notifikace — kompletní API reference