📘 Thiết kế chi tiết Notification Sub Service¶

1. 🧭 Phạm vi và Trách nhiệm¶

🎯 Mục tiêu¶

• Lắng nghe sự kiện notification.triggered từ Notification Master để gửi thông báo thực tế đến người dùng cuối trong từng tenant.
• Quản lý cấu hình kênh gửi của tenant (email, SMS, push), mapping template và xử lý fallback logic.
• Ghi nhận log gửi để phục vụ tra soát, thống kê, và audit.

📦 Các thực thể dữ liệu quản lý¶

🔒 Ngoài Phạm Vi¶

Service này không thực hiện: - ❌ Quản lý trigger business logic tạo ra notification – đã được tách riêng tại Notification Master. - ❌ Tự generate nội dung hoặc cá nhân hóa sâu (việc đó do master thực hiện). - ❌ Gửi thông báo vượt quyền tenant (cross-tenant broadcast). - ❌ Xác thực user – được thực hiện tại Gateway.

👥 Đối tượng sử dụng¶

• Notification Master (qua Pub/Sub – async)
• Superadmin Webapp (cho mục đích tra log, kiểm tra trạng thái – nếu cần)
• Admin Webapp của tenant (truy cập nội bộ để chỉnh sửa cấu hình kênh)

2. 🌐 Thiết kế API chi tiết¶

🔧 Tuân thủ: - ADR-011: Error Format - ADR-012: Response Envelope - ADR-013: Path Naming - ADR-030: Event Schema Governance (consume: notification.triggered) - 📎 Chi tiết xem tại: Interface Contract và OpenAPI Spec

3. 🗃️ Mô hình dữ liệu chi tiết¶

erDiagram
  NotificationTemplate ||--o{ NotificationLog : used_by
  NotificationChannelCfg ||--o{ NotificationTemplate : configures

  NotificationTemplate {
    UUID id PK
    STRING event_code
    STRING channel
    TEXT template_body
    JSONB default_params
    BOOLEAN is_active
    TIMESTAMPTZ updated_at
  }

  NotificationLog {
    UUID id PK
    UUID template_id FK
    STRING recipient
    STRING status
    TEXT error_message
    JSONB payload
    TIMESTAMPTZ sent_at
  }

  NotificationChannelCfg {
    STRING channel PK
    STRING provider
    JSONB config
    BOOLEAN is_enabled
    TIMESTAMPTZ updated_at
  }
````

> 📎 Chi tiết xem tại: [Data Model](./data-model.md)

---

### 4. 🔄 Luồng nghiệp vụ chính – Chi tiết hóa

#### 4.1. Mục tiêu

Mỗi lần nhận được sự kiện `notification.triggered`, service phải:

1. Lấy đúng template phù hợp theo `event_code`, `channel`, `tenant_id`
2. Gửi notification qua kênh tương ứng (email, SMS, v.v.)
3. Log đầy đủ hành động gửi – trạng thái, lỗi nếu có, thời gian
4. Có fallback nếu gửi kênh chính thất bại (nếu được cấu hình)
5. Tuân thủ giới hạn (rate-limit, retry theo config nếu có)

---

#### 4.2. Mô tả logic đầy đủ

```mermaid
sequenceDiagram
    participant PubSub as Pub/Sub
    participant NotiSub as Notification Sub
    participant DB as Notification DB
    participant Email as Email/SMS Gateway
    participant Fallback as Fallback Channel

    PubSub-->>NotiSub: Nhận sự kiện `notification.triggered`
    Note right of NotiSub: Extract `tenant_id`, `event_code`, `channel`, `recipient`, `params`

    NotiSub->>DB: Truy vấn NotificationTemplate (match theo `event_code`, `channel`, `tenant_id`)
    alt Không tìm thấy template
        NotiSub-->>DB: Ghi log lỗi "template not found"
        Note right of NotiSub: Dừng xử lý – không gửi
    else Template hợp lệ
        NotiSub->>DB: Ghi log trạng thái `queued`, lưu payload
        NotiSub->>Email: Gửi thông báo (render template + send)
        alt Gửi thành công
            Email-->>NotiSub: OK
            NotiSub->>DB: Update log → status=`sent`
        else Gửi thất bại
            Email-->>NotiSub: Error
            alt Có fallback được cấu hình
                NotiSub->>Fallback: Gửi lại qua kênh fallback
                Fallback-->>NotiSub: OK/Error
                NotiSub->>DB: Update log → status=`sent_fallback` hoặc `failed`
            else Không có fallback
                NotiSub->>DB: Update log → status=`failed`, lưu lỗi
            end
        end
    end

4.3. Chi tiết các bước¶

4.4. Ghi chú & lưu ý triển khai¶

• Template Mapping phải đúng channel – tránh gửi email bằng SMS template hoặc ngược lại.
• Bảo vệ chống gửi lặp nếu Pub/Sub delivery bị trùng → cần xử lý idempotency qua event_id.
• Fallback policy có thể cấu hình ở level NotificationChannelCfg, ví dụ:

{
  "channel": "email",
  "fallback": ["sms"],
  "retry_limit": 2
}

5. 📣 Tương tác & Sự kiện¶

5.1. Sự kiện nhận vào (Consumed Event)¶

🔔 Sự kiện: notification.triggered.v1¶

Ví dụ schema (JSON):

{
  "event_id": "3a36f1d4-8fa7-4704-a94e-4c55e9142cb3",
  "tenant_id": "tenant-vas-001",
  "event_code": "user.welcome",
  "channel": "email",
  "recipient": "student@example.edu.vn",
  "params": {
    "full_name": "Nguyễn Văn A",
    "first_login_at": "2025-06-01T10:00:00Z"
  },
  "trigger_by": "admin_123",
  "trace_id": "x-trace-abc-789",
  "created_at": "2025-06-14T07:32:00Z"
}

✅ Schema này được quản lý và version hóa theo ADR-030 – Event Schema Governance

5.2. Xử lý sự kiện¶

• Notification Sub Service sẽ đăng ký lắng nghe topic tương ứng, ví dụ:

• GCP Pub/Sub: vas.notification.triggered.v1

• Kafka: notification.triggered.v1

• Khi nhận event, service thực hiện pipeline:

• Parse + Validate schema theo version

• Check event_id đã xử lý chưa → để tránh gửi lặp (idempotency)
• Render template
• Gửi notification
• Ghi log + kết quả gửi + trace_id + status

5.3. Không phát sinh sự kiện outbound¶

Notification Sub không phát event ngược ra ngoài. Tuy nhiên:

• Có thể log vào hệ thống Audit Logging (theo adr-008) bằng cách gọi nội bộ tới audit-logging-service
• Không có luồng đồng bộ đẩy ra Pub/Sub để tránh phát sinh spam hoặc loop

5.4. Biến thể sự kiện & khả năng mở rộng¶

📌 Các biến thể nên được định nghĩa rõ trong event-schemas/registry theo ADR-030

5.5. Chính sách Schema & Versioning¶

Tuân thủ nghiêm ngặt ADR-030:

• Không thay đổi field bắt buộc trong version cũ
• Nếu cần breaking change → tạo version mới (vd: v2) và dual-publish trong giai đoạn chuyển tiếp
• Mỗi sự kiện đều mang event_id, trace_id, version, tenant_id

6. 🔐 Bảo mật & RBAC¶

6.1. Authentication – Xác thực¶

• Mọi API của Notification Sub đều yêu cầu người dùng đã xác thực qua API Gateway, dùng JWT chuẩn theo ADR-006.

• Token sẽ được kiểm tra signature và claim gồm:

• sub: user ID

• tenant_id: mã tenant đang truy cập
• permissions: danh sách quyền có dạng notif.read.log, notif.send.test, v.v.
• exp: thời điểm hết hạn
• Token được đính kèm qua header:

Authorization: Bearer <access_token>

6.2. Authorization – Phân quyền¶

Áp dụng mô hình RBAC phân tầng theo tenant, theo chuẩn ADR-007. Mỗi API đều khai báo permission yêu cầu qua x-required-permission, ví dụ:

x-required-permission: notif.read.log

Quy tắc phân quyền:¶

✅ Danh sách permission được cấp theo từng user_role gắn với X-Tenant-ID

6.3. Tenant Isolation – Tách biệt tenant¶

Theo yêu cầu của CR-04, mọi hành động (query, mutate, audit) đều phải:

• Ràng buộc trong phạm vi X-Tenant-ID (đọc từ JWT hoặc header)
• Không cho phép truy cập chéo tenant (trừ Superadmin)
• Có cấu trúc condition rõ trong OpenAPI:

x-condition:
  tenant_id: "{{X-Tenant-ID}}"

6.4. Audit Logging – Ghi log kiểm toán¶

Tuân thủ ADR-008, mọi hành động quan trọng sẽ được log lại dưới dạng Audit Event, bao gồm:

Audit log được đẩy async tới audit-logging-service hoặc ghi nội bộ tùy theo cấu hình môi trường

6.5. Data Protection – Bảo vệ dữ liệu cá nhân¶

• Không lưu plaintext recipient hoặc payload nếu không cần thiết.
• Trường nhạy cảm (recipient, error_message) có thể bị mask hoặc hash nếu được cấu hình.
• Có thể dùng ADR-024 để thiết lập thời gian anonymization hoặc retention policy theo từng tenant.

6.6. Các biện pháp phòng vệ bổ sung¶

7. ⚙️ Cấu hình & Phụ thuộc¶

7.1. Biến môi trường chính (ENV VARS)¶

🔐 Secrets như SMTP credentials, access tokens không bao giờ hardcode – được mount từ Secret Manager hoặc Vault (theo ADR-003 và ADR-004)

7.2. Cấu hình theo tenant (Dynamic per-tenant)¶

Các tenant có thể có cấu hình khác nhau như:

Thông tin này được nạp từ TENANT_CONFIG_SECRET_PATH theo mỗi tenant (tenant_id) trong runtime.

7.3. Phụ thuộc hệ thống¶

7.4. Phân biệt giữa cấu hình "build-time" và "runtime"¶

8. 🧪 Kiểm thử¶

Việc kiểm thử notification-service/sub/ được chia thành 4 lớp chính: Unit, Integration, Contract, và Security & RBAC. Tất cả các test đều cần tự động hóa và được tích hợp vào CI pipeline qua GitHub Actions (adr-001).

8.1. 🧪 Unit Tests¶

✅ Tỷ lệ coverage bắt buộc > 80% (code coverage report tích hợp CI/CD)

8.2. 🔄 Integration Tests¶

8.3. 🤝 Contract Tests (theo ADR-010)¶

Tuân thủ kiểm thử giao diện (OpenAPI contract):

Sử dụng:

• Prism hoặc Dredd để test OpenAPI spec
• CI sẽ fail nếu sai contract (ví dụ đổi schema không báo trước)

8.4. 🛡️ RBAC & Security Tests¶

✅ Kết quả test phải khớp với error-codes.md theo ADR-011

8.5. 📊 Đo lường & Báo cáo¶

• Báo cáo test coverage (pytest-cov, jest,...) gửi về CI/CD dashboard

• Ghi rõ:

• % coverage theo service/module

• Tên test bị fail và lý do
• Tự động chạy lại test nếu xảy ra race condition do message queue

8.6. 🧪 Test trong môi trường staging¶

Mỗi release trước khi đưa lên production sẽ được kiểm tra trong staging với:

9. 📈 Giám sát & Audit¶

9.1. 🔍 Logging (Ứng dụng & Gửi thông báo)¶

9.2. 📊 Metrics (Prometheus / OpenTelemetry)¶

✅ Tất cả metric đều được gắn nhãn (labels) gồm tenant_id, channel, status, template_id nếu có.

9.3. 🎯 SLO & Alerting¶

Tuân thủ ADR-022 – thiết lập SLO cho service:

✅ Alert được gửi về Email/Slack qua Alertmanager hoặc Grafana OnCall.

9.4. 📁 Audit Log (tuân thủ ADR-008)¶

Các hành vi cần audit:

• Audit log được đẩy async tới audit-logging-service qua HTTP nội bộ.
• Log phải chứa: actor_id, tenant_id, trace_id, action, timestamp, details.

9.5. 🔁 Tracing (OpenTelemetry)¶

Tích hợp OpenTelemetry để trace xuyên suốt hành trình notification:

Tất cả trace được gắn với trace_id gốc từ sự kiện. Dữ liệu gửi về OTEL Collector → Grafana Tempo hoặc Jaeger.

10. 🚀 Triển khai & Migration¶

10.1. 🧭 Chiến lược triển khai¶

Việc triển khai notification-service/sub/ được thiết kế để đảm bảo Zero Downtime theo ADR-014 với các đặc điểm:

10.2. ☁️ Môi trường & ranh giới triển khai (theo ADR-017)¶

🔐 Cấu hình ENVIRONMENT sẽ ảnh hưởng đến behavior gửi thật hay giả (ví dụ: smtp-sandbox trong dev)

10.3. 🚀 Tự động hóa triển khai (CI/CD)¶

Tuân thủ ADR-001:

10.4. 📥 Migration dữ liệu (schema & dữ liệu)¶

Tuân thủ ADR-023 – Schema Migration Strategy

Công cụ gợi ý¶

• Quản lý migration: Alembic hoặc Sqlx (nếu dùng Python / Go)
• Kiểm tra forward/backward compatibility: schemachange hoặc sqldiff

10.5. ⛑️ Rollback strategy¶

10.6. 📋 Checklist trước production¶

11. 🧩 Kiến trúc nội bộ¶

11.1. Mục tiêu phân lớp¶

Hệ thống được thiết kế theo hướng module hóa rõ ràng, tách biệt theo chức năng để dễ dàng mở rộng, kiểm thử và bảo trì.

11.2. Sơ đồ luồng xử lý nội bộ¶

flowchart TD
    PubSub[Event Listener]
    PubSub --> Parser[Parse + Validate Event]
    Parser --> TemplateLookup[Lookup Template]
    TemplateLookup --> RenderEngine[Render Template]
    RenderEngine --> Notifier[Send Notification]
    Notifier --> Audit[Log Audit]
    Notifier --> LogWriter[Ghi NotificationLog]

    subgraph Modules
      TemplateLookup
      RenderEngine
      Notifier
      Audit
      LogWriter
    end

11.3. Phân tích module chính¶

🧩 consumer/¶

• Nhận sự kiện từ Pub/Sub
• Parse & validate schema (tuân theo ADR-030)
• Bắt đầu trace (trace_id)
• Gửi vào processor

🧩 processor/¶

• Truy cập tenant_id để load cấu hình (config/)
• Gọi template_repository để tìm template khớp event_code + channel
• Render nội dung
• Gọi notifier/ để gửi đi
• Ghi log + fallback nếu thất bại
• Gửi log audit nếu bật

🧩 notifier/¶

• Có các adapter theo kênh:

• notifier/email.py

• notifier/sms.py
• notifier/push.py (chưa triển khai)
• Giao diện thống nhất: send(recipient, content, config)

🧩 repository/¶

• Truy cập Postgres: bảng NotificationLog, Template, ChannelCfg
• Được mock dễ dàng trong test

🧩 config/¶

• Load cấu hình theo tenant_id từ Secret Manager / mount path
• Có cơ chế cache nội bộ (TTL: 5 phút)
• Tự invalid cache khi có sự kiện config.updated

🧩 audit/¶

• Tạo cấu trúc audit log (tuân theo ADR-008)
• Gửi async sang audit-logging-service

🧩 api/¶

• Expose REST API nội bộ:

• GET /notifications/logs

• POST /notifications/test
• GET /notifications/templates

11.4. Logging & Tracing luồng nội bộ¶

• Mỗi bước trong luồng xử lý đều tạo 1 span nếu dùng OpenTelemetry

• Toàn bộ log theo chuẩn JSON và đính kèm:

• tenant_id

• event_id
• trace_id
• template_id
• channel

11.5. Khả năng mở rộng & plugin¶

Hệ thống có thể dễ dàng mở rộng thêm kênh gửi mới:

12. 📚 Tài liệu liên quan¶

• Interface Contract
• Data Model
• OpenAPI Spec
• ADR-007 – RBAC Strategy
• ADR-008 – Audit Logging
• ADR-030 – Event Schema Governance
• Change Request 04 – Tenant Isolation
• README.md – System Overview
• RBAC Deep Dive
• System Diagram