Broadcast — odeslání jedné šablony více uživatelům

Kromě odeslání jednomu uživateli (POST /internal/notifications) umí API rozeslat jeden notifikační typ najednou:

• jednomu uživateli,
• poli uživatelů,
• nebo všem ("all") — všem aktivním uživatelům s rolí v dané aplikaci.

Rozesílání běží na pozadí a je throttlované (po dávkách s prodlevou), aby nás SMTP relay nezablokoval. Endpoint vrátí job ihned (202) a průběh se zjišťuje pollováním.

Endpointy jsou na admin API (JWT + SuperAdmin) — typicky je volá atrea-user-panel.

Throttling

Příjemci se zpracují po dávkách (batchSize, odesílají se paralelně v rámci dávky); mezi dávkami runner počká delayMs. Strop ≈ batchSize / (delayMs/1000) e-mailů/s.

Parametr	Default	Rozsah	Význam
batchSize	10	1–100	Počet příjemců v jedné dávce (paralelně)
delayMs	1000	0–60000	Prodleva mezi dávkami (ms)

Hodnoty mimo rozsah se ořežou (clamp). Default ≈ 10 e-mailů/s — šetrné. Pro velké "all" kampaně volte konzervativně dle limitů SMTP relaye.

Každé jednotlivé odeslání jde standardní cestou NotificationService.send — respektuje preference, locale, kanály i brand příjemce a loguje se do tabulky notifications. Odhlášení uživatelé se počítají jako skipped.

POST /admin/notifications/broadcast/:appCode — spuštění

POST /api/admin/notifications/broadcast/crm
Authorization: Bearer <superadmin-token>
Content-Type: application/json

{
  "type": "error",
  "template": "maintenance_notice",
  "recipients": "all",
  "data": { "from": "2026-06-20 22:00", "to": "2026-06-21 02:00" },
  "locale": "cs",
  "channels": ["email"],
  "throttle": { "batchSize": 20, "delayMs": 1000 }
}

Pole	Typ	Povinné	Popis
type	string	✓	Kód notifikačního typu / skupiny (musí existovat; nebo generic)
template	string	✗*	Pojmenovaná šablona pod typem. *Volitelné, když má typ jedinou šablonu; jinak povinné (400 TEMPLATE_REQUIRED).
recipients	"all" | string[]	✓	"all" = všichni aktivní uživatelé s rolí v aplikaci; jinak pole e-mailů
data	object	✗	Data šablony (stejná pro všechny příjemce)
locale	string	✗	Vynutit locale (jinak per-user preference)
brand	string	✗	Vynutit brand (jinak per-user)
channels	("email"|"push")[]	✗	Omezit kanály
throttle	object	✗	{ batchSize, delayMs } — viz Throttling

Pre-flight validace

Před spuštěním kampaně se ověří (jednou, ať nevznikne tisíc selhání):

• aplikace existuje,
• šablona jde rozpustit z type + template (nebo type = "generic") → jinak 400 UNKNOWN_TEMPLATE / TEMPLATE_REQUIRED (details.available = [klíče]),
• data obsahuje všechny required parametry zvolené šablony → jinak 400 MISSING_TEMPLATE_VARIABLES,
• po rozpuštění recipients zbyl aspoň jeden příjemce.

Response — 202 Accepted

{
  "code": "OK",
  "response": {
    "id": "9b1c…-uuid",
    "appCode": "crm",
    "type": "error",
    "template": "maintenance_notice",
    "status": "running",
    "total": 142,
    "processed": 0,
    "sent": 0,
    "failed": 0,
    "skipped": 0,
    "errors": [],
    "throttle": { "batchSize": 20, "delayMs": 1000 },
    "startedAt": "2026-06-14T10:00:00.000Z"
  }
}

GET /admin/notifications/broadcast/jobs/:jobId — stav jobu

Pollování průběhu. status: running → completed / failed / canceled.

{
  "code": "OK",
  "response": {
    "id": "9b1c…-uuid",
    "status": "completed",
    "total": 142,
    "processed": 142,
    "sent": 128,
    "failed": 2,
    "skipped": 12,
    "errors": [ { "email": "bad@x.cz", "reason": "EMAIL_…" } ],
    "throttle": { "batchSize": 20, "delayMs": 1000 },
    "startedAt": "2026-06-14T10:00:00.000Z",
    "finishedAt": "2026-06-14T10:00:08.000Z"
  }
}

errors je oříznuté na prvních 50 položek pro rychlou diagnostiku; kompletní záznam každého odeslání je v audit logu.

GET /admin/notifications/broadcast/jobs — seznam jobů

Poslední joby (od nejnovějšího). Joby jsou in-memory a prunují se ~1 h po dokončení (samotná odeslání jsou trvale v logu).

POST /admin/notifications/broadcast/jobs/:jobId/cancel — zrušení

Zruší běžící job — runner se zastaví před další dávkou (rozdělané dávky se dokončí).

Trvalost jobů

Stav jobu (agregát) je in-memory → po restartu API zmizí. Jednotlivá odeslání (kdo co dostal) jsou trvale v tabulce notifications. Pokud běží víc replik API nebo chcete joby přežívající restart, je potřeba je odložit do DB (tabulka + migrace).