@torus-engineering/tas-kit 1.7.0 → 1.8.0

package/.tas/templates/SAD.md

@@ -1,274 +1,274 @@
-# Solution Architecture Document (SAD)
-
-> **Version:** 1.0
-> **Last Updated:** [Date]
-> **Author:** [SE name]
-
----
-
-## 1. Executive Summary
-
-<!-- MANDATORY. Viết cho người đọc không có technical background.
-  Bắt buộc:
-  - 1.1 Purpose: Tại sao SAD này tồn tại, vấn đề gì cần giải quyết
-  - 1.2 Scope: Hệ thống nào, ranh giới nào được/không được cover
-  - 1.3 Key Objectives: 3-5 mục tiêu kiến trúc cụ thể, đo lường được
-  Format: Prose ngắn, tối đa 1 trang tổng cộng -->
-
-### 1.1 Purpose
-### 1.2 Scope
-### 1.3 Key Objectives
-
----
-
-## 2. Architecture Vision
-
-<!-- MANDATORY.
-  Bắt buộc:
-  - 2.1 Vision Statement: 1-2 câu mô tả "kiến trúc này hướng tới điều gì"
-  - 2.2 Architecture Principles: 4-8 nguyên tắc dẫn dắt quyết định thiết kế
-    (vd: Stateless services, API-first, Defense in depth, Fail fast)
-  - 2.3 Constraints & Assumptions: Ràng buộc kỹ thuật/tổ chức, giả định đang được chấp nhận
-  Format: Bullet list cho principles và constraints -->
-
-### 2.1 Vision Statement
-### 2.2 Architecture Principles
-### 2.3 Constraints & Assumptions
-
----
-
-## 3. Business Requirements
-
-<!-- MANDATORY.
-  Bắt buộc:
-  - 3.1 Business Problem: Mô tả bài toán kinh doanh cần giải quyết
-  - 3.2 Stakeholders: Bảng stakeholder (role, concerns, influence)
-  - 3.3 Functional Requirements: Danh sách FR-xxx, mỗi item có ID để trace
-  - 3.4 Non-Functional Requirements: Danh sách NFR với metric cụ thể
-    (vd: Latency P99 < 300ms, Availability 99.9%, RPS 5000)
-  Nên có: Priority (Must/Should/Could) cho mỗi requirement
-  Format: Table hoặc numbered list với ID (FR-001, NFR-001) -->
-
-### 3.1 Business Problem
-### 3.2 Stakeholders
-### 3.3 Functional Requirements
-### 3.4 Non-Functional Requirements
-
----
-
-## 4. Technology Baseline
-
-<!-- MANDATORY.
-  Bắt buộc:
-  - 4.1 Current State: Hệ thống hiện tại (nếu là greenfield thì ghi rõ)
-  - 4.2 Technology Stack: Bảng layer → technology → version → rationale
-    (Frontend / Backend / Database / Infrastructure / Messaging / Monitoring)
-  - 4.3 Dependencies: External services, third-party APIs, shared platforms
-  Nên có: Diagram current-state nếu là migration/modernization
-  Format: Table cho Technology Stack -->
-
-### 4.1 Current State
-### 4.2 Technology Stack
-### 4.3 Dependencies
-
----
-
-## 5. System Context (C4 Level 1)
-
-<!-- MANDATORY. Trả lời: "Hệ thống này nằm ở đâu trong hệ sinh thái?"
-  Bắt buộc:
-  - Mermaid flowchart: hệ thống ở giữa, xung quanh là users và external systems
-  - Chú thích mỗi external system: tên, vai trò, protocol giao tiếp
-  Không cần: chi tiết nội bộ của hệ thống (để C4 Level 2)
-  Format: Mermaid flowchart (dùng :::mermaid wrapper, không dùng () trong node label)
-
-  Ví dụ:
-  :::mermaid
-  flowchart TD
-    U[fa:fa-user End User] -- |HTTPS| SYS[Your System]
-    SYS -- |REST| EXT1[Payment Gateway]
-    SYS -- |SMTP| EXT2[Email Service]
-    ADMIN[fa:fa-user Admin] -- |HTTPS| SYS
-  ::: -->
-
----
-
-## 6. Logical View (C4 Level 2 — Container)
-
-<!-- MANDATORY. Trả lời: "Hệ thống gồm những container nào?"
-  Bắt buộc:
-  - Mermaid flowchart: tất cả containers (web app, API, DB, cache, queue, ...)
-  - Mỗi container: tên, technology, vai trò chính
-  - Luồng tương tác giữa containers với protocol/label
-  Nên có: Phân nhóm theo bounded context nếu hệ thống lớn
-  Format: Mermaid flowchart với subgraph để nhóm theo domain
-
-  Ví dụ node: WebApp["Web App\n(Next.js / Vercel)"] -->
-
----
-
-## 7. Component View (C4 Level 3)
-
-<!-- CONDITIONAL — Bắt buộc nếu hệ thống có độ phức tạp cao hoặc team mới.
-  Trả lời: "Bên trong mỗi container có components nào?"
-  Hướng dẫn:
-  - Mỗi container phức tạp → một subsection riêng (7.1, 7.2, ...)
-  - Container đơn giản (chỉ proxy, static file, thin wrapper) → bỏ qua
-  - Không cần drill vào mọi container — chỉ những container có internal logic đáng kể
-  Mỗi subsection bắt buộc:
-  - Mermaid flowchart liệt kê components bên trong container đó
-  - Mỗi component: tên, trách nhiệm chính, interface exposed
-  - Dependency direction giữa components (tránh circular)
-  Format: Mermaid flowchart với subgraph bao ngoài (tên container), nodes là components
-
-  Ví dụ:
-  :::mermaid
-  flowchart TD
-    subgraph API["API Service (NestJS)"]
-      Router[Route Handler] -- AuthMW[Auth Middleware]
-      AuthMW -- Controller[Order Controller]
-      Controller -- Service[Order Service]
-      Service -- Repo[Order Repository]
-      Service -- Queue[Queue Publisher]
-    end
-  ::: -->
-
-### 7.1 [Container Name]
-
-<!-- Bắt buộc: Mermaid component diagram như hướng dẫn trên.
-  Nên có: Mô tả ngắn vai trò của container này trước diagram. -->
-
-### 7.2 [Container Name]
-
-<!-- Thêm subsection cho mỗi container phức tạp. Xóa subsection này nếu không cần. -->
-
----
-
-## 8. Data Architecture & ERD
-
-<!-- MANDATORY nếu hệ thống có persistence layer.
-  Bắt buộc:
-  - ERD: entities, attributes (chỉ key fields), relationships với cardinality
-  - Data flow overview: data đi từ đâu đến đâu, transform ở đâu
-  Nên có:
-  - Data classification: PII / Sensitive / Internal / Public cho mỗi entity
-  - Retention policy nếu có compliance requirement
-  - Sharding/partitioning strategy nếu data scale lớn
-  Format: Mermaid erDiagram cho ERD -->
-
----
-
-## 9. Integration & Data Flow
-
-<!-- MANDATORY nếu hệ thống tích hợp với external services hoặc có async flows.
-  Bắt buộc:
-  - Sequence diagram cho mỗi critical flow (auth, payment, order, ...)
-  - Async flows: queue/event-driven patterns phải được diagram rõ
-  Nên có: Error/retry flows cho critical paths
-  Format: Mermaid sequenceDiagram, một diagram per flow -->
-
-### 9.1 API Design Principles
-
-<!-- MANDATORY nếu hệ thống expose API (internal hoặc external).
-  Bắt buộc:
-  - API Style: REST / GraphQL / gRPC / Event-driven — và lý do chọn
-  - Versioning strategy: URL path (/v1/) vs header vs query param
-  - Authentication scheme: Bearer JWT / API Key / OAuth2 / mTLS
-  - Standard error format: HTTP status codes, error body structure
-  Nên có:
-  - Rate limiting approach (per-user, per-IP, tiered)
-  - Pagination convention (cursor vs offset)
-  - Idempotency handling cho mutating operations
-  Không đưa vào đây: endpoint list, request/response schema chi tiết
-    → Những thứ đó thuộc API Contract document riêng (viết khi implement)
-  Format: Bullet list hoặc table ngắn gọn -->
-
----
-
-## 10. Security Architecture
-
-<!-- MANDATORY. Đây là architectural concern, không phải implementation detail.
-  Bắt buộc:
-  - Threat Model: attack surfaces, trust boundaries, top threats (dùng STRIDE nếu cần)
-  - Identity & Auth Flow: AuthN/AuthZ mechanism, token lifecycle, privilege escalation path
-  - Data Classification: PII / Sensitive / Internal / Public — handling rules per class
-  - Network Security Zones: public / DMZ / private / data tier và rules giữa các zones
-  - Encryption: at-rest (algorithm, key management) và in-transit (TLS version, cert strategy)
-  Nên có:
-  - Secrets management approach (Vault, AWS SSM, env vars strategy)
-  - Audit logging scope: what events must be logged, retention
-  - Compliance requirements: GDPR, PCI-DSS, SOC2, ... nếu applicable
-  Format:
-  - Threat model: table (Threat | Vector | Mitigation)
-  - Auth flow: Mermaid sequenceDiagram
-  - Network zones: Mermaid flowchart với subgraph per zone -->
-
----
-
-## 11. NFR Strategies
-
-<!-- MANDATORY. Mỗi NFR-xxx trong Section 3.4 phải có strategy tương ứng ở đây (reference bằng ID).
-  Bắt buộc — cover các categories sau nếu có NFR liên quan:
-  - Performance: caching strategy (L1/L2/CDN), DB indexing, query optimization approach
-  - Scalability: horizontal vs vertical, stateless design, queue-based decoupling
-  - Availability: redundancy model (Active-Active/Active-Passive), failover mechanism, SLA target
-  - Resilience: circuit breaker, retry with backoff, bulkhead, timeout policy
-  - Observability: structured logging, distributed tracing, metrics & alerting thresholds
-  Nên có:
-  - Capacity planning baseline: expected load, growth projection, scale trigger points
-  - DR strategy: RPO/RTO targets, backup frequency, restore procedure overview
-  Format: Table với cột NFR ID để trace ngược về Section 3.4
-  | NFR ID | Category | Target | Strategy | Notes |
-  |--------|----------|--------|----------|-------|
-  | NFR-001 | Latency | P99 < 300ms | Redis cache L2, read replicas | Cache TTL 5m |
-  | NFR-002 | Availability | 99.9% | Active-Active, 2 AZs | Health check interval 10s | -->
-
----
-
-## 12. Deployment Topology
-
-<!-- MANDATORY. Trả lời: "Các components chạy ở đâu trong infrastructure?"
-  Bắt buộc:
-  - Infrastructure diagram: regions, AZs, VPC/subnets, load balancers, entry points
-  - Component-to-infrastructure mapping: service X → ECS Fargate, DB → RDS Multi-AZ, ...
-  - Traffic entry points: CDN → ALB → API Gateway → Service flow
-  - Environment matrix: dev / staging / prod — sự khác nhau về scale, config, isolation
-  Nên có:
-  - Network topology: public subnet / private subnet / data subnet và routing rules
-  - CI/CD pipeline overview: build → test → deploy flow và approval gates
-  - Container orchestration config nếu dùng K8s/ECS (namespace, resource limits)
-  Format:
-  - Mermaid flowchart với subgraph per environment tier hoặc per network zone
-  - Environment matrix: table (Component | Dev | Staging | Prod) -->
-
----
-
-## 13. Architectural Decisions
-
-<!-- MANDATORY. Ghi lại mọi quyết định kiến trúc quan trọng và lý do.
-  Bắt buộc: Mỗi ADR entry gồm Decision, Status, Date, Rationale
-  Nên có: Alternatives considered và tại sao không chọn
-  Format: Table — thêm row mỗi khi có quyết định mới
-  Status values: Proposed | Accepted | Deprecated | Superseded -->
-
-| ID | Decision | Status | Date | Rationale |
-|----|----------|--------|------|-----------|
-
----
-
-## 14. Risks & Mitigation
-
-<!-- MANDATORY.
-  Bắt buộc: Risk, Impact (H/M/L), Probability (H/M/L), Mitigation action
-  Nên có: Owner và review date cho mỗi risk
-  Format: Table, sắp xếp theo Impact × Probability giảm dần -->
-
-| Risk | Impact | Probability | Mitigation | Owner |
-|------|--------|-------------|------------|-------|
-
----
-
-## Changelog
-
-| Date | Version | Changes | Author |
-|------|---------|---------|--------|
+# Solution Architecture Document (SAD)
+
+> **Version:** 1.0
+> **Last Updated:** [Date]
+> **Author:** [SE name]
+
+---
+
+## 1. Executive Summary
+
+<!-- MANDATORY. Viết cho người đọc không có technical background.
+  Bắt buộc:
+  - 1.1 Purpose: Tại sao SAD này tồn tại, vấn đề gì cần giải quyết
+  - 1.2 Scope: Hệ thống nào, ranh giới nào được/không được cover
+  - 1.3 Key Objectives: 3-5 mục tiêu kiến trúc cụ thể, đo lường được
+  Format: Prose ngắn, tối đa 1 trang tổng cộng -->
+
+### 1.1 Purpose
+### 1.2 Scope
+### 1.3 Key Objectives
+
+---
+
+## 2. Architecture Vision
+
+<!-- MANDATORY.
+  Bắt buộc:
+  - 2.1 Vision Statement: 1-2 câu mô tả "kiến trúc này hướng tới điều gì"
+  - 2.2 Architecture Principles: 4-8 nguyên tắc dẫn dắt quyết định thiết kế
+    (vd: Stateless services, API-first, Defense in depth, Fail fast)
+  - 2.3 Constraints & Assumptions: Ràng buộc kỹ thuật/tổ chức, giả định đang được chấp nhận
+  Format: Bullet list cho principles và constraints -->
+
+### 2.1 Vision Statement
+### 2.2 Architecture Principles
+### 2.3 Constraints & Assumptions
+
+---
+
+## 3. Business Requirements
+
+<!-- MANDATORY.
+  Bắt buộc:
+  - 3.1 Business Problem: Mô tả bài toán kinh doanh cần giải quyết
+  - 3.2 Stakeholders: Bảng stakeholder (role, concerns, influence)
+  - 3.3 Functional Requirements: Danh sách FR-xxx, mỗi item có ID để trace
+  - 3.4 Non-Functional Requirements: Danh sách NFR với metric cụ thể
+    (vd: Latency P99 < 300ms, Availability 99.9%, RPS 5000)
+  Nên có: Priority (Must/Should/Could) cho mỗi requirement
+  Format: Table hoặc numbered list với ID (FR-001, NFR-001) -->
+
+### 3.1 Business Problem
+### 3.2 Stakeholders
+### 3.3 Functional Requirements
+### 3.4 Non-Functional Requirements
+
+---
+
+## 4. Technology Baseline
+
+<!-- MANDATORY.
+  Bắt buộc:
+  - 4.1 Current State: Hệ thống hiện tại (nếu là greenfield thì ghi rõ)
+  - 4.2 Technology Stack: Bảng layer → technology → version → rationale
+    (Frontend / Backend / Database / Infrastructure / Messaging / Monitoring)
+  - 4.3 Dependencies: External services, third-party APIs, shared platforms
+  Nên có: Diagram current-state nếu là migration/modernization
+  Format: Table cho Technology Stack -->
+
+### 4.1 Current State
+### 4.2 Technology Stack
+### 4.3 Dependencies
+
+---
+
+## 5. System Context (C4 Level 1)
+
+<!-- MANDATORY. Trả lời: "Hệ thống này nằm ở đâu trong hệ sinh thái?"
+  Bắt buộc:
+  - Mermaid flowchart: hệ thống ở giữa, xung quanh là users và external systems
+  - Chú thích mỗi external system: tên, vai trò, protocol giao tiếp
+  Không cần: chi tiết nội bộ của hệ thống (để C4 Level 2)
+  Format: Mermaid flowchart (dùng :::mermaid wrapper, không dùng () trong node label)
+
+  Ví dụ:
+  :::mermaid
+  flowchart TD
+    U[fa:fa-user End User] -- |HTTPS| SYS[Your System]
+    SYS -- |REST| EXT1[Payment Gateway]
+    SYS -- |SMTP| EXT2[Email Service]
+    ADMIN[fa:fa-user Admin] -- |HTTPS| SYS
+  ::: -->
+
+---
+
+## 6. Logical View (C4 Level 2 — Container)
+
+<!-- MANDATORY. Trả lời: "Hệ thống gồm những container nào?"
+  Bắt buộc:
+  - Mermaid flowchart: tất cả containers (web app, API, DB, cache, queue, ...)
+  - Mỗi container: tên, technology, vai trò chính
+  - Luồng tương tác giữa containers với protocol/label
+  Nên có: Phân nhóm theo bounded context nếu hệ thống lớn
+  Format: Mermaid flowchart với subgraph để nhóm theo domain
+
+  Ví dụ node: WebApp["Web App\n(Next.js / Vercel)"] -->
+
+---
+
+## 7. Component View (C4 Level 3)
+
+<!-- CONDITIONAL — Bắt buộc nếu hệ thống có độ phức tạp cao hoặc team mới.
+  Trả lời: "Bên trong mỗi container có components nào?"
+  Hướng dẫn:
+  - Mỗi container phức tạp → một subsection riêng (7.1, 7.2, ...)
+  - Container đơn giản (chỉ proxy, static file, thin wrapper) → bỏ qua
+  - Không cần drill vào mọi container — chỉ những container có internal logic đáng kể
+  Mỗi subsection bắt buộc:
+  - Mermaid flowchart liệt kê components bên trong container đó
+  - Mỗi component: tên, trách nhiệm chính, interface exposed
+  - Dependency direction giữa components (tránh circular)
+  Format: Mermaid flowchart với subgraph bao ngoài (tên container), nodes là components
+
+  Ví dụ:
+  :::mermaid
+  flowchart TD
+    subgraph API["API Service (NestJS)"]
+      Router[Route Handler] -- AuthMW[Auth Middleware]
+      AuthMW -- Controller[Order Controller]
+      Controller -- Service[Order Service]
+      Service -- Repo[Order Repository]
+      Service -- Queue[Queue Publisher]
+    end
+  ::: -->
+
+### 7.1 [Container Name]
+
+<!-- Bắt buộc: Mermaid component diagram như hướng dẫn trên.
+  Nên có: Mô tả ngắn vai trò của container này trước diagram. -->
+
+### 7.2 [Container Name]
+
+<!-- Thêm subsection cho mỗi container phức tạp. Xóa subsection này nếu không cần. -->
+
+---
+
+## 8. Data Architecture & ERD
+
+<!-- MANDATORY nếu hệ thống có persistence layer.
+  Bắt buộc:
+  - ERD: entities, attributes (chỉ key fields), relationships với cardinality
+  - Data flow overview: data đi từ đâu đến đâu, transform ở đâu
+  Nên có:
+  - Data classification: PII / Sensitive / Internal / Public cho mỗi entity
+  - Retention policy nếu có compliance requirement
+  - Sharding/partitioning strategy nếu data scale lớn
+  Format: Mermaid erDiagram cho ERD -->
+
+---
+
+## 9. Integration & Data Flow
+
+<!-- MANDATORY nếu hệ thống tích hợp với external services hoặc có async flows.
+  Bắt buộc:
+  - Sequence diagram cho mỗi critical flow (auth, payment, order, ...)
+  - Async flows: queue/event-driven patterns phải được diagram rõ
+  Nên có: Error/retry flows cho critical paths
+  Format: Mermaid sequenceDiagram, một diagram per flow -->
+
+### 9.1 API Design Principles
+
+<!-- MANDATORY nếu hệ thống expose API (internal hoặc external).
+  Bắt buộc:
+  - API Style: REST / GraphQL / gRPC / Event-driven — và lý do chọn
+  - Versioning strategy: URL path (/v1/) vs header vs query param
+  - Authentication scheme: Bearer JWT / API Key / OAuth2 / mTLS
+  - Standard error format: HTTP status codes, error body structure
+  Nên có:
+  - Rate limiting approach (per-user, per-IP, tiered)
+  - Pagination convention (cursor vs offset)
+  - Idempotency handling cho mutating operations
+  Không đưa vào đây: endpoint list, request/response schema chi tiết
+    → Những thứ đó thuộc API Contract document riêng (viết khi implement)
+  Format: Bullet list hoặc table ngắn gọn -->
+
+---
+
+## 10. Security Architecture
+
+<!-- MANDATORY. Đây là architectural concern, không phải implementation detail.
+  Bắt buộc:
+  - Threat Model: attack surfaces, trust boundaries, top threats (dùng STRIDE nếu cần)
+  - Identity & Auth Flow: AuthN/AuthZ mechanism, token lifecycle, privilege escalation path
+  - Data Classification: PII / Sensitive / Internal / Public — handling rules per class
+  - Network Security Zones: public / DMZ / private / data tier và rules giữa các zones
+  - Encryption: at-rest (algorithm, key management) và in-transit (TLS version, cert strategy)
+  Nên có:
+  - Secrets management approach (Vault, AWS SSM, env vars strategy)
+  - Audit logging scope: what events must be logged, retention
+  - Compliance requirements: GDPR, PCI-DSS, SOC2, ... nếu applicable
+  Format:
+  - Threat model: table (Threat | Vector | Mitigation)
+  - Auth flow: Mermaid sequenceDiagram
+  - Network zones: Mermaid flowchart với subgraph per zone -->
+
+---
+
+## 11. NFR Strategies
+
+<!-- MANDATORY. Mỗi NFR-xxx trong Section 3.4 phải có strategy tương ứng ở đây (reference bằng ID).
+  Bắt buộc — cover các categories sau nếu có NFR liên quan:
+  - Performance: caching strategy (L1/L2/CDN), DB indexing, query optimization approach
+  - Scalability: horizontal vs vertical, stateless design, queue-based decoupling
+  - Availability: redundancy model (Active-Active/Active-Passive), failover mechanism, SLA target
+  - Resilience: circuit breaker, retry with backoff, bulkhead, timeout policy
+  - Observability: structured logging, distributed tracing, metrics & alerting thresholds
+  Nên có:
+  - Capacity planning baseline: expected load, growth projection, scale trigger points
+  - DR strategy: RPO/RTO targets, backup frequency, restore procedure overview
+  Format: Table với cột NFR ID để trace ngược về Section 3.4
+  | NFR ID | Category | Target | Strategy | Notes |
+  |--------|----------|--------|----------|-------|
+  | NFR-001 | Latency | P99 < 300ms | Redis cache L2, read replicas | Cache TTL 5m |
+  | NFR-002 | Availability | 99.9% | Active-Active, 2 AZs | Health check interval 10s | -->
+
+---
+
+## 12. Deployment Topology
+
+<!-- MANDATORY. Trả lời: "Các components chạy ở đâu trong infrastructure?"
+  Bắt buộc:
+  - Infrastructure diagram: regions, AZs, VPC/subnets, load balancers, entry points
+  - Component-to-infrastructure mapping: service X → ECS Fargate, DB → RDS Multi-AZ, ...
+  - Traffic entry points: CDN → ALB → API Gateway → Service flow
+  - Environment matrix: dev / staging / prod — sự khác nhau về scale, config, isolation
+  Nên có:
+  - Network topology: public subnet / private subnet / data subnet và routing rules
+  - CI/CD pipeline overview: build → test → deploy flow và approval gates
+  - Container orchestration config nếu dùng K8s/ECS (namespace, resource limits)
+  Format:
+  - Mermaid flowchart với subgraph per environment tier hoặc per network zone
+  - Environment matrix: table (Component | Dev | Staging | Prod) -->
+
+---
+
+## 13. Architectural Decisions
+
+<!-- MANDATORY. Ghi lại mọi quyết định kiến trúc quan trọng và lý do.
+  Bắt buộc: Mỗi ADR entry gồm Decision, Status, Date, Rationale
+  Nên có: Alternatives considered và tại sao không chọn
+  Format: Table — thêm row mỗi khi có quyết định mới
+  Status values: Proposed | Accepted | Deprecated | Superseded -->
+
+| ID | Decision | Status | Date | Rationale |
+|----|----------|--------|------|-----------|
+
+---
+
+## 14. Risks & Mitigation
+
+<!-- MANDATORY.
+  Bắt buộc: Risk, Impact (H/M/L), Probability (H/M/L), Mitigation action
+  Nên có: Owner và review date cho mỗi risk
+  Format: Table, sắp xếp theo Impact × Probability giảm dần -->
+
+| Risk | Impact | Probability | Mitigation | Owner |
+|------|--------|-------------|------------|-------|
+
+---
+
+## Changelog
+
+| Date | Version | Changes | Author |
+|------|---------|---------|--------|