DX-VAS Platform – Documentation (v2)¶

1. Vision & Scope¶

🎯 Tầm nhìn¶

Xây dựng DX-VAS Platform thành một nền tảng chuyển đổi số “tất-cả-trong-một” cho hệ sinh thái Trường Việt Anh, đáp ứng ba mục tiêu cốt lõi:

1. Kết nối liền mạch – Hợp nhất quy trình giáo dục, vận hành trường học và tương tác phụ huynh-học sinh trên một nền tảng duy nhất.
2. Mở rộng linh hoạt – Kiến trúc multi-tenant cho phép triển khai nhanh nhiều cơ sở/trường, mỗi tenant tự chủ nhưng kế thừa dịch vụ chung.
3. Bền vững & bảo mật – Áp dụng chuẩn 5★ (Service, Data, Interface, OpenAPI, Security) và tuân thủ các ADR để đảm bảo bảo mật, khả năng quan sát, và tiết kiệm chi phí dài hạn.
4. Hệ thống hỗ trợ đa dạng phương thức đăng nhập:
5. OAuth2 (Google): Dành cho giáo viên, học sinh, nhân viên – xác thực qua auth-service/master.
6. Local/OTP: Dành cho phụ huynh và trường không dùng Google Workspace – xử lý qua auth-service/sub và reCAPTCHA.

📦 Phạm vi tài liệu¶

Tài liệu này mô tả toàn bộ kiến trúc và tiêu chuẩn kỹ thuật của DX-VAS:

👥 Đối tượng độc giả¶

• Kỹ sư phát triển (backend/frontend, ML, mobile)
• DevOps & SRE – triển khai, vận hành, giám sát
• Kiến trúc sư hệ thống – thẩm định, mở rộng kiến trúc
• Quản lý sản phẩm & ban lãnh đạo – nắm bức tranh tổng quan và roadmap kỹ thuật

🚫 Ngoài phạm vi¶

• Chiến lược sư phạm, nội dung giảng dạy.
• Hướng dẫn chi tiết UI/UX cho từng portal (được tài liệu riêng).
• Báo cáo tài chính và dữ liệu PII cụ thể (chỉ nêu nguyên tắc xử lý).

Kết quả mong đợi: Sau khi đọc xong phần Vision & Scope, độc giả hiểu “tại sao” và “tài liệu này bao trùm những gì” trước khi đi sâu vào chi tiết kỹ thuật.

2. High-Level Architecture¶

2.1 Sơ đồ tổng quan (Mermaid) ^{_{Khối màu nhạt = dịch vụ “per tenant”.}}¶

flowchart TD
  %% ======= EXTERNAL =======
  subgraph ext ["🌐 External IdP & Channels"]
    GoogleOAuth(Google OAuth2)
    OTPProv(OTP Provider)
    EmailSvc(Email Gateway)
    SMSSvc(SMS Gateway)
  end

  %% ======= FRONTEND =======
  subgraph fe ["💻 Frontend Apps"]
    AdminPortal(Admin Portal)
    TeacherPortal(Teacher Portal)
    StudentPortal(Student Portal)
    ParentPortal(Parent Portal)
  end

  %% ======= CORE SERVICES =======
  subgraph core ["🔧 Core Services (Shared)"]
    APIGW(API Gateway)
    TokenSvc(Token Service)
    AuthM(Auth Master)
    UserM(User Master)
    NotifM(Notification Master)
    RedisRev[Redis
revoked_tokens cache]
    ReportSvc(Reporting Service)
    AuditLog(Audit Logging Service)
    PubSub((Pub / Sub))
  end

  %% ======= DATA PLATFORM =======
  subgraph db ["🔧 Data Platform"]
    BQ(Data Warehouse)
  end

  %% ======= MONITORING STACK =======
  subgraph mon ["📈 Monitoring Stack"]
    CloudLog(Cloud Logging)
    CloudMon(Cloud Monitoring)
    AlertSys(Alerting Rules)
  end

  %% ======= CI / CONTRACT TESTING =======
  subgraph test ["🧪 CI / Contract Testing"]
    CIPipeline(CI/CD Pipeline)
    ContractEngine(Contract Test Engine)
    MockUser(Mock: User Service)
    MockNotif(Mock: Notif Service)
    MockAuth(Mock: Auth Service)
  end

  %% ======= TENANT STACK EXAMPLE =======
  subgraph tenantA ["🏫 Tenant Stack · ABC School"]
    subgraph smsgrp ["School Management System (SMS)"]
      SMS(SMS Backend
+ MariaDB)
    end
    AuthSub(Auth Sub)
    UserSub(User Sub)
    NotifSub(Notif Sub)
  end

  %% ======= FLOWS =======
  %% Front-door
  AdminPortal -. https .-> APIGW
  TeacherPortal -. https .-> APIGW
  StudentPortal -. https .-> APIGW
  ParentPortal  -. https .-> APIGW

  %% Auth & Token
  APIGW -->|/login| AuthM
  AuthM -->|/token/issue| TokenSvc
  AuthSub -->|/token/issue| TokenSvc
  TokenSvc -- JWKS --> APIGW

  %% Revoked-token check
  APIGW -->|check revoked| RedisRev
  TokenSvc -->|sync revoked| RedisRev

  %% Core routing
  APIGW ==> UserM
  APIGW ==> NotifM
  APIGW ==> ReportSvc
  APIGW ==> AuditLog

  %% Tenant routing
  APIGW ==> AuthSub
  APIGW ==> UserSub
  APIGW ==> NotifSub
  APIGW ==> SMS

  %% Event fan-out
  UserM -- "user.*" --> PubSub
  NotifM -- "notif.*" --> PubSub
  PubSub -- "user.*" --> UserSub
  PubSub -- "notif.*" --> NotifSub

  %% ELT (simplified)
  SMS -- "ELT" --> BQ

  %% Audit Logging
  AuthM -->|log login| AuditLog
  TokenSvc -->|log issue/revoke| AuditLog
  UserM -->|log user change| AuditLog
  NotifM -->|log notif trigger| AuditLog
  ReportSvc -->|log report access| AuditLog
  AuthSub -->|log local login| AuditLog
  UserSub -->|log role update| AuditLog
  NotifSub -->|log delivery| AuditLog

  %% Monitoring Stack
  APIGW --> CloudLog
  AuthM --> CloudLog
  TokenSvc --> CloudLog
  UserM --> CloudLog
  ReportSvc --> CloudLog
  AuditLog --> CloudLog
  AuthSub --> CloudLog
  UserSub --> CloudLog
  SMS --> CloudLog
  NotifSub --> CloudLog
  CloudLog --> CloudMon
  CloudMon --> AlertSys

  %% CI/CD & Contract Testing
  CIPipeline --> ContractEngine
  ContractEngine --> MockUser
  ContractEngine --> MockNotif
  ContractEngine --> MockAuth
  MockUser -->|simulate calls| APIGW
  MockNotif -->|simulate notif| APIGW
  MockAuth -->|simulate login| APIGW

📝 Chú thích quan trọng¶

1. API Gateway xác thực JWT offline qua JWKS (RS256); chỉ gọi Token Service khi cần kiểm tra revoked token (tra Redis) hoặc các trường hợp đặc biệt.
2. Redis lưu cache revoked_tokens (TTL 15 phút). Token Service đồng bộ cache mỗi khi thu hồi token.
3. User Sub & Notif Sub là read-replica; dữ liệu đồng bộ bất đồng bộ từ các service Master qua Pub/Sub.
4. SMS là nguồn dữ liệu chính cho báo cáo; dữ liệu được trích xuất vào Data Warehouse qua đường ELT rồi tiêu thụ bởi Reporting Service.

5. Định nghĩa đường nối

6. -. https .-> : Gọi HTTPS từ frontend bên ngoài

7. --> : Gọi API đồng bộ nội bộ
8. ==> : Gọi API đồng bộ ưu tiên cao (core routing)
9. ..> : Luồng bất đồng bộ (Pub/Sub, ELT)

Sơ đồ này phản ánh đầy đủ hai Change Request: Token Service centralization và Tenant Stack/SMS simplification.

2.2 Component Groups¶

Phân tầng rõ ràng giúp:
• Isolate tenant-level logic (stack 4) khỏi vùng shared (stack 3).
• Giảm coupling – Token Service & Gateway xử lý xác thực tập trung.
• Mở rộng – thêm tenant = triển khai một SMS + ba Sub services, không ảnh hưởng Core.

3. Authentication Flow¶

3.1 Các thành phần tham gia¶

3.2 Trình tự đăng nhập & gọi API¶

sequenceDiagram
    participant FE as Frontend
    participant APIGW as API Gateway
    participant AuthM as Auth Master
    participant AuthSub as Auth Sub
    participant TokenSvc as Token Service
    participant Redis as Redis Cache

    FE->>APIGW: POST /login (Google hoặc Local/OTP)

    alt Google OAuth2
        APIGW->>AuthM: /login/google
        AuthM->>Google OAuth2: OAuth dance
        Google OAuth2-->>AuthM: id_token
    else Local / OTP
        APIGW->>AuthSub: /login/local|otp
        AuthSub->>AuthSub: verify pwd / OTP
    end

    par Lấy RBAC
        AuthM->>UserSub: GET /rbac (roles, perms)
        AuthSub->>UserSub: GET /rbac
    end

    AuthM->>TokenSvc: POST /token/issue
    AuthSub->>TokenSvc: POST /token/issue
    TokenSvc-->>AuthM: access + refresh JWT
    TokenSvc-->>AuthSub: access + refresh JWT
    AuthM-->>APIGW: 200 JWT
    AuthSub-->>APIGW: 200 JWT
    APIGW-->>FE: 200 JWT

    opt Subsequent request
        FE->>APIGW: GET /api/*
        APIGW->>APIGW: verify RS256 via JWKS
        APIGW->>Redis: jti revoked?
        alt OK
            APIGW->>Backend: forward
        else Revoked / edge
            APIGW->>TokenSvc: POST /token/introspect
            TokenSvc-->>APIGW: status
        end
    end

Chú thích sơ đồ

• JWKS là cơ chế xác thực mặc định; introspect chỉ được gọi khi Gateway cần khẳng định token chưa bị thu hồi hoặc gần hết hạn.
• Redis đóng vai trò cache danh sách token bị thu hồi; Token Service đẩy cập nhật ngay khi thu hồi (POST /token/revoke).
• Dữ liệu RBAC lấy từ User Sub để nhúng vào JWT; giúp Gateway authorize mà không phải gọi lại database.

3.3 Vòng đời JWT¶

3.4 Cấu trúc JWT (RS256)¶

sub   : user_id_global
tid   : tenant_id
roles : ["teacher"]
perms : ["grade.read", "grade.write"]
auth_provider : "google" | "local" | "otp"
jti   : e4c7...  (UUID v4)
sid   : 9ab0...  (session id)
exp   : 1717833000

3.5 Biện pháp bảo mật bổ sung¶

• Rate-limit & CAPTCHA cho Local/OTP; giới hạn OTP theo IP & user.
• Key rotation ≤ 90 ngày; JWKS cache 10 phút tại Gateway/CDN.
• Error code tuân thủ namespace.snake_case (xem ADR-011).
• mTLS cho traffic nội bộ giữa Gateway ↔ Core/Tenant services.

Phần luồng xác thực này đặt nền tảng cho mọi dịch vụ: JWT cung cấp danh tính & RBAC, còn Gateway bảo vệ biên, giữ latency thấp nhờ xác thực offline.

4. Token Service & JWT Lifecycle¶

Nguồn thiết kế – Change Request 03-cr-token-service:contentReference[oaicite:0]{index=0} & ADR-006 – Auth Strategy :contentReference[oaicite:1]{index=1}

4.1 Vai trò & Ranh giới tin cậy¶

• Token Service là micro-service duy nhất phát hành, làm mới (refresh), thu hồi (revoke) và introspect JWT cho toàn bộ platform.
• Giữ private RSA key (RS256); công khai JWKS cho API Gateway xác thực offline.
• Đồng bộ danh sách token bị thu hồi tới Redis cache → Gateway truy vấn cục bộ, chỉ gọi /token/introspect khi cache miss hoặc token sắp hết hạn.

4.2 API Endpoints¶

4.3 Key Management 🔑¶

• Thuật toán RS256; giữ 2 key hoạt động song song (kid=current|next).
• Luân phiên khóa tối đa 90 ngày/lần; triển khai bằng Cloud KMS + GitOps pipeline :contentReference[oaicite:2]{index=2}.
• JWKS có Cache-Control: public, max-age=600 – Gateway tải lại tự động mỗi 10 phút.

4.4 Cấu trúc JWT & TTL¶

Refresh token: TTL 14 ngày, lưu bảng auth_sessions.

4.5 Thu hồi token & Redis Cache¶

flowchart LR
  TokenSvc -- "sync revoked (jti)" --> Redis[(Redis
revoked_tokens)]
  APIGW -- "check jti" --> Redis
  APIGW -- "introspect (rare)" --> TokenSvc

• Redis TTL 15 phút – đủ nhanh để propagation nhưng không quá tải network.
• Gateway chỉ “rơi về” /introspect khi cache miss hoặc cần kiểm tra chi tiết phiên (sid).

4.6 Event Publishing 📡¶

• Phát sự kiện token.issued & token.revoked lên Pub/Sub → Audit-Logging & dashboard “token-per-minute”, “revoked-rate”.
• Sự kiện tuân thủ schema token.{issued|revoked}.v1 (tham khảo ADR-030 – Event Schema Governance).

4.7 Error Codes¶

• Tất cả response lỗi bao bọc theo ErrorEnvelope (ADR-011).
• Quy ước namespace.snake_case, ví dụ token.expired, session.not_found – quản lý trong docs/standards/error-codes.md.

4.8 KPI & Monitoring¶

Tóm tắt – Đặt Token Service làm “nhà máy” JWT giúp đảm bảo bảo mật, giảm độ trễ và đơn giản hoá quản lý vòng đời token cho toàn hệ thống.

5. Tenant Stack & School Management System (SMS)¶

5.1 Khái niệm Tenant Stack¶

Mỗi tenant (trường) có một stack dịch vụ biệt lập, triển khai trên GCP project riêng theo chiến lược dx-vas-tenant-<name> (xem ADR-015, ADR-019) .
Stack bao gồm:

5.2 Luồng chính¶

1. Portal gọi API Gateway kèm header X-Tenant-ID.
2. Gateway định tuyến /sms/** tới SMS của tenant; chèn thêm header X-User-ID, X-Permissions để RBAC hoạt động.
3. SMS phục vụ nghiệp vụ trường (điểm danh, học phí, LMS, v.v.).
4. User-sub & Notif-sub nhận sự kiện từ User-master / Notif-master qua Pub/Sub → cập nhật DB cục bộ.
5. ELT pipeline trích xuất dữ liệu SMS → Data Warehouse; Reporting Service truy vấn DW tạo dashboard đa-tenant .

5.3 Lợi ích kiến trúc¶

• Đơn giản hoá vận hành – Loại bỏ ba adapter, giảm số container per tenant ~ 60 %.
• On-boarding nhanh – Thêm tenant = deploy một container SMS + 3 sub services (Terraform module “tenant-stack”).
• Trải nghiệm nhất quán – 4 portal chia sẻ UI/UX và SSO, giảm chi phí hỗ trợ người dùng :contentReference[oaicite:3]{index=3}.
• Tách billing & bảo mật – Project riêng, log/alert dán nhãn tenant_id (ADR-022) :contentReference[oaicite:4]{index=4}.

5.4 Chuẩn triển khai & versioning¶

• Docker image SMS gắn thẻ vX.Y.Z; thông tin stack_version lưu trong secret mỗi tenant (ADR-025).
• CI/CD hỗ trợ rollout so le; Superadmin Webapp quản lý mapping tenant ↔ version.
• Pipeline terraform + github actions tự động tạo project, DNS, secrets, certs theo template (ADR-015).

TL;DR – Tenant Stack mới gói gọn nghiệp vụ trường trong một SMS, liên kết an toàn vào khung xác thực & quan sát chung, giúp dx-vas “on-board một trường mới trong vài giờ thay vì vài ngày”.

6. Core & Business Services¶

Mục tiêu – Liệt kê các dịch vụ chạy dùng chung (Core) và dịch vụ nghiệp vụ (Business), kèm đường dẫn tài liệu kỹ thuật (ADR / SDD) để tra cứu chi tiết.

6.1 Core Services (Shared)¶

6.2 Business Services (per tenant)¶

Các adapter cũ crm-adapter, sis-adapter, lms-adapter đã ngưng – thay thế hoàn toàn bởi SMS.

6.3 Cross-cutting & Infrastructure¶

6.4 Ưu tiên phát triển (Roadmap)¶

1. User Service Master – SDD “Legendary++” (đang viết) → unlock RBAC advance.
2. SMS OpenAPI → chuẩn hoá contract, bật code-gen client cho portal.
3. Audit-Logging v2 → blockchain timestamp & zero-trust export.
4. Cost Observability automation → chargeback dòng tiền per tenant.
5. External Observability SLA dashboard → public status.truongvietanh.edu.vn.

Ghi nhớ: Mọi dịch vụ mới phải tuân thủ bộ 5★ standards và được ghi lại dưới dạng ADR + SDD trước khi triển khai.

7. Observability & Security¶

Mục tiêu – Đảm bảo tính minh bạch (observability) cho vận hành và tính an toàn (security) cho dữ liệu/nguồn lực của toàn hệ thống DX-VAS. Các nguyên tắc bên dưới lấy căn cứ từ:
• ADR-004 – Security · ADR-022 – SLO & Monitoring · ADR-020 – Cost Observability · ADR-021 – External Observability · ADR-011 – API Error Format · ADR-003 – Secrets

7.1 Observability 🔍¶

7.1.1 Revoked-Token Hit Ratio¶

• Metric: revoked_token_cache_hit_ratio (Gateway).
• Mục tiêu: > 95 %. Alert nếu < 90 % liên tục 10 phút → điều tra Redis / sync Token Service.

7.2 Security 🛡️¶

7.2.1 Key Rotation & JWKS¶

• Rotation job: Cloud Build pipeline tạo key mới, gắn kid=next, deploy Token Service → sau 24 h xoá key cũ.
• Fallback: Nếu JWKS fetch lỗi > 3 lần, Gateway cứng chặn traffic (fail-closed).

7.2.2 Pen-test & Compliance¶

• Quarterly penetration test + SAST/DAST; kết quả lưu requests/04-cr-tenant-system.md phụ lục bảo mật.
• Tuân thủ GDPR cho dữ liệu học sinh & phụ huynh; dữ liệu PII được ẩn danh theo ADR-024.

7.3 Alert Routing & Escalation¶

Nguyên tắc vàng: “Bạn không thể bảo vệ điều bạn không quan sát được.” – Observability & Security phải song hành để DX-VAS vận hành tin cậy, tuân thủ, và tối ưu chi phí.

8. CI/CD & Deployment¶

Cơ chế CI/CD của DX-VAS áp dụng triệt để triết lý “Everything-as-Code” và GitOps, bảo đảm triển khai Zero-Downtime theo ADR-014, ủy quyền phát hành rõ ràng theo ADR-018, và hạ tầng bất biến theo ADR-002 & ADR-015.

8.1 Nhánh mã & Chính sách PR¶

8.2 Pipeline CI (GitHub Actions)¶

1. Checkout + Cache
   actions/checkout@v4 → thiết lập cache pnpm / poetry.
2. Static Analysis & SCA
3. SAST (SonarQube) – fail nếu critical.
4. Dependency CVE (Dependabot).
5. Unit & Contract Test
6. Python/PyTest + Coverage ≥ 85 %.
7. Contract-Testing theo ADR-010 (PactFlow).
8. Build & SBOM
9. Docker multi-arch (linux/amd64, arm64).
10. Tạo SBOM CycloneDX; push Artifact Registry.
11. Image Scan (GCP Container Analysis) – block CVE “High”.
12. Publish
13. Tag main ⇒ vX.Y.Z (semantic-release).
14. Upload Helm chart → Helm Repo.

8.3 Pipeline CD (Argo CD + Terraform Cloud)¶

8.4 Zero-Downtime & Chiến lược Triển khai¶

• Canary Rollout (default) – 10 → 25 → 50 → 100 %.
• Blue-Green – dùng cho migration DB lớn (flag strategy=bluegreen).
• Schema Migration – GitOps-DB chạy flyway job → version-controlled (ADR-023).
• Auto-Scaling – HPA theo p95 latency & CPU (ADR-016).
• Env Deploy Boundary – Staging và Prod tách VPC, project (GCP) (ADR-017).

8.5 Tenant On-Boarding Pipeline¶

flowchart LR
  A[Create Tenant PR] --> B[Terraform Cloud
plan/apply
project, VPC, MariaDB]
  B --> C[DNS & Cert bot]
  C --> D[Argo CD
sync tenant stack
SMS + Sub services]
  D --> E["API Gateway auto-route
/sms/{tenant}"]
  E --> F[Smoke Test suite]

• Thời gian: \~ 25 phút/tenant (99-percentile).
• Output: Slack thông báo “Tenant abc ready 🎉”.

8.6 Quản lý Cấu hình & Secrets¶

• ADR-005 – cấu hình qua ConfigMap/Secret phân tách env và tenant.
• ADR-003 – Secrets (RSA key, OTP provider) lưu GCP Secret Manager với rotation cron.

8.7 Kiểm soát Chi phí & Carbon¶

• FinOps Job chạy mỗi đêm: truy vấn Cloud Billing API → BigQuery → Grafana “Cost/Tenant/Service”.
• Cảnh báo Slack khi chi phí chệch > 20 % so với trung bình 7 ngày.

8.8 Sơ đồ luồng CI/CD tổng quan¶

graph TB
  Dev -->|PR| GitHub
  GitHub -->|CI pass| ArtifactRegistry
  ArtifactRegistry -->|tag main| ArgoCD
  ArgoCD -->|sync| Staging
  Staging -->|integration ok| ArgoGate[Release Approval]
  ArgoGate -->|canary| ProdCanary
  ProdCanary -->|auto promote| Prod
  Prod -->|metrics| Grafana

Nguồn tham chiếu: • ADR-001 – CI/CD · ADR-014 – Zero-Downtime · ADR-015 – Deployment Strategy · ADR-018 – Release Approval Policy • Terraform module tenant-stack · Helm chart dx-vas-core.

9. Data & Reporting¶

Phần này trình bày cách DX-VAS thu thập, lưu trữ, quản trị và khai thác dữ liệu — từ SMS của từng tenant, qua ELT pipeline, vào Data Warehouse, và cuối cùng hiển thị báo cáo. Các quyết định thiết kế dựa trên:
• ADR-023 Schema Migration :contentReference[oaicite:0]{index=0} · ADR-024 Data Anonymization & Retention :contentReference[oaicite:1]{index=1} · ADR-026 Hard Delete Policy :contentReference[oaicite:2]{index=2} · ADR-027 Data Management Strategy :contentReference[oaicite:3]{index=3} · ADR-028 Reporting Architecture :contentReference[oaicite:4]{index=4} · ADR-029 Report Template Schema :contentReference[oaicite:5]{index=5} · ADR-030 Event Schema Governance :contentReference[oaicite:6]{index=6}

9.1 Nguồn dữ liệu gốc (Source-of-Truth)¶

9.2 ELT Pipeline (near-real-time)¶

flowchart LR
  SMS_MariaDB((MariaDB)) -->|Debezium
CDC| DataLake[(Cloud Storage
Parquet Staging)]
  DataLake -->|Dataflow
transform| BQ[BigQuery
Data Warehouse]
  PubSub((Pub/Sub)) -->|Stream
Dataflow| BQ

• Extract: Debezium CDC dump insert/update/delete mỗi tenant vào Cloud Storage (Parquet).
• Load: Scheduled Dataflow job nạp incremental vào BigQuery staging.
• Transform: dbt chạy nightly tạo Data Mart (fct_enrolment, dim_student, v.v.).
• Latency mục tiêu: < 5 phút cho sự kiện, < 30 phút cho batch.

9.3 Thiết kế Data Warehouse¶

Retention: Raw = 30 ngày (xem ADR-024); Mart giữ 5 năm, bản ghi PII được ẩn danh (hash + salt).

9.4 Báo cáo & BI¶

• Reporting Service đọc Mart, sinh dashboard multi-tenant (Grafana, Superset).
• Mỗi báo cáo tuân thủ template JSON Schema v1.0 (định nghĩa tại ADR-029).
• Public API /reports/:id/export trả về CSV / Parquet; Gateway gắn header X-Tenant-ID.

9.5 Data Governance & Compliance¶

9.6 Quan sát & SLA dữ liệu¶

9.7 Tích hợp Event Schema Governance¶

• Mọi sự kiện *.*.v1 phải đăng ký schema Avro trong Schema Registry (ADR-030).
• Pipeline Dataflow validate schema ID trước khi nạp vào BigQuery; sai lệch → gửi error.code=data.schema_mismatch.

Nền tảng dữ liệu DX-VAS được dựng để dễ mở rộng, tuân thủ (GDPR) và tối ưu chi phí — bảo đảm mỗi tenant truy cập báo cáo kịp thời mà không ảnh hưởng dữ liệu tenant khác.

10. ADR & CR Index¶

10.1 Architecture Decision Records (ADR)¶

10.2 Change Requests (CR)¶

Ghi chú:
ADR = quyết định kiến trúc lâu dài; CR = thay đổi lớn được phê duyệt sau giai đoạn thiết kế chi tiết.
Mọi PR mới thay đổi kiến trúc phải kèm ADR / CR tương ứng trước khi merge vào main.

11. Standards & Conventions¶

Mục đích – Bảo đảm mọi thành phần của DX-VAS tuân thủ một bộ quy ước thống nhất về thiết kế dịch vụ, dữ liệu, API, mã lỗi, versioning và style code, giúp giảm sai sót, dễ bảo trì và đồng nhất trải nghiệm.

11.1 Bộ tiêu chuẩn “5★” (5-Star Standards)¶

Check-list CI: PR nào chứa file IC/OpenAPI sẽ chạy linter 5★ – fail nếu vi phạm.

11.2 Error Codes & Envelope¶

11.3 Naming & Versioning¶

11.4 Style Guide (Code & Docs)¶

Docs-as-Code: Mọi tài liệu (ADR, SDD, IC) lưu trong Git, PR review = code.

11.5 Kiểm tra tuân thủ (CI Checks)¶

1. 5★ Linter – validate OpenAPI & IC.
2. Schema Registry – event Avro ID phải khớp ADR-030.
3. SBOM & CVE Scan – block CVE High/critical.
4. Error code validator – compare error.code xuất hiện trong OpenAPI với danh sách chuẩn.

11.6 Ngoại lệ & Quy trình phê duyệt¶

• Ngoại lệ hiếm (P0 deadline, legacy) ⇒ tạo RFC kèm justification, gắn label standards-waiver, review bởi Architecture Board.
• Sau 60 ngày, waiver hết hạn; service phải retrofit về đúng chuẩn.

Nhắc lại – “Consistency is speed.” Tuân thủ bộ chuẩn trên giúp đội ngũ DX-VAS ship nhanh hơn mà không đánh đổi chất lượng hoặc an toàn.

12. Appendix¶

12.1 Thuật ngữ (Glossary)¶

12.2 Danh bạ (Contacts)¶

(Địa chỉ email/điện thoại chỉ là ví dụ; cập nhật khi áp dụng thực tế.)

12.3 Changelog (Tóm tắt)¶

Lưu ý: Changelog chỉ ghi thay đổi ở cấp kiến trúc/tài liệu. Thay đổi code chi tiết xem Git commit history.

12.4 Tài liệu bổ sung¶

DX-VAS Platform Documentation v2.
Phát hành theo giấy phép nội bộ; không sao chép khi chưa có sự đồng ý bằng văn bản.