📘 Thiết kế chi tiết Auth Service - Sub¶

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

auth-service/sub là dịch vụ xác thực được thiết kế theo mô hình per-tenant deployment, phục vụ riêng biệt cho từng tenant (trường học) trong hệ thống dx-vas. Mỗi tenant có một instance riêng, độc lập về cơ sở dữ liệu, cấu hình, và lifecycle vận hành.

Dịch vụ này đảm nhiệm xác thực đầu vào cho người dùng cuối (student, teacher, employee) thuộc tenant tương ứng, thông qua các phương thức OTP và Local Login.

✅ Chức năng chính¶

🚫 Không thuộc phạm vi¶

🧩 Vai trò trong kiến trúc tổng thể¶

flowchart TD
    FE[Frontend]
    GW[API Gateway]
    AS[Auth Service Sub]
    TS[Token Service]
    US[User Service]
    AUD[Audit Logging]

    FE --> GW
    GW --> AS
    AS --> TS
    AS --> US
    AS --> AUD

• api-gateway định tuyến request login đến auth-service/sub dựa trên header X-Tenant-ID
• auth-service/sub xác thực thông tin, gọi token-service, gửi sự kiện audit, đồng bộ user nếu cần
• Mọi token, permission, RBAC đều được quản lý bên ngoài auth-service/sub, đảm bảo service giữ vai trò nhẹ, tập trung, có thể scale độc lập

🧪 Tóm tắt vai trò¶

💡 auth-service/sub không xử lý xác thực liên tenant (như admin login từ hệ thống khác); các luồng đó được định tuyến đến auth-service/master.

2. 🌐 Thiết kế API chi tiết (Interface Contract)¶

Auth Service (Sub) cung cấp các API xác thực OTP và Local login, được định nghĩa rõ ràng trong interface-contract.md. Các API tuân thủ chuẩn thiết kế chung toàn hệ thống:

• Cấu trúc response theo SuccessEnvelope / ErrorEnvelope (ADR-012, ADR-011)
• Có trường meta đi kèm mọi response
• Được bảo vệ bằng RBAC và điều kiện động x-condition (ADR-007)
• Truy vết theo X-Trace-ID, audit qua audit-logging-service

🔐 Danh sách endpoint chính¶

Auth Service - Sub cung cấp 4 endpoint chính phục vụ xác thực người dùng và quản lý phiên đăng nhập. Thiết kế tuân thủ chuẩn OpenAPI và thống nhất với các tài liệu interface-contract và mô hình dữ liệu.

📌 Lưu ý:

• API /auth/login sử dụng oneOf để phân biệt giữa OTP và Local login thông qua login_type, không tách thành các route riêng như /auth/otp/request hay /auth/local.
• Tất cả các API đều sử dụng X-Tenant-ID trong x-condition để đảm bảo phân vùng tenant.
• Header Authorization: Bearer <token> áp dụng cho các API bảo vệ, trừ POST /auth/login.

📦 Cấu trúc request/response¶

✅ Request Schema¶

• LoginRequest: oneOf 2 loại:

• LoginRequestOTP: { login_type: otp, phone_number, otp_code }

• LoginRequestLocal: { login_type: local, username, password (writeOnly) }
• LogoutRequest: { reason: string } (tuỳ chọn)

✅ Response Schema¶

• TokenEnvelope: { access_token, refresh_token, expires_in, session_id, token_type }
• SessionOut: { session_id, user_id, auth_method, created_at, revoked_at, device_type, ip_address, location, user_agent, status }
• PaginatedSessions: { meta: ResponseMeta, data: [SessionOut] }
• ErrorEnvelope: { error: { code, message, data }, meta: ResponseMeta }
• ResponseMeta: { request_id, timestamp, pagination? }

🎯 Mã lỗi chuẩn¶

📌 Tất cả schema và mã lỗi đều tuân thủ định nghĩa trong components/schemas và components/responses của openapi.yaml, đồng thời thống nhất với data-model.md.

🧠 Truyền thông tin session (session_metadata)¶

Mỗi lần xác thực thành công, dịch vụ sẽ thu thập metadata liên quan đến phiên đăng nhập và gửi kèm trong yêu cầu đến token-service:

{
  "user_id": "abc123",
  "login_method": "otp",
  "session_metadata": {
    "ip": "192.168.1.1",
    "user_agent": "Mozilla/5.0",
    "device": "Android; Pixel 6"
  }
}

Thông tin này sẽ được ghi lại tại bảng auth_sessions và hiển thị trong hệ thống quản trị.

📌 Lưu ý triển khai¶

• Tất cả API đều định danh tenant thông qua header X-Tenant-ID
• RBAC được kiểm tra bởi api-gateway, không phải trong auth-service/sub
• Các API không yêu cầu xác thực đầu vào (vì là entrypoint của login) nhưng được kiểm soát qua rate-limit, captcha, otp max-attempt
• Có thể test API thông qua Swagger UI tích hợp nội bộ (/docs/)

👉 Xem chi tiết: Interface Contract.md – OpenAPI

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

Auth Service (Sub) không lưu trữ thông tin người dùng hay token, nhưng vẫn duy trì một số dữ liệu liên quan đến phiên đăng nhập và hỗ trợ xác thực.

🔐 Bảng auth_sessions (PostgreSQL)¶

Lưu thông tin phiên đăng nhập sau mỗi lần xác thực thành công.
Dữ liệu này phục vụ mục đích kiểm toán, phân tích hành vi và hỗ trợ thu hồi phiên (logout).

📌 Trường session_metadata thường chứa:

{
  "ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0",
  "device": "Android; Pixel 6",
  "location": "HCMC"
}

🧊 Cache revoked_tokens (Redis)¶

Để đảm bảo hiệu quả khi xác thực JWT tại api-gateway, Auth Service Sub hỗ trợ ghi token bị thu hồi vào Redis (dùng chung cluster Redis của hệ thống).

• Key format: revoked:{token_id}
• TTL: bằng thời hạn còn lại của JWT
• Giá trị: JSON gồm revoked_at, user_id, reason

Ví dụ:

revoked:3fa85f64-5717-4562-b3fc-2c963f66afa6
→
{
  "revoked_at": "2025-06-13T10:03:00Z",
  "user_id": "abc123",
  "reason": "manual_logout"
}

🔄 Event Log (Pub/Sub)¶

Mỗi sự kiện xác thực đều được phát đi theo chuẩn schema adr-030, phục vụ hệ thống audit-log và các adapter bên ngoài.

✨ Ghi chú¶

• Dữ liệu được partition theo tenant_id để phục vụ triển khai đa tenant hiệu quả
• Chỉ lưu session sau khi token được cấp từ token-service
• Không lưu token plaintext — chỉ lưu metadata và mapping session

Xem thêm các chi tiết kỹ thuật như indexing, constraints, ENUMs, retention policy và chiến lược kiểm thử dữ liệu tại Data Model

4. 🔄 Luồng xử lý nghiệp vụ chính¶

Dưới đây là mô tả chi tiết các luồng xử lý chính của auth-service/sub, bao gồm: đăng nhập bằng OTP, đăng nhập Local, logout và đồng bộ người dùng. Tất cả đều diễn ra trong ngữ cảnh của từng tenant (per-tenant).

🔐 Luồng 1: Đăng nhập bằng OTP¶

sequenceDiagram
    participant FE as Frontend
    participant GW as API Gateway
    participant AS as Auth Sub
    participant TS as Token Service
    participant US as User Service
    participant AL as Audit Logging

    FE->>GW: POST /auth/otp/verify
    GW->>AS: Forward request + headers
    AS->>AS: Kiểm tra mã OTP hợp lệ
    AS->>TS: Gửi yêu cầu cấp token + session_metadata
    TS-->>AS: Trả về access_token + refresh_token
    AS->>US: Gửi yêu cầu đồng bộ user (nếu chưa có)
    AS->>AL: Gửi sự kiện `auth.token.issued`
    AS-->>GW: Trả JWT cho FE

📝 Ghi chú: - Nếu OTP sai → trả lỗi auth.otp.invalid (namespace auth, theo ErrorEnvelope) - Nếu chưa có user → gửi yêu cầu POST user.sync tới user-service (async) - Session được ghi lại tại bảng auth_sessions sau khi nhận token

👤 Luồng 2: Đăng nhập Local (username/password)¶

• Tương tự luồng OTP, nhưng thay kiểm tra OTP bằng xác thực credential:

  - Kiểm tra username/password
  - Gọi token-service
  - Ghi session
  - Audit log
  - Đồng bộ user nếu chưa tồn tại
  

📌 Yêu cầu dùng chuẩn bcrypt cho password hash; không lưu plaintext hoặc so sánh trực tiếp.

🔁 Luồng 3: Logout (Thu hồi phiên)¶

sequenceDiagram
    participant FE
    participant GW
    participant AS
    participant TS
    participant AL

    FE->>GW: POST /auth/logout (kèm JWT)
    GW->>AS: Forward token
    AS->>TS: Gọi token-service thu hồi token
    AS->>AL: Ghi sự kiện `auth.token.revoked`
    AS-->>GW: Trả success envelope

Ghi chú: - Token bị thu hồi sẽ được đẩy vào Redis (revoked_tokens) với TTL tương ứng - Dữ liệu thu hồi có thể dùng để kiểm tra chéo ở api-gateway

🔄 Luồng 4: Đồng bộ user¶

• Nếu token được cấp hợp lệ nhưng user_id chưa có trong tenant DB, auth-service/sub sẽ:
• Gửi request đồng bộ async tới user-service
• Ghi log user.sync.triggered
• Cho phép hoàn tất phiên xác thực, không chặn người dùng

✅ Mô hình phân tầng¶

👉 Các luồng này tuân thủ nguyên tắc stateless, có thể mở rộng theo từng tenant, và dễ dàng theo dõi qua audit log + trace ID từ api-gateway.

5. 📣 Tương tác với các Service khác & Luồng sự kiện¶

auth-service/sub không hoạt động độc lập mà tương tác chặt chẽ với các thành phần khác trong hệ thống thông qua API nội bộ và cơ chế sự kiện bất đồng bộ (Pub/Sub). Mục tiêu là đảm bảo xác thực an toàn, thống nhất token lifecycle, và ghi nhận đầy đủ dấu vết phục vụ kiểm toán & phân tích.

🔗 Giao tiếp nội bộ (Internal API Calls)¶

📌 Tất cả các call đều có gắn X-Tenant-ID, X-Trace-ID, và truyền metadata như IP, thiết bị, phương thức login.

📣 Luồng sự kiện bất đồng bộ (Pub/Sub)¶

Sau mỗi hành động xác thực quan trọng, auth-service/sub phát sự kiện đến hệ thống Pub/Sub của tenant tương ứng.

🔄 Danh sách sự kiện phát hành¶

📋 Ví dụ payload auth.token.issued¶

{
  "event": "auth.token.issued",
  "timestamp": "2025-06-13T10:00:00Z",
  "tenant_id": "school-abc",
  "session_id": "abc123",
  "user_id": "user-001",
  "login_method": "otp",
  "session_metadata": {
    "ip": "192.168.1.1",
    "user_agent": "Mozilla/5.0",
    "device": "iPhone 12"
  }
}

🎯 Nguyên tắc thiết kế tích hợp¶

• Tất cả các sự kiện tuân theo schema chuẩn định nghĩa trong adr-030-event-schema-governance.md
• Không có dữ liệu nhạy cảm (mật khẩu, OTP) được truyền trong payload
• Mỗi sự kiện đều chứa tenant_id và trace_id để phục vụ việc theo dõi chéo hệ thống
• Các hệ thống tiêu thụ sự kiện (CRM, LMS, Dashboard) sẽ dựa vào các sự kiện này để trigger hành vi phù hợp (ví dụ: tạo học sinh mới sau login)

👉 Việc triển khai Pub/Sub là bắt buộc để đảm bảo hệ thống có khả năng observability toàn diện, scale độc lập và dễ dàng tích hợp với các module kinh doanh khác.

6. 🔐 Bảo mật & Phân quyền¶

auth-service/sub là entrypoint xác thực người dùng cuối (student, teacher, employee) trong từng tenant. Mặc dù bản thân dịch vụ không trực tiếp kiểm tra phân quyền, nó vẫn tuân thủ nghiêm ngặt các yêu cầu bảo mật và phối hợp chặt chẽ với tầng api-gateway để thực thi RBAC & các chính sách bảo vệ hệ thống.

🔐 Cơ chế bảo mật chính¶

🔐 Phân quyền và RBAC (áp dụng gián tiếp)¶

Mặc dù auth-service/sub không tự phân quyền, nó có trách nhiệm gắn permission code và x-condition phù hợp để api-gateway kiểm tra trước khi gọi.

• Mỗi endpoint được annotate bởi:
• x-required-permission: Mã quyền logic (vd: auth.otp.verify)
• x-condition: Điều kiện động dựa trên request (tenant_id, login_method, ...)

/auth/otp/verify:
  post:
    summary: Xác thực OTP
    x-required-permission: auth.otp.verify
    x-condition:
      tenant_id: "{{X-Tenant-ID}}"
      login_method: "otp"

Các giá trị x-condition này sẽ được api-gateway sử dụng để tra bảng role-permission trong Redis và quyết định có forward hay không.

🔒 Token & session lifecycle¶

🧯 Chính sách bảo vệ API¶

👉 Trong môi trường production, nên sử dụng mTLS hoặc HMAC signature để xác thực giữa các service nội bộ (auth-service/sub → token-service, user-service...).

Ngoài ra, cần liên tục monitor các sự kiện bất thường như: - OTP gửi quá mức - login_failed tăng đột biến - user chưa tồn tại sau login → dấu hiệu tấn công thăm dò

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

auth-service/sub được thiết kế theo mô hình per-tenant deployment, mỗi tenant chạy một instance độc lập với cấu hình riêng biệt, đảm bảo cô lập dữ liệu, khả năng tùy chỉnh linh hoạt và dễ mở rộng. Dịch vụ hoạt động theo kiến trúc stateless và phụ thuộc vào một số dịch vụ lõi trong hệ sinh thái.

🔧 Cấu hình môi trường (ENV)¶

Tất cả biến môi trường phải được quản lý qua ConfigMap và Secret (Xem adr-005 và adr-003).

🔐 Secrets bắt buộc¶

Secrets được mount qua Kubernetes Secret hoặc Vault Agent Sidecar, tuyệt đối không commit vào mã nguồn.

🧩 Phụ thuộc vào các dịch vụ khác¶

Tất cả service đều dùng chung hệ thống service discovery nội bộ thông qua tên DNS Kubernetes.

🗂 Tách biệt cấu hình theo tenant¶

Cấu hình có thể được quản lý qua các khối values.yaml riêng biệt trong Helm Chart hoặc file .env theo folder:

env/
├── school-abc/
│   ├── .env
│   └── secrets.env
├── school-xyz/
│   ├── .env
│   └── secrets.env

⚠️ Các ràng buộc¶

• Không được hard-code endpoint hoặc secret trong mã nguồn
• Mọi thông tin nhạy cảm đều cần được quản lý theo adr-003-secrets.md
• Nếu triển khai multi-tenant trên cùng 1 instance (không khuyến khích), cần dùng X-Tenant-ID để định tuyến và phân vùng session — tuy nhiên điều này làm tăng độ phức tạp bảo mật và quan sát

👉 Đảm bảo mọi cấu hình đều có kiểm tra tính hợp lệ khi service khởi động, sử dụng thư viện cấu hình chuẩn (VD: pydantic.BaseSettings, dynaconf, dotenv, v.v.)

8. 🧪 Chiến lược kiểm thử¶

auth-service/sub đóng vai trò cốt lõi trong quá trình xác thực người dùng đầu vào hệ thống. Do đó, cần triển khai chiến lược kiểm thử toàn diện từ đơn vị (unit) đến tích hợp hệ thống (E2E), bao gồm cả kiểm thử hợp đồng với các service liên kết như token-service, user-service, notification-service.

🔬 8.1. Unit Tests¶

✅ Toàn bộ unit test được chạy độc lập với các service khác.

🔗 8.2. Contract Tests¶

Tuân thủ theo adr-010, tất cả các HTTP call outbound đều có hợp đồng rõ ràng và được kiểm thử contract định kỳ.

🔒 Các contract test được trigger tự động trong CI mỗi khi có thay đổi API liên quan.

🧪 8.3. Integration Tests¶

Mô phỏng toàn bộ flow xác thực giữa các service.

📦 Dùng docker-compose hoặc test container mock để chạy test môi trường staging.

🌐 8.4. E2E Tests (qua API Gateway)¶

• Gửi request từ frontend giả lập qua api-gateway
• Test rate-limit, RBAC, header X-Tenant-ID, trace ID
• Kiểm tra toàn chuỗi: login → get token → logout → revoked check

💡 Các E2E test quan trọng nhất sẽ được đưa vào smoke test suite khi rollout mỗi tenant mới.

📈 8.5. Coverage & CI/CD¶

• Yêu cầu coverage > 90% cho domain logic
• Có các tệp test độc lập theo từng tầng: tests/unit/, tests/integration/, tests/contracts/
• Các test được chạy trên pipeline GitLab CI hoặc GitHub Actions, có kiểm tra rollback nếu fail

🧩 Tổng hợp mục tiêu kiểm thử¶

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

auth-service/sub là entrypoint xác thực quan trọng, cần được quan sát và giám sát toàn diện để đảm bảo độ tin cậy, bảo mật và hiệu suất. Chiến lược observability của service tuân thủ triết lý “4 trụ cột”:

• Logging (Ghi log chuẩn và có cấu trúc)
• Metrics (Đo lường định lượng, dùng cho cảnh báo)
• Tracing (Theo dõi chuỗi request xuyên service)
• Audit Logging (Lưu dấu vết hành vi người dùng)

🪵 9.1. Logging (Structured Log)¶

• Mọi log phải ở định dạng JSON để có thể phân tích tập trung
• Log phải bao gồm ít nhất các trường sau:

{
  "timestamp": "2025-06-13T10:00:00Z",
  "level": "INFO",
  "tenant_id": "school-abc",
  "trace_id": "abc123",
  "module": "otp_login",
  "message": "OTP verified successfully",
  "user_id": "user-xyz"
}

📍 Dùng loguru, structlog hoặc tương đương, log tập trung qua Fluent Bit → Loki / ELK.

📊 9.2. Metrics (Prometheus)¶

Dịch vụ expose /metrics theo chuẩn Prometheus, gồm các metric chính:

🚨 Cảnh báo đi kèm (Alert Rules): - Tăng đột biến login_failed_total - Số OTP gửi vượt ngưỡng trong thời gian ngắn - Token issue latency vượt SLA (>300ms)

🔍 9.3. Tracing (Distributed Trace)¶

• Tích hợp OpenTelemetry để trace toàn bộ chuỗi login
• Mỗi request đều đính kèm:
• X-Trace-ID: UUID toàn chuỗi
• X-Span-ID: ID riêng cho mỗi dịch vụ
• Trace gửi về hệ thống như Jaeger, Tempo, Honeycomb

Ví dụ trace:

FE → Gateway → AuthSub → TokenService → UserService → AuditLog

📚 9.4. Audit Logging¶

Tuân theo adr-008, mọi hành vi xác thực đều ghi log vào hệ thống audit-logging-service.

⚠️ Audit log có thể được xuất sang file riêng biệt hoặc stream qua Pub/Sub tùy theo thiết lập tenant.

🧪 9.5. Observability by tenant¶

• Mỗi tenant có thể có dashboard Prometheus/Grafana riêng
• Mọi alert rule đều gắn tenant_id để tách biệt kênh cảnh báo
• Các dashboard gồm:
• Tỉ lệ thành công OTP/Login
• Số lượng login theo ngày
• Thời gian trung bình cấp token

👉 Đảm bảo observability không chỉ phục vụ vận hành, mà còn là một phần quan trọng để đánh giá bảo mật và chất lượng trải nghiệm người dùng.

10. 🚀 Độ tin cậy & Phục hồi¶

auth-service/sub được thiết kế để đạt độ tin cậy cao trong môi trường multi-tenant, đảm bảo dịch vụ luôn sẵn sàng phục vụ người dùng đầu cuối như học sinh, giáo viên và nhân viên trong các trường thành viên của hệ thống VAS.

🧱 10.1. Stateless và Scale ngang¶

• Dịch vụ hoàn toàn stateless – mọi trạng thái người dùng (token, session) được lưu tại Redis hoặc PostgreSQL
• Hỗ trợ horizontal scaling thông qua autoscaler (HPA), phù hợp với mô hình burst load như đăng nhập giờ cao điểm

♻️ 10.2. Retry & Idempotency¶

🧪 Các API gọi outbound phải idempotent, đặc biệt là user.sync, token.issue, đảm bảo không tạo session trùng nếu frontend resend request.

💥 10.3. Giới hạn lỗi & cô lập tenant¶

• Nếu một tenant gặp lỗi (ví dụ cấu hình sai Redis), chỉ tenant đó bị ảnh hưởng → không lan sang tenant khác
• Mỗi tenant chạy instance riêng hoặc phân vùng theo namespace

🛠 10.4. Circuit Breaker & Timeout¶

• Circuit breaker bật nếu tỷ lệ lỗi vượt 20% trong 1 phút cho từng external service
• Timeout tiêu chuẩn:
• token-service: 3s
• user-service: 2s
• notification-service: 2s
• Nếu quá timeout → ghi log và trả lỗi chuẩn auth.external_timeout (ErrorEnvelope)

⏱ 10.5. SLA/SLO¶

Các chỉ số này được monitor qua Prometheus, và báo cáo theo tenant.

🚨 10.6. Rollback & Zero Downtime¶

• Tuân thủ adr-014: sử dụng rolling update, không xóa container cũ cho đến khi container mới sẵn sàng
• Sử dụng readinessProbe, livenessProbe để đảm bảo chỉ phục vụ request khi sẵn sàng
• Nếu phiên bản mới bị lỗi:
• Rollback tự động trong 30s
• Alert cho DevOps nếu 3 lần rollout liên tiếp thất bại

🧯 10.7. Recovery từ lỗi nghiêm trọng¶

✅ Tóm lại, auth-service/sub được thiết kế để chịu lỗi, khôi phục tự động, cô lập tenant và đảm bảo hoạt động liên tục trong điều kiện thực tế nhiều biến động.

11. ⚡️ Hiệu năng & Khả năng mở rộng¶

auth-service/sub được thiết kế với mục tiêu hiệu năng cao, độ trễ thấp và có thể scale độc lập theo từng tenant. Dịch vụ hoạt động hoàn toàn stateless, tận dụng caching, pub/sub và cấu trúc microservice để đảm bảo khả năng phục vụ đồng thời hàng ngàn phiên đăng nhập mỗi phút.

⚙️ Kiến trúc hiệu năng cao¶

🚀 Khả năng mở rộng theo tenant¶

• Mỗi tenant được deploy theo instance hoặc namespace riêng
• Có thể điều chỉnh autoscale, resource limit theo nhu cầu từng tenant
• Tách queue Pub/Sub và cache Redis riêng → tránh “noisy neighbor”

graph TD
  Tenant1(AuthSub1) -->|Redis1| RedisCluster
  Tenant2(AuthSub2) -->|Redis2| RedisCluster
  Tenant3(AuthSub3) -->|Redis3| RedisCluster

📌 Có thể gom nhiều tenant có traffic thấp vào một cụm nếu cần tối ưu tài nguyên, nhưng phải bảo đảm tenant_id được cách ly logic.

📈 Các chỉ số theo dõi hiệu năng¶

Tất cả các chỉ số được theo dõi qua Prometheus và dashboard riêng cho từng tenant.

⛓ Giới hạn và bảo vệ¶

🧪 Benchmark đề xuất¶

🧩 Định hướng tối ưu tiếp theo¶

• Dùng JWT với short TTL + sliding session để giảm revoked lookup
• Caching result của OTP validate để giảm DB hit nếu resend
• Gom luồng audit log thành batch để gửi hiệu quả hơn

✅ Tổng kết: auth-service/sub có thể mở rộng linh hoạt theo tenant, đảm bảo phục vụ tốt các hệ thống trường lớn nhỏ với chi phí hạ tầng tối ưu, độ trễ thấp và độ sẵn sàng cao.

12. 🛠 Kế hoạch Triển khai & Migration¶

Việc triển khai auth-service/sub tuân theo chiến lược triển khai theo tenant độc lập, kết hợp versioning linh hoạt và khả năng migration an toàn nhằm đảm bảo zero downtime và không ảnh hưởng dữ liệu xác thực.

🚀 Chiến lược triển khai¶

helm upgrade --install auth-sub-school-abc ./charts/auth-sub -f values/school-abc.yaml

🧩 Chính sách versioning theo tenant¶

Tuân thủ adr-025, mỗi tenant có thể sử dụng phiên bản service khác nhau, được quản lý theo semver:

Các version được quản lý qua Helm tag + image tag, được kiểm tra tự động trước khi cập nhật diện rộng.

🔁 Kế hoạch migration schema¶

Tuân thủ adr-023, mọi migration đều phải: - Có version kiểm soát - Có backup snapshot trước khi apply - Có rollback script đi kèm

⛑ Phục hồi nếu deployment lỗi¶

📋 Checklist triển khai tenant mới¶

1. Tạo file cấu hình values/tenant-id.yaml
2. Tạo secret Vault hoặc Kubernetes tương ứng
3. Khởi tạo DB với auth_sessions table
4. Apply Helm chart
5. Kiểm thử login flow (OTP & Local)
6. Kích hoạt autoscaler nếu load thực tế cao
7. Giám sát metrics & alert trong 24h đầu
8. Bàn giao cho quản trị viên tenant

🧪 Mô phỏng deploy mass multi-tenant¶

• Kịch bản: deploy 50 tenants song song
• Mỗi tenant deploy mất ~8s
• Tổng thời gian rollout < 7 phút
• Không có downtime ở các tenant đang hoạt động

✅ Kết luận: auth-service/sub hỗ trợ triển khai linh hoạt, cô lập rủi ro, rollback dễ dàng, và mở rộng từng tenant theo nhu cầu thực tế.

13. 🧩 Kiến trúc Service¶

auth-service/sub được thiết kế theo mô hình microservice hiện đại, hoàn toàn stateless, tối ưu cho triển khai đa tenant và khả năng mở rộng độc lập theo từng tenant.

🏗 Kiến trúc nội tại (Internal Architecture)¶

graph LR
  GW[API Gateway] --> SRV(Auth Service Sub)
  SRV --> OTP[OTP Module]
  SRV --> LOCAL[Local Login Module]
  SRV --> TS[Token Service]
  SRV --> US[User Service]
  SRV --> AUD[Audit Logging]
  SRV --> REDIS[Redis Cache]
  SRV --> PG[PostgreSQLauth_sessions]

🧩 Các thành phần chính¶

🧱 Kiến trúc triển khai (Deployment Architecture)¶

flowchart TD
  subgraph Tenant A
    A1[auth-service/sub:v1.2.0]
    A2[Postgres A]
    A3[Redis A]
  end

  subgraph Tenant B
    B1[auth-service/sub:v1.1.5]
    B2[Postgres B]
    B3[Redis B]
  end

  GW[API Gateway] -->|X-Tenant-ID: A| A1
  GW -->|X-Tenant-ID: B| B1

• Mỗi tenant có thể chạy một phiên bản khác nhau
• Redis và Postgres có thể tách riêng hoặc dùng cùng Redis cluster phân vùng theo tenant_id
• Tất cả giao tiếp ra bên ngoài đều dùng nội bộ (cluster.local) và bảo vệ bằng HMAC hoặc mTLS

🧠 Quy tắc thiết kế¶

📦 Thư mục mã nguồn (gợi ý)¶

auth-service-sub/
├── main.py
├── config/          # Load cấu hình theo tenant
├── routes/          # OTP, local login, logout
├── services/        # Giao tiếp token, user, audit
├── models/          # DB model cho auth_sessions
├── schemas/         # Request/response schema
├── utils/           # Helper extract metadata, hashing
├── tests/
│   ├── unit/
│   ├── integration/
│   └── contract/

✅ Kết luận: Kiến trúc của auth-service/sub được tối ưu để vận hành tin cậy, tách biệt rủi ro, dễ quan sát và scale hiệu quả trên môi trường multi-tenant.

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

• Interface Contract
• Data Model
• OpenAPI Spec
• ADR-006 - Auth Strategy
• ADR-007 - RBAC
• rbac-deep-dive.md