📘 ADR Index – dx-vas¶
Danh sách và phạm vi áp dụng của các Architecture Decision Records (ADR) cho hệ thống dx-vas. Bảng dưới đây liệt kê từng ADR, các service bị ảnh hưởng và vai trò/điểm nhấn triển khai đặc biệt nếu có.
| ADR | Áp dụng cho Service | Vai trò/Điểm nhấn triển khai |
|---|---|---|
| ADR-001: CI/CD | Tất cả services (core + tenant stack) | ✅ Tách pipeline theo stack; ✅ Sử dụng GitHub Actions và Environments |
| ADR-002: IaC | Hạ tầng GCP toàn hệ thống | ✅ Tách Terraform module cho core/tenant; hỗ trợ provisioning tự động |
| ADR-003: Secrets | Tất cả services | ✅ Secret per tenant (Zalo, Gmail); quản lý bằng Secret Manager & rotate riêng |
| ADR-004: Security | Tất cả services | ✅ Gateway enforce JWT trust boundary; ✅ Mỗi tenant có project/DB/network riêng |
| ADR-005: Env Config | Tất cả services | ✅ Mỗi stack có env riêng (dev, staging, prod) |
| ADR-006: Auth Strategy | Auth Service, API Gateway | ✅ Sub Auth login OTP; ✅ Master Auth Google; JWT có tenant_id |
| ADR-007: RBAC | User Service, API Gateway | ✅ RBAC phân tầng; Gateway đọc Redis theo user_id + tenant_id |
| ADR-008: Audit Logging | Tất cả services | ✅ Log hành vi có side-effect; ✅ Audit log có tenant_id, traceId |
| ADR-009: API Governance | Tất cả services phơi API | ✅ Kiểm tra OpenAPI + tagging module trong CI |
| ADR-010: Contract Testing | Tất cả services phơi API | ✅ Hợp đồng test có tenant_id, JWT context |
| ADR-011: API Error Format | Tất cả services phơi API | ✅ Dùng chung ErrorEnvelope (code/message/details) |
| ADR-012: Response Structure | Tất cả services phơi API | ✅ Chuẩn meta, data, errors; dễ monitoring |
| ADR-013: Path Naming Convention | Tất cả services phơi API | ✅ Tuân thủ RESTful, phân loại rõ tài nguyên |
| ADR-014: Zero Downtime Deployment | Tất cả services | ✅ Tách migration & deploy; rollback dễ dàng |
| ADR-015: Deployment Strategy | Core & tenant stack | ✅ Stack per tenant; Gateway chia theo domain/host |
| ADR-016: Auto Scaling | Tất cả services (Cloud Run) | ✅ Core và tenant scale độc lập; cấu hình min/max instance |
| ADR-017: Env Deploy Boundary | Tất cả services | ✅ Mỗi tenant có môi trường riêng biệt |
| ADR-018: Release Approval Policy | Core & tenant stack | ✅ Core phải duyệt thủ công; tenant có thể tự động nếu an toàn |
| ADR-019: Project Layout | GCP project toàn hệ thống | ✅ Chia project: core, tenant, monitoring, data |
| ADR-020: Cost Observability | Tất cả services | ✅ Tách chi phí per tenant; billing label theo service/group |
| ADR-021: External Observability | Tùy chọn cho tenant stack | ✅ Cho phép tích hợp Prometheus, Grafana, Datadog nếu cần |
| ADR-022: SLA, SLO, Monitoring | Tất cả services | ✅ Alert/log theo tenant_id; dashboard riêng mỗi tenant |
| ADR-023: Schema Migration Strategy | Các service có DB schema | ✅ Tuân thủ 3 bước: prepare, transition, cleanup |
| ADR-024: Data Anonymization & Retention | Dịch vụ xử lý PII | ✅ TTL per table; masking log; anonymize sandbox data |
| ADR-025: Multi-Tenant Versioning | Core & tenant stack | ✅ Cho phép mỗi tenant chọn version riêng; hỗ trợ rollout lệch phiên bản |
| ADR-026: Hard Delete Policy | Tất cả service có dữ liệu nhạy cảm | ✅ Xác định tiêu chí không được xoá vật lý; sử dụng soft delete và audit |
| ADR-027: Data Management Strategy | Toàn hệ thống | ✅ Chuẩn hoá phân loại dữ liệu, retention, purge, schema, access, bảo mật |
| ADR-028: Reporting Service Design | Reporting Service | ✅ Tách backend chuyên biệt cho báo cáo; sử dụng Data Warehouse và RBAC theo template |
| ADR-029: Report Template Schema | Reporting Service + Superadmin Webapp | ✅ Chuẩn hóa cấu trúc report_template; hỗ trợ input validation, versioning, metadata RBAC |
| ADR-030: Event Schema Governance | Tất cả services phát sự kiện (User, Auth, Notification, Adapters) | ✅ Chuẩn hóa schema sự kiện, versioned, lưu tại event registry; hỗ trợ backward compatibility |
🔎 Gợi ý sử dụng: Nếu bạn triển khai service mới, hãy rà soát bảng này để đảm bảo service tuân thủ đầy đủ các ADR tương ứng và ghi rõ mọi điểm triển khai đặc biệt (nếu có) trong Interface Contract.