Notification Service

Microsluzba pro odesilani notifikaci (email, SMS, Slack, push). Postavena na Cloudflare Workers s D1 databazi.

Obsah

• Architektura
• Kanaly notifikaci
• Queue processing
• Konektory
• RPC akce
• Audit logging
• Databazove schema
• Error Codes

Architektura

Sluzba se sklada z:

• Akce (Actions) - RPC endpointy pro odesilani notifikaci
• Queue handler - Asynchronni zpracovani notifikaci z fronty
• Konektory - Abstrakce nad API externich sluzeb (Ecomail, Twilio, Slack)
• Audit log - Zaznamenani vsech odeslanych notifikaci do D1

Bindings:

• NOTIFICATION_D1 - Cloudflare D1 databaze
• NOTIFICATIONS_QUEUE - Fronta pro asynchronni zpracovani
• SECRETS_STORE - Service binding na secrets store
• SLACK_WEBHOOK - Webhook URL pro Slack notifikace

Kanaly notifikaci

| Kanal | Konektor | Stav | |-------|----------|------| | Email | Ecomail | Aktivni | | SMS | Twilio | Aktivni | | Slack | Slack Webhook | Aktivni | | Push | - | Neimplementovano |

Queue processing

Notifikace lze odesilat synchronne (primo) nebo asynchronne (pres frontu).

Async flow (vychozi)

public-send-email / public-send-sms
  │
  ▼
NOTIFICATIONS_QUEUE
  │
  ▼
Queue handler (switch dle type)
  ├─ email  → _sendEmail()
  ├─ sms    → _sendSms()
  ├─ slack  → sendSlackNotification()
  └─ push   → _sendPushNotification() (501)
  │
  ├─ success → message.ack()
  └─ error   → message.retry() (exponential backoff, base 60s)

Sync flow

public-send-email-sync vola _sendEmail() primo bez fronty.

Queue message

{
  type: 'email' | 'sms' | 'pushNotification' | 'slack'
  metadata: {
    userAgent?: string
    ip?: string
    initiator: { service: string, userId?: string }
  }
  payload: {
    email?: IEmail
    sms?: ISms
    pushNotification?: IPushNotification
    slack?: ISlack
  }
}

Konektory

Ecomail (email)

Provider pro transakcni emaily. Podporuje:

• Plain text a HTML emaily (/transactional/send-message)
• Template emaily s merge vars (/transactional/send-template)
• Prilohy (base64, max 10 priloh, celkem 25MB)
• CC, BCC, Reply-To

Omezeni: Ecomail odmita emaily s localhost v template variables - connector automaticky nahradi localhost za origin.

Twilio (SMS)

Provider pro SMS pres Twilio Messaging Service.

Slack (webhook)

Odesilani notifikaci pres Slack Incoming Webhook. Timeout 3s.

RPC akce

Notification service je RPC worker - vsechny akce dostupne pres Cloudflare Worker binding.

Verejne akce

| Akce | Popis | |------|-------| | public-send-email | Zaradi email do fronty (async) | | public-send-email-sync | Odesle email primo (sync) | | public-send-sms | Zaradi SMS do fronty (async) | | send-slack-notification | Odesle Slack notifikaci (sync) |

Interni akce

| Akce | Popis | |------|-------| | private-send-email | Odesle email pres konektor + audit log | | private-send-sms | Odesle SMS pres konektor + audit log | | send-push-notification | Neimplementovano (501) |

Vstupy

Vsechny akce vyzaduji metadata objekt:

metadata: {
  userAgent?: string
  ip?: string        // IPv4 nebo IPv6
  initiator: {
    service: string  // nazev volajici sluzby
    userId?: string
  }
}

Email podporuje: to, cc, bcc, replyTo, from, subject, text, html, templateId, templateVariables, attachments.

SMS podporuje: message, to.

Slack podporuje: message.

Audit logging

Kazdy uspesne odeslany email a SMS se zaznamenava do audit logu.

Zaznamenavane udaje: event type, IP adresa, user agent, popis (JSON vstupu), initiator service, initiator user ID.

Databazove schema

audit_log

| Sloupec | Typ | Popis | |---------|-----|-------| | id | text | UUID | | createdAt | timestamp | Cas vytvoreni | | event | text | EMAIL | SMS | PUSH_NOTIFICATION | SLACK | | ip | text | IP adresa (nullable) | | userAgent | text | User agent (nullable) | | description | text | JSON dump vstupu (nullable) | | initiatorService | text | Nazev volajici sluzby | | initiatorUserId | text | ID uzivatele (nullable) |

Error Codes

Format: {CATEGORY}-N-{NUMBER}

| Code | Status | Popis | |------|--------|-------| | CONN-N-01 | 502 | Ecomail: failed to send email | | CONN-N-02 | 502 | Ecomail: failed to send template email | | CONN-N-03 | 502 | Twilio: failed to send SMS | | CONN-N-04 | 502 | Slack: failed to send notification | | CONN-N-05 | 504 | Slack: request timed out | | VALID-N-01 | 404 | Unsupported email provider | | VALID-N-02 | 404 | Unsupported SMS provider | | SYS-N-01 | 501 | Push notifications not implemented |