📦 Notification Sub Service – Data Model¶

Tài liệu này mô tả chi tiết các thực thể dữ liệu cốt lõi của Notification Sub Service, bao gồm schema, quan hệ, và các lưu ý về bảo mật, ẩn danh và chuẩn hóa schema theo chuẩn đa tenant.

1. 🎯 Mục tiêu & Phạm vi¶

Phần này xác định rõ phạm vi dữ liệu mà Notification Sub Service quản lý, đồng thời nhấn mạnh mục tiêu thiết kế dữ liệu đa tenant, có khả năng mở rộng, kiểm thử và truy vết.

🎯 Mục tiêu¶

• Cung cấp mô hình dữ liệu chuẩn hóa để lưu trữ các hoạt động gửi notification cho từng tenant.
• Hỗ trợ việc truy vấn hiệu quả thông tin log đã gửi theo nhiều tiêu chí: event, channel, trạng thái, người nhận.
• Cho phép mapping động giữa event_code + channel → template tùy theo tenant.
• Lưu trữ cấu hình kênh gửi riêng cho mỗi tenant với khả năng bật/tắt và fallback.
• Đảm bảo dữ liệu phù hợp với các yêu cầu:
• Audit & Compliance theo ADR-008
• Retention & Anonymization theo ADR-024
• Multi-tenant Isolation theo CR-04 & ADR-025

📦 Phạm vi dữ liệu được quản lý¶

🔒 Nguyên tắc thiết kế dữ liệu¶

⛔ Không nằm trong phạm vi¶

• Không lưu trạng thái đọc / unread
• Không lưu trạng thái gửi real-time của client (client-side delivery)
• Không lưu full render HTML trừ khi cần audit (tuỳ cấu hình)
• Không quản lý luồng trigger gửi (thuộc về Notification Master)

2. 🔢 Mô hình dữ liệu tổng thể¶

Hệ thống Notification Sub quản lý ba thực thể chính:

1. NotificationTemplate – Metadata template gắn với event_code, channel, và tenant
2. NotificationLog – Lưu lại từng lần gửi thực tế, bao gồm trace, lỗi, người nhận
3. NotificationChannelCfg – Cấu hình kênh gửi cho mỗi tenant và channel

Mô hình tuân thủ chặt chẽ kiến trúc multi-tenant, hỗ trợ versioning, tracing và khả năng kiểm toán đầy đủ.

🧭 Mối quan hệ giữa các thực thể¶

```mermaid 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 INTEGER version STRING tenant_id TIMESTAMPTZ updated_at }

NotificationLog { UUID id PK UUID template_id FK STRING recipient STRING status TEXT error_message JSONB payload STRING tenant_id TIMESTAMPTZ sent_at STRING event_code STRING channel BOOLEAN retry STRING trace_id }

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

📌 Giải thích tổng quan các bảng¶

🧩 Thiết kế hỗ trợ:¶

3. 📚 Chi tiết các bảng¶

3.1. NotificationTemplate¶

Lưu trữ metadata và nội dung template cho từng event_code và channel. Hỗ trợ versioning, ngôn ngữ, trạng thái bật/tắt và kiểm tra render (qua POST /notifications/test).

🔎 Ràng buộc quan trọng: - Unique constraint: (tenant_id, event_code, channel, language, version) - Có index trên tenant_id, event_code, channel, is_active

3.2. NotificationLog¶

Lưu lại từng lần gửi notification (gửi thật hoặc test). Phục vụ audit, kiểm tra lỗi, thống kê.

🔎 Lưu ý: - Có index trên tenant_id, event_code, status, sent_at, recipient - Có thể xóa mềm hoặc TTL 30 ngày theo ADR-024

3.3. NotificationChannelCfg¶

Lưu cấu hình kênh gửi (SMTP, SMS provider...) riêng cho từng tenant. Hỗ trợ bật/tắt động, fallback hoặc dry-run.

🔎 Best Practice: - Config được load từ cache, invalidate khi có cập nhật - Có thể có thêm trường test_email, test_number dùng cho POST /notifications/test

📌 Gợi ý mở rộng tương lai (optional):

4. 🔐 Chính sách bảo mật & đa tenant¶

Thiết kế dữ liệu của Notification Sub Service đặt trọng tâm vào tách biệt dữ liệu tenant, bảo mật thông tin cá nhân, và tuân thủ chính sách kiểm toán & lưu trữ.
Các nguyên tắc sau được áp dụng ở mọi tầng: schema, query, API, log và pipeline event.

4.1. 🧱 Tách biệt theo tenant (Tenant Isolation)¶

🔐 Tuân thủ ADR-025 – Multi-Tenant Versioning, ADR-007 – RBAC, CR-04 – Phân vùng tenant vật lý/logic

4.2. 🛡️ Bảo vệ dữ liệu cá nhân¶

Tuân thủ ADR-024 – Data Anonymization & Retention

4.3. 🕓 Chính sách giữ dữ liệu (Retention)¶

Nếu cần soft-delete (dùng archived_at), nên thêm theo ADR-026 – Hard Delete Policy

4.4. 🔍 Giám sát & kiểm toán¶

4.5. ✅ Checklist tuân thủ bảo mật & đa tenant¶

5. 🧩 Mapping sang các API¶

Bảng dưới đây trình bày mối quan hệ giữa từng API và các bảng dữ liệu liên quan.
Mục tiêu là đảm bảo tính nhất quán giữa luồng nghiệp vụ, dữ liệu lưu trữ, và hợp đồng giao tiếp (interface contract).

5.1. 📌 Chi tiết truy xuất & ghi dữ liệu theo API¶

🔍 GET /notifications/logs¶

• Read-only
• Truy vấn trên bảng NotificationLog
• Dựa trên tenant_id, có thể filter theo status, channel, event_code, recipient

🧪 POST /notifications/test¶

• Truy xuất NotificationTemplate để render
• Truy xuất NotificationChannelCfg để kiểm tra config kênh gửi
• Ghi log gửi thử vào NotificationLog (dạng test, không ảnh hưởng thống kê chính)
• Gắn trace_id, status: sent, failed, test_only: true

📑 GET /notifications/templates¶

• Truy xuất từ NotificationTemplate với tenant_id tương ứng
• Không trả template_body, chỉ metadata để UI lựa chọn

5.2. 🔐 RBAC Mapping¶

6. 📌 Schema versioning & kiểm thử schema¶

6.1. 🎯 Mục tiêu¶

Việc version hóa schema giúp đảm bảo: - Tương thích ngược khi template thay đổi cấu trúc - Hỗ trợ A/B testing hoặc rollback khi cấu hình gửi thay đổi - Cho phép kiểm tra tính đúng đắn của schema trước khi gửi thực tế

6.2. 📚 Vị trí version trong hệ thống¶

Hệ thống KHÔNG nhúng version vào event_code – theo khuyến nghị của ADR-030.

6.3. 🧪 Cơ chế kiểm thử schema¶

Gửi thử (POST /notifications/test) đóng vai trò là cơ chế kiểm thử schema động.

❗ Các lỗi render, thiếu biến, sai kiểu sẽ được phát hiện tại bước 3 – không được phép đến bước gửi.

6.4. 🧩 Cơ chế quản lý template theo version¶

6.5. ✅ Kiểm thử schema nên bao gồm:¶

7. 🧪 Gợi ý kiểm thử dữ liệu¶

Các trường hợp kiểm thử dưới đây nhằm đảm bảo hệ thống lưu trữ dữ liệu đúng, phản ánh chính xác luồng nghiệp vụ, đồng thời hỗ trợ audit và phân tích sự cố dễ dàng.

7.1. 🔄 Kiểm thử tạo & truy vấn log gửi¶

7.2. 📄 Kiểm thử template¶

7.3. 🔐 Kiểm thử liên quan bảo mật & phân vùng tenant¶

7.4. 🧩 Kiểm thử toàn vẹn dữ liệu¶

7.5. ✅ Checklist xác nhận dữ liệu¶

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

• Design.md
• Interface Contract
• OpenAPI Spec
• ADR-030 – Event Schema Governance
• ADR-024 – Data Anonymization & Retention
• ADR-025 – Multi-Tenant Versioning
• ADR-007 – RBAC