@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-architecture-design/steps/step-04.1b-wbs-audit.md

@@ -0,0 +1,97 @@
+# Step 04.1b: WBS Audit & Coverage Quality Gate
+
+> **Acting as:** [Agent E — Master Orchestrator](../agents/agent_e_orchestrator.md) (vai trò QA Gatekeeper)
+> **Tuân thủ:** [Iron Rules](../principles/iron_rules.md) — đặc biệt R4 (Traceability), R6 (Gate), R7 (Stopping Errors).
+
+## MỤC TIÊU (Goal)
+Đảm bảo bản danh sách đơn vị work (WBS) do Agent C tạo ra đạt độ bao phủ 100% so với yêu cầu kinh doanh (PRD/Epics), phân loại module đúng 4-type taxonomy, và sở hữu cấu trúc dữ liệu High-Fidelity trước khi tiến hành thiết kế chi tiết.
+
+## VAI TRÒ (Role)
+- **Agent thực hiện**: **Agent E (Orchestrator/QA)**.
+- **Agent nhận feedback**: **Agent C (Architect)**.
+
+## ĐIỀU KIỆN KÍCH HOẠT (Trigger)
+- Sau khi Agent C hoàn tất việc tạo/cập nhật file `project_wbs.md` tại Step 04.1.
+
+---
+
+## QUY TRÌNH KIỂM TOÁN (Audit Workflow)
+
+### 1. Kiểm toán định lượng (Coverage Check)
+- **Hành động**: Agent E đối soát danh sách `Epic ID / Story ID` trong WBS (Cột 4) với tài liệu PRD/Epics (Level 0).
+- **Check-item**:
+    - [ ] Mọi Epic quan trọng đều có ít nhất một đơn vị work tương ứng.
+    - [ ] Không có Story nào bị bỏ sót (Missing Coverage).
+    - [ ] Story chưa được cover → Agent E ghi nhận vào `Audit Report`.
+
+### 2. Kiểm toán định tính (Data Lineage Check)
+- **Hành động**: Kiểm tra tính logic của chuỗi Input/Output.
+- **Check-item**:
+    - [ ] Cấu trúc 3 dòng thẻ `<br>` (Input/Output) được thực thi 100%.
+    - [ ] **Data Chain Integrity**: Mọi Output của ID phía trước phải được sử dụng làm Input cho ID phía sau (tránh dữ liệu "chết" hoặc "mồ côi").
+
+### 2b. Kiểm toán cấu trúc file (Structural Check)
+- **Hành động**: Kiểm tra `project_wbs.md` đúng cấu trúc 2 thành phần theo template.
+- **Check-item**:
+    - [ ] Có **Function Decomposition Tree** (fenced block ` ```text `, ASCII với `├──` `│` `└──`) đặt **trước** Coverage Matrix.
+    - [ ] Có **Coverage Matrix** bảng 4 cột.
+    - [ ] **Tree ↔ Bảng integrity**: Mọi ID xuất hiện trong Tree phải xuất hiện trong Bảng và ngược lại — không thiếu, không thừa.
+    - [ ] **ID uniqueness (global toàn project)**: Mỗi WBS ID xuất hiện đúng 1 row trong Bảng — KHÔNG trùng cross-module/cross-repo (2 FE app cùng chức năng phải phân biệt bằng segment app, vd `SCR-ADM-LOGIN` vs `SCR-APP-LOGIN`). Trùng → FAIL, list ID.
+
+### 2c. Kiểm toán phân loại module (Module Type Classification Check)
+- **Hành động**: Kiểm tra mỗi cluster trong WBS đã declare đúng `module_type` (1 trong 4 type) và đơn vị work dưới cluster khớp convention.
+- **Check-item**:
+    - [ ] Mọi cluster header đều có hậu tố `_(module_type)_` với giá trị ∈ {`backend-service`, `frontend-app`, `integration-contract`, `infrastructure`} (xem template mục 0).
+    - [ ] **Naming convention khớp module_type:**
+        - `backend-service` / `infrastructure` → ID dạng `{MOD}-NN` hoặc `BE-{MOD}-NN` (feature_id).
+        - `frontend-app` → ID dạng `SCR-{NAME}` (screen) hoặc `WGT-{NAME}` (widget). KHÔNG cho phép feature_id pattern trong cluster FE.
+        - `integration-contract` → ID dạng `INT-{SRC}-NN`.
+    - [ ] **Cross-mismatch check**: ID prefix `SCR-` / `WGT-` xuất hiện trong cluster KHÔNG phải `frontend-app` → FAIL (vd: `SCR-LOGIN` lạc vào cluster `backend-service`).
+    - [ ] **Frontend-app coverage:** Cluster `frontend-app` phải có ≥ 1 screen. Cluster chỉ có widgets (không screen) → cho phép nhưng warn (component library reusable).
+    - [ ] **Repo binding (CHỈ audit khi project multi-repo):** project có ≥2 FE code repo (signal: `design-system/registry.yaml` khai ≥2 systems, hoặc baseline/user đã xác nhận multi-repo) → mọi Cluster Header `frontend-app` PHẢI có thẻ `- repo: <code-repo-folder>` ở cột 3, giá trị ∈ danh sách code repo đã biết (workspace folder / registry `code_repo`). Thiếu thẻ hoặc giá trị lạ → FAIL, list cluster. Thẻ `repo` xuất hiện ở row đơn vị work (không phải header) → FAIL (sai vị trí). Project 1 code repo → thẻ optional, bỏ qua check.
+
+### 2d. Kiểm toán quan hệ (Relations Cross-Reference Check)
+- **Hành động**: Verify relations field (`consumes` / `used_by` / `provider` / `consumers`) trỏ tới ID thực sự tồn tại trong WBS.
+- **Check-item**:
+    - [ ] Mọi `screen` row có field `consumes: <feature_id>` → mỗi `<feature_id>` phải tồn tại trong cùng WBS (cluster `backend-service` hoặc `integration-contract`).
+    - [ ] Mọi `widget` row có field `used_by: <screen_id>` → mỗi `<screen_id>` phải tồn tại trong cùng WBS (cluster `frontend-app`).
+    - [ ] Mọi `contract` row có `provider: <module_id>` + `consumers: <module_id>...` → mỗi `<module_id>` phải khớp prefix cluster header tồn tại trong WBS.
+    - [ ] Dangling reference (relations trỏ tới ID không tồn tại) → FAIL, list ra ID lạc.
+
+### 2e. Kiểm toán tính đầy đủ đồ thị (Graph-Completeness Presence Check)
+
+> **Bản chất (A-U3):** đây là **presence check** — Agent E chỉ kiểm *có khai hay không*, rồi trả về **gap-list có địa chỉ** để Agent C sửa trong **MỘT lượt follow-up bounded**. Completeness là việc của Agent E (audit), KHÔNG dồn lên Agent C phải hoàn hảo trong 1 pass. Đây là checklist đóng, không phải bài toán mở.
+
+- **Phạm vi:** CHỈ xét **feature-unit**. **BỎ QUA** mọi unit có cột Epic (Cột 4) bắt đầu bằng `BL:` — đó là baseline brownfield as-built, ngoài phạm vi (không ép khai lại cạnh cho hệ đã chạy).
+- **Phân loại role:** role đọc từ thẻ `<br>- role: <role>` ở cột 3; nếu trống thì suy từ prefix (`SCR-`/`WGT-` → consumer; `INT-` → contract).
+- **Check-item (mỗi mục miss → ghi ID cụ thể vào gap-list):**
+    - [ ] Mọi **consumer** (screen / widget, hoặc `role: consumer`) khai **≥ 1** `consumes` → nếu 0 thì list ID.
+    - [ ] Mọi **contract** (`INT-*`) khai **cả** `provider` **và** `consumers` → nếu thiếu thì list ID + nêu rõ thiếu cái nào (`provider` hay `consumers`).
+    - [ ] Mọi unit có `role ∈ {proxy, gateway, aggregation, bff}` **bị ít nhất một consumer tiêu thụ** mà **không** khai downstream `consumes` → list ID (proxy fronting service khác phải khai nó forward xuống đâu).
+- **Output format (gap-list có địa chỉ, cụ thể, đếm được):**
+    > `[graph-completeness] N unit consumer thiếu consumes: <id>, <id>; M contract thiếu provider: <id>; K contract thiếu consumers: <id>; P proxy thiếu downstream consumes: <id>`
+    Nếu 0 gap → ghi "Graph-completeness: PASS".
+- Agent C nhận gap-list và sửa trong **một lượt follow-up bounded** (chỉ điền cạnh thiếu, không re-author toàn bảng), rồi Agent E re-check mục 2e.
+
+### 3. Feedback Loop (Cơ chế phản hồi)
+- **Hành động**: Agent E xuất một bản `WBS Audit Report` ngắn gọn.
+- **Nếu FAIL**:
+    - Agent E cung cấp danh sách cụ thể các ID hoặc Story bị lỗi/thiếu, phân loại theo gate (Coverage / Lineage / Structural / Module Type / Relations / **Graph-completeness**). Riêng Graph-completeness → trả gap-list có địa chỉ (mục 2e) để Agent C điền cạnh thiếu trong 1 lượt follow-up bounded.
+    - Agent C **PHẢI** quay lại Step 04.1 để cập nhật lại `project_wbs.md` cho đến khi đạt Pass.
+- **Nếu PASS**:
+    - Agent E "Khóa" WBS và cho phép workflow chuyển sang Step 04.2 (Modular Design).
+
+---
+
+## KẾT QUẢ ĐẦU RA (Exit Criteria)
+1. File `project_wbs.md` đạt trạng thái "Audited & Locked".
+2. Báo cáo `WBS_Audit_Report.md` (nếu có lỗi cần fix), phân loại theo 6 gate (Coverage / Lineage / Structural / Module Type / Relations / Graph-completeness).
+
+---
+
+## ⛔ [GATE G2 — WBS Lock] (đặt TRƯỚC Next)
+
+- **FAIL** (bất kỳ 1 trong 6 category: Coverage / Lineage / Structural / Module Type / Relations / **Graph-completeness**) → Agent C **PHẢI** quay lại [`./step-04.1-architecture-global.md`](./step-04.1-architecture-global.md) cập nhật `project_wbs.md` rồi re-audit. KHÔNG đi tiếp (đây là recovery loop của gate, KHÔNG phải `**Next:**`).
+- **PASS** → Agent E "Khoá" WBS ("Audited & Locked"). Agent C quay lại Step 04.1 hoàn tất L1/L2 + ERD (nếu chưa) và đạt G3, rồi pipeline chuyển sang Step 04.2.
+
+**Next:** Read fully and follow `./step-04.2-architecture-modules.md`

package/skills/NTAPP/.agent/skills/NTAPP-architecture-design/steps/step-04.2-architecture-modules.md

@@ -0,0 +1,75 @@
+# STEP 04.2: MODULAR DEEPDIVE DESIGN
+
+> **Acting as:** [Agent C — System Architect](../agents/agent_c_system_architect.md)
+> **Tuân thủ:** [Iron Rules](../principles/iron_rules.md) — đặc biệt R4 (Traceability — WBS ID xuất hiện trong Sequence/Data Flow), R5 (Consistency — tên Container khớp L2).
+
+**Input:** `part_04.1_global_architecture.md` + `project_wbs.md` (Functional SSoT) + `part_03_tech_research.md` (nếu có) + Epics
+**Output:** `part_04.2_modular_deepdive.md` — (Bao gồm: Sequence Diagrams & Bảng Data Flow chi tiết cho từng Module)
+
+---
+
+## MỤC TIÊU BƯỚC NÀY
+
+Phân rã từng Module thành các thành phần nội tại, đặc tả chi tiết trình tự tương tác (Sequence) và logic xử lý (Data Flow) theo hai luồng Inbound (Ghi) và Query (Đọc) để đảm bảo tính **Traceability** tối thượng.
+
+---
+
+## QUY TRÌNH THỰC THI
+
+### 3.2 Mô hình phân rã chức năng/phân hệ
+
+> ⚠️ **CẤM sinh §3.2.0 (Function Decomposition Tree / WBS Injection) trong file này.** §3.2.0 thuộc về `project_wbs.md` (SSoT) và sẽ được Step 07 inject verbatim vào HLD final. Agent C bắt đầu output của step 04.2 từ §3.2.1.
+
+#### 3.2.1 Mô hình tổng thể
+Liệt kê danh sách các module/microservices đã xác định ở Step 04.1 (thường trình diễn kết hợp một bảng `| Module | Nhiệm vụ cốt lõi | API/Topic |`). 
+Với mỗi module, tuân thủ các quy định trình bày:
+- **Nhiệm vụ cốt lõi:** BẮT BUỘC phải được mô tả cực kỳ chi tiết, dễ hiểu và viết hoàn toàn bằng TIẾNG VIỆT. Cấm viết theo kiểu liệt kê gạch đầu dòng vài chữ sơ sài. Phải nêu rõ lý do module này tồn tại để cover use_case nào.
+- Danh sách API cung cấp (các chiều Inbound/Outbound).
+- Các Topic/Queue đang lắng nghe hoặc đẩy thông báo.
+
+#### 3.2.2 Mô hình luồng xử lý tổng thể (Sequence/Data Flow)
+
+**Thực hiện lặp (Loop) cho từng Module:**
+
+##### 3.2.2.x. [Tên Phân hệ]
+
+**A. Sequence Diagram (Nội tại Module)**
+**Sử dụng Mermaid sequenceDiagram.** Mô phỏng tương tác nội bộ để xử lý một yêu cầu nghiệp vụ tiêu biểu của module này.
+
+**B. Bảng luồng dữ liệu (Data Flow)**
+Lựa chọn các bảng phù hợp dựa trên tính chất của phân hệ:
+
+**1. Luồng Lưu dữ liệu (Inbound/Write Flow):**
+| Điểm nút (Node) | Hành động kích hoạt (Trigger) | Cơ chế xử lý & Chuyển hóa dữ liệu | Đích đến tiếp theo |
+| :--- | :--- | :--- | :--- |
+| `[Node nội bộ]` | `[Hành động]` | `[Logic chuyển hóa: Mapping, Validation, Storage]` | `[Node tiếp theo]` |
+
+**2. Luồng Truy vấn dữ liệu (Query/Read Flow):**
+| Đối tượng gọi | Nút kiểm tra / Xác thực | Nhánh xử lý (Condition) | Nguồn cấp dữ liệu & Cơ chế trả về |
+| :--- | :--- | :--- | :--- |
+| `[App/Web]` | `[Token check]` | `[VD: Cache HIT / MISS]` | `[Source of Truth & Format]` |
+
+**Quy tắc:**
+- **Zero Hallucination**: Chỉ sử dụng các định danh (Identifiers) đã có trong Container Diagram (L2).
+- **ERD Alignment**: Tất cả các đối tượng dữ liệu trong Sequence Diagram và tên bảng/trường trong Data Flow **BẮT BUỘC** phải tồn tại hoặc liên kết trực tiếp với thực thể trong ERD ở Step 4.1.
+- **Conditional Logic**: Luồng Query BẮT BUỘC phải thể hiện các nhánh rẽ (Success/Fail hoặc Hit/Miss).
+
+## Ghi output ra file
+Ghi kết quả vào file:
+- `{intermediate_folder}/part_04.2_modular_deepdive.md` — (Bao gồm: Sequence Diagrams & Bảng Data Flow chi tiết cho từng Module)
+
+---
+
+## ĐIỀU KIỆN TIẾP TỤC (Exit Criteria)
+- [ ] Mục 3.2.1 liệt kê đủ các module từ sơ đồ Container.
+- [ ] Mỗi module trọng tâm đều có đủ 2 bảng luồng dữ liệu (Inbound và Query).
+- [ ] 100% các thực thể dữ liệu trong Data Flow có thể truy vết ngược về ERD tại Step 4.1.
+- [ ] Không còn placeholder `[Data]` trong bảng.
+
+---
+
+## ⛔ [GATE — Exit Criteria] (đặt TRƯỚC Next)
+
+Chỉ sang Step 05 khi toàn bộ Exit Criteria trên PASS (đủ module, đủ 2 bảng luồng, traceability về ERD, không placeholder).
+
+**Next:** Read fully and follow `./step-05-implementation-security.md`

package/skills/NTAPP/.agent/skills/NTAPP-architecture-design/steps/step-05-implementation-security.md

@@ -0,0 +1,170 @@
+# STEP 05: IMPLEMENTATION & SECURITY DESIGN
+
+> **Acting as:** [Agent D — Implementation & Security Lead](../agents/agent_d_implementation_sec.md)
+> **Tuân thủ:** [Iron Rules](../principles/iron_rules.md) — đặc biệt R3 (Zero-Fabrication), R4 (Traceability — Project Tree map sang Container), R5 (Consistency — Folder name khớp Container name).
+
+**Input:** `part_04.1_global_architecture.md` + `part_04.2_modular_deepdive.md` + `part_03_tech_research.md` (nếu có) + `part_02_context_strategy.md`
+**Output:** `part_05_implementation_security.md` — (Bao gồm: Project Tree, Ánh xạ tính năng, Giải pháp ATTT & Hiệu năng)
+
+---
+
+## MỤC TIÊU BƯỚC NÀY
+
+Ánh xạ kiến trúc phần mềm xuống cấu trúc code vật lý (Folder Structure) và đặc tả 3 lớp ngoài-vào-trong của HLD: kiến trúc bảo mật (ATTT), giải pháp hiệu năng, và quản trị dữ liệu.
+
+---
+
+## QUY TRÌNH THỰC THI
+
+### 4. CHIẾN LƯỢC TRIỂN KHAI VẬT LÝ
+
+#### 4.1 Cấu trúc thư mục dự án
+
+Căn cứ vào danh sách Containers và Modules từ các tệp `part_04.x`, Agent D phải tạo cấu trúc thư mục vật lý thực tế. Stack ngôn ngữ và framework quyết định cấu trúc cụ thể; ví dụ dưới mang tính tham khảo cho monorepo/multi-module, **agent điều chỉnh theo stack thực tế của dự án**:
+
+```text
+{project_root}/
+├── apps/                          # Deployable applications (FE + BE)
+│   ├── {frontend_app}/            # Framework: {Angular/React/Vue/...}
+│   │   └── src/
+│   │       ├── core/              # Auth guards, interceptors, global state
+│   │       ├── features/          # Feature modules (1 folder per Epic)
+│   │       └── shared/            # Reusable UI components
+│   └── {backend_app}/             # Framework: {Spring/FastAPI/Express/...}
+│       ├── api/                   # API endpoints (REST/gRPC handlers)
+│       ├── core/                  # Config, security, gateway proxy
+│       ├── services/              # Business logic services
+│       └── adapters/              # Connectors tới external systems
+├── libs/                          # Shared libraries (không deploy độc lập)
+│   ├── adapters/                  # External system adapters
+│   │   └── {external_system}/     # 1 folder per external system
+│   │       └── ...                # Adapter pattern: API client + data transformer + schema validator (file convention theo stack)
+│   ├── domain/                    # Domain logic dùng chung (optional)
+│   └── shared/
+│       ├── schema/                # Canonical Data Models (mapping 1-1 ERD)
+│       └── utils/                 # Shared utilities
+└── infrastructure/                # Deploy configs (CI/CD-managed)
+    ├── containers/                # Container build files
+    ├── orchestration/             # K8s manifests / Helm charts / Compose
+    └── scripts/                   # Migration, seed, sync scripts
+```
+
+**Quy tắc:**
+- Mỗi thư mục PHẢI có comment giải thích vai trò.
+- **Data Governance**: Thư mục `schema/` (canonical data models) và schema validator của mỗi adapter phải ánh xạ 1-1 với thực thể trong ERD.
+- Dependency direction: `apps/` import được từ `libs/`, ngược lại KHÔNG được phép.
+- Mỗi External System trong `libs/adapters/{system}/` phải có đủ adapter pattern (API client + data transformer + schema validator) — phân thành bao nhiêu file là quyết định của stack (Python: 3 file riêng; TypeScript: thường gộp vào 1 module với 3 export).
+
+#### 4.2 Ánh xạ tính năng (Feature-to-Path)
+
+| Feature/Epic | Folder Path | Files chính | Dependency |
+| :--- | :--- | :--- | :--- |
+| `{Epic 1 - Tên Feature}` | `{apps/backend/api/...}` | `{handler + schema file theo stack}` | `{libs/adapters/{external_system}/}` |
+| `{Epic 2 - Tên Feature}` | `{apps/frontend/features/...}` | `{component + service theo stack}` | `{libs/shared/schema/}` |
+
+---
+
+### 5.1 Kiến trúc bảo mật hệ thống - ATTT
+
+#### 5.1.1 Internal Security Boundary (Trong hệ thống)
+
+| Cơ chế | Công cụ/Chuẩn | Mô tả chi tiết |
+| :--- | :--- | :--- |
+| Authentication | `{Keycloak / Auth0 / JWT}` | `{Token format, Expiry time, Refresh strategy}` |
+| Authorization | `{RBAC / ABAC}` | `{Danh sách roles và quyền tương ứng}` |
+| API Validation | `{Pydantic / Joi / Zod}` | `{Validate schema trên mọi request trước khi xử lý}` |
+| Data Encryption | `{AES-256 / TLS 1.3}` | `{Mã hóa at-rest và in-transit}` |
+| PII Masking | `{Custom Middleware}` | `{Trường nào bị mask trong ERD, mask pattern}` |
+| Secret Management | `{Hashicorp Vault / AWS Secrets}` | `{Loại secret nào lưu ở đây}` |
+
+#### 5.1.2 External & Network Security (High-Fidelity Zoning)
+
+| Cơ chế | Công cụ/Chuẩn | Mô tả chi tiết |
+| :--- | :--- | :--- |
+| **Network Zoning**| DMZ / Trust Zone | **DMZ:** Mọi public-facing gateway (Reverse Proxy, API Gateway, LLM Gateway nếu có). **Internal:** App services, DB, message broker. |
+| API Gateway | `{Kong / Nginx / Cloud-native}` | `{Rate limiting: X req/min, IP whitelist}` |
+| AI/LLM Gateway (nếu có) | `{Custom proxy}` | `PII Masking, Audit log, Token rotation, Fallback model` |
+| VPN Tunnel | `{WireGuard / OpenVPN}` | `{Luồng nào bắt buộc đi qua VPN}` |
+| Third-party Auth | `{API Key / OAuth2}` | `{Cách cấp phát và rotate Key}` |
+
+
+#### 5.1.3 Security Guardrails (Vùng cấm - Agent phải check trước khi code)
+
+```
+[ ] KHÔNG lưu plaintext credentials trong source code
+[ ] KHÔNG log dữ liệu PII (SĐT, CMND, Email) dưới dạng plaintext
+[ ] KHÔNG expose internal stack trace ra API response (dùng error codes)
+[ ] KHÔNG bỏ qua Token validation ở bất kỳ endpoint nào
+[ ] MỌI request cross-service phải có Service Account JWT
+[ ] Zero-retention: Session context phải bị flush sau {X} phút idle
+```
+
+---
+
+### 5.2 Giải pháp đối với yêu cầu hiệu năng
+
+#### 5.2.1 Caching Strategy
+
+| Cache Layer | Công cụ | Key Pattern | TTL | Chiến lược Invalidation |
+| :--- | :--- | :--- | :--- | :--- |
+| API Response Cache | `Redis Cluster` | `{entity}:{id}:{version}` | `{X}s` | `{Event-based: khi update → xóa key liên quan}` |
+| Schema Cache | `Redis` | `schema:{system}:{type}` | `24h` | `Cron job refresh lúc 00:00 hàng ngày` |
+| Session Cache | `Redis` | `session:{user_id}:{token_hash}` | `30m` | `Tự expire sau TTL; Flush khi logout` |
+
+#### 5.2.2 Database Scaling
+
+| Database | Sharding Strategy | Index Fields | Connection Pool |
+| :--- | :--- | :--- | :--- |
+| `{PostgreSQL}` | `{Shard by tenant_id}` | `{tenant_id, created_at, status}` | `{Max 20 connections/pod}` |
+| `{Redis}` | `{Cluster mode 3 master + 3 replica}` | N/A | `{Max 100 connections}` |
+
+#### 5.2.3 Auto-scaling Rules
+
+```
+Pod Scale-up trigger:  CPU > 70% trong 2 phút liên tiếp → +{N} pods
+Pod Scale-down trigger: CPU < 20% trong 10 phút → -{N} pods
+Max pods: {X}
+Min pods: {Y}
+```
+
+---
+
+### 5.3 Các giải pháp đối với các yêu cầu đặc biệt khác
+`[Mô tả các Pattern như Event-Driven Architecture, Microservices, quy trình CI/CD và cơ chế Deployment.]`
+
+### 5.4 Các giải pháp tuân thủ tiêu chuẩn Quản trị dữ liệu
+
+| Tiêu chuẩn | Cơ chế | Công cụ | Chi tiết |
+| :--- | :--- | :--- | :--- |
+| Secret Management | Vault (centralized) | `Hashicorp Vault` | `Tất cả API Keys, DB credentials, LLM keys` |
+| Encryption at Rest | Hash + Salt | `bcrypt / SHA-256 + salt` | `Password, sensitive ID fields` |
+| Audit Immutability | Write-once Log | `PostgreSQL WAL / Event Sourcing` | `Bảng audit_trails: chỉ INSERT, không UPDATE/DELETE` |
+| Centralized Logging | Log aggregation | `ELK Stack (Elastic, Logstash, Kibana)` | `Tất cả service log gửi về Logstash qua Filebeat` |
+| Data Retention | TTL policy | `Cron + Soft Delete` | `PII data xóa sau {X} ngày per regulation` |
+
+---
+
+## Ghi output ra file
+
+Ghi vào một file duy nhất:
+- `{intermediate_folder}/part_05_implementation_security.md` — (Bao gồm: Project Tree, Ánh xạ tính năng, Giải pháp ATTT & Hiệu năng)
+
+---
+
+## ĐIỀU KIỆN TIẾP TỤC (Exit Criteria)
+
+- [ ] Cây thư mục Project Tree đã được đặc tả đầy đủ với comment cho mỗi thư mục.
+- [ ] Feature-to-Path Mapping Table có ít nhất 1 dòng per Epic trong PRD.
+- [ ] 100% Shared Schemas trong Project Tree khớp với danh mục thực thể ERD (Step 4.1).
+- [ ] Bảng ATTT Internal và External đều có đủ hàng.
+- [ ] Security Guardrails checklist đã được điền với giá trị cụ thể (thay `{X}` bằng con số thực).
+- [ ] Bảng Caching Strategy có đủ các Layer (API, Schema, Session).
+- [ ] Không có `{placeholder}` còn sót trong output.
+
+---
+
+## ⛔ [GATE — Exit Criteria] (đặt TRƯỚC Next)
+
+Chỉ sang Step 06 khi toàn bộ Exit Criteria trên PASS (Project Tree đủ comment, Feature-to-Path ≥ 1 dòng/Epic, schema khớp ERD, bảng ATTT/Caching đủ hàng, không còn `{placeholder}`).
+
+**Next:** Read fully and follow `./step-06-module0.md`

package/skills/NTAPP/.agent/skills/NTAPP-architecture-design/steps/step-06-module0.md

@@ -0,0 +1,106 @@
+# STEP 06: MODULE 0 — CONNECTIVITY MATRIX & INTEGRATION HARDENING
+
+> **Acting as:** [Agent F — Integration Architect](../agents/agent_f_integration_architect.md)
+> **Tuân thủ:** [Iron Rules](../principles/iron_rules.md) — đặc biệt R1 (Verbatim Injection), R3 (Zero-Fabrication), R4 (Traceability), R8 (Contract Lock).
+
+**Input:** `part_04.1_global_architecture.md` (HLD L1/L2 + ERD), `part_04.2_modular_deepdive.md`, `part_05_implementation_security.md`, [module_0_template.md](../templates/module_0_template.md)
+**Output trung gian:** `part_06_module0_draft.md`
+**Output thành phẩm (dual-write):**
+- Canonical: `{planning_artifacts}/00_system_connectivity_integration.md` (latest, overwrite)
+- Archive: `{planning_artifacts}/archive/00_system_connectivity_integration_v{N}.md` (snapshot history)
+
+---
+
+## MỤC TIÊU
+
+Xuất bản **Module 0** — bản đồ tích hợp hệ thống bất biến, gồm 2 phase nội bộ:
+- **Phase A — Connectivity Skeleton**: trích xuất ma trận kết nối + sơ đồ trình tự gốc từ HLD L1.
+- **Phase B — Integration Hardening**: tiêm Schema, Resilience, Security policies vào skeleton đã chốt.
+
+---
+
+## PHASE A — CONNECTIVITY MATRIX (Skeleton Extraction)
+
+### A.1. Ingest Input Context
+- **Biểu mẫu đích:** Đọc tệp [module_0_template.md](../templates/module_0_template.md) để nắm cấu trúc 7 phần bắt buộc.
+- **Dữ liệu nguồn:** Đọc `part_04.1_global_architecture.md` (Container Diagram L2 + ERD) và `part_04.2_modular_deepdive.md` (Sequence Diagrams).
+- Liệt kê toàn bộ các mũi tên giao tiếp giữa các Container.
+
+### A.2. Xây dựng Sơ đồ trình tự gốc
+- Vẽ sơ đồ Mermaid `sequenceDiagram` mô tả luồng Payload đi qua các module chính.
+- Sử dụng đúng tên các phân hệ đã định nghĩa ở L1/L2 (R5 — Consistency).
+
+### A.3. Lập Ma trận kết nối
+- Điền dữ liệu vào bảng Ma trận tại Mục 1 của [module_0_template.md](../templates/module_0_template.md).
+- **Payload Alignment**: Source/Target phải tương ứng với các thực thể trong ERD.
+- Ghi rõ giao thức (Protocol) theo đúng L1 (vd: gRPC, REST, Kafka topic name).
+- Nếu L1 chưa quy định Protocol → đánh dấu `[TBD]` (R3 — Zero-Fabrication).
+- **A-U4 — Edge↔Contract mapping (BẮT BUỘC):** với **mỗi cạnh service-to-service NỘI BỘ** (một service gọi một service khác trong hệ), ghi vào cột `INT-*` đúng **một** unit contract sở hữu cạnh đó. Nếu cạnh chưa có contract:
+    - Agent F **tạo mới** unit `INT-*` cho cạnh đó và ghi chú "cần bổ sung vào WBS" (contract này sẽ được khai ở `project_wbs.md` với `provider` + `consumers` tương ứng), **hoặc**
+    - đánh dấu cạnh là `external` / `no-contract` kèm **lý do** rõ ràng (vd: gọi hệ đối tác bên thứ ba, không phải cạnh nội bộ).
+    - **CẤM** để cạnh nội bộ không có contract mà không có lý do (đây là nguồn của "edge without owner" — cạnh không ai sở hữu).
+
+### A.4. Phase A Checkpoint
+- [ ] Số luồng kết nối khớp với số mũi tên (Rel) trong sơ đồ L2.
+- [ ] Mọi Container trong L2 xuất hiện trong ma trận (no missing node).
+- [ ] Không có entry "[Data]" hoặc placeholder runtime trong ma trận.
+- [ ] **Mọi cạnh nội bộ (service→service) có một `INT-*` sở hữu, HOẶC được đánh dấu `external`/`no-contract` kèm lý do** — không còn cạnh nội bộ không hợp đồng và không lý do (A-U4).
+
+---
+
+## PHASE B — INTEGRATION HARDENING (Policy Injection)
+
+### B.1. Lock & Ingest
+- Đọc lại Phase A output làm Metadata bất biến.
+- **Nghiêm cấm:** Không thay đổi Ma trận kết nối (Mục 1) và Sơ đồ trình tự (Mục 2). Nhiệm vụ duy nhất là tiêm dữ liệu vào các mục còn lại.
+
+### B.2. Master Data Modeling (ERD Consolidation)
+- Trích xuất và chi tiết hoá **Master Data Schema** từ ERD ở `part_04.1_global_architecture.md`.
+- ERD trong Module 0 phải là bản chi tiết hơn (Level 3) của ERD ở Step 4.1, đảm bảo tính nhất quán 100% về định danh thực thể (R5).
+- Thêm các Metadata trường bắt buộc: `trace_id`, `timestamp`.
+- Nếu không tìm thấy cấu trúc dữ liệu thô trong L1 → đánh dấu `[TBD]` (R3).
+
+### B.3. Apply Global Mesh Policies
+- Đặc tả: cơ chế xác thực (Auth), kháng lỗi (Resilience: retry/circuit breaker/timeout), bảng trạng thái toàn cục (States).
+- Đối chiếu với từng dòng trong Ma trận kết nối ở Phase A để thiết lập chính sách tương ứng (1-1 mapping).
+
+### B.4. Final Assembly & Dual-Write
+
+#### B.4.1. R8 Sync Check (BẮT BUỘC trước khi write)
+
+Agent F kiểm tra context invocation:
+- **Case 1 — Cascade từ HLD update (Step 07 trigger):** Cho phép write (Module 0 phải sync theo HLD mới).
+- **Case 2 — Reconcile drift (Module 0 hiện tại không khớp HLD canonical):** Cho phép write để đồng nhất.
+- **Case 3 — Edit độc lập (HLD không đổi, Module 0 vẫn khớp):** **REJECT** theo R8. Báo user: "Module 0 đã khớp HLD và HLD chưa update — không có lý do để bump version. Nếu cần thay đổi Schema/Protocol, hãy update HLD ở Stage 2 trước, Module 0 sẽ cascade theo."
+
+#### B.4.2. Merge content
+- Kết hợp dữ liệu mới vào các Mục 3, 4, 5, 6, 7 của bản mẫu [module_0_template.md](../templates/module_0_template.md).
+- **Ghi vết draft:** Lưu bản thảo gộp tại `{intermediate_folder}/part_06_module0_draft.md`.
+
+#### B.4.3. Dual-Write (chỉ thực hiện khi B.4.1 PASS)
+
+1. `mkdir -p {planning_artifacts}/archive/` (idempotent).
+2. Detect `N_next`: list `{planning_artifacts}/archive/00_system_connectivity_integration_v*.md` → `max(N) + 1`.
+3. Ghi 2 file:
+    - Canonical: `{planning_artifacts}/00_system_connectivity_integration.md` (overwrite).
+    - Archive: `{planning_artifacts}/archive/00_system_connectivity_integration_v{N_next}.md` (new snapshot).
+
+---
+
+## EXIT CRITERIA (Done = đủ tất cả)
+
+- [ ] `part_06_module0_draft.md` chứa cả Phase A + Phase B.
+- [ ] **R8 Sync Check** (B.4.1) đã PASS — write được phép vì cascade từ HLD update HOẶC reconcile drift.
+- [ ] Canonical `{planning_artifacts}/00_system_connectivity_integration.md` đã ghi (overwrite latest).
+- [ ] Archive `{planning_artifacts}/archive/00_system_connectivity_integration_v{N_next}.md` đã tạo.
+- [ ] **Sanity Check**: ERD trong tệp này khớp hoàn toàn với danh mục thực thể đã dùng trong HLD L2 (R5).
+- [ ] Báo cáo xác nhận: "Đã trích xuất chính xác X luồng kết nối từ HLD L1".
+- [ ] Không còn placeholder Template, ngoại trừ `[TBD]` có lý do rõ ràng.
+
+---
+
+## ⛔ [GATE — R8 Sync Check] (đặt TRƯỚC Next)
+
+Dual-write Module 0 chỉ thực hiện khi **R8 Sync Check (B.4.1) PASS** (cascade từ HLD update HOẶC reconcile drift). Case 3 (edit độc lập, HLD chưa đổi) → **REJECT**, KHÔNG đi tiếp. PASS → đã ghi canonical + archive → sang Step 07 assembly.
+
+**Next:** Read fully and follow `./step-07-assembly.md`

package/skills/NTAPP/.agent/skills/NTAPP-architecture-design/steps/step-07-assembly.md

@@ -0,0 +1,168 @@
+# STEP 07: MERGE, QA & FINALIZE
+
+> **Acting as:** [Agent E — Master Orchestrator](../agents/agent_e_orchestrator.md)
+> **Tuân thủ:** [Iron Rules](../principles/iron_rules.md) — đặc biệt R1 (Verbatim Injection), R2 (Zero-Summarization), R4 (Traceability), R6 (Quantitative Audit Gate).
+> ⛔ **Đây là step cuối (TERMINAL) — KHÔNG có `**Next:**`.** Cổng cuối = G4 Quantitative Audit + trình bày HLD cho người dùng. (Cascade Module 0 sync ở §7.5.4 là re-run R8, KHÔNG phải pointer pipeline.)
+
+**Input:** Tất cả file `part*.md` trong thư mục `architecture_design_parts/`
+**Output (dual-write):**
+- Canonical: `{planning_artifacts}/architecture_design.md` (latest, overwrite mỗi run)
+- Archive: `{planning_artifacts}/archive/architecture_design_v{N}.md` (snapshot history, version mới mỗi run)
+
+---
+
+Hợp nhất toàn bộ output từ các Agent A, B, C, D thành một tài liệu HLD duy nhất, nhất quán và đầy đủ.
+
+---
+
+## QUY TRÌNH THỰC THI "FFT ASSEMBLY" (5-PHASE — phase nội bộ của Step 07, không phải global pass)
+
+### GIAI ĐOẠN 1: INITIALIZATION (Khởi tạo khung HLD)
+- **Hành động:** Sử dụng `architecture_design_final_template.md` để tạo file HLD mới.
+- **Nhiệm vụ:**
+    - Thiết lập tiêu đề dự án.
+    - Hoàn thiện bảng **Document History**.
+    - Khởi tạo bảng **Architecture Audit Matrix** để đối soát WBS ID (SSoT).
+
+### GIAI ĐOẠN 2: STRATEGY & NFR INJECTION (Bơm bối cảnh)
+- **Hành động:** Bơm nội dung từ `part_02_context_strategy.md` vào Mục 1 và Mục 2 của HLD.
+- **Yêu cầu:** Giữ nguyên bảng NFR và các bullet points của System Thinking.
+
+### GIAI ĐOẠN 3: ARCHITECTURE DEEP-DIVE INJECTION (Bơm kiến trúc)
+- **Hành động:** Bơm nội dung vào Mục 3 theo thứ tự sau:
+    1. **§3.1.x** (Phân lớp, C4 L1/L2, ERD, Framework) ← từ `part_04.1_global_architecture.md` verbatim.
+    2. **§3.2.0 (Function Decomposition Tree + Coverage Matrix)** ← từ `project_wbs.md` verbatim (bê nguyên cả Tree ASCII + Bảng 4 cột). Đây là single source — KHÔNG đọc từ part_04.2.
+    3. **§3.2.1+ (Mô hình tổng thể, Sequence/Data Flow per module)** ← từ `part_04.2_modular_deepdive.md` verbatim, bắt đầu từ §3.2.1 (part_04.2 không được chứa §3.2.0 — xem step-04.2).
+- **TỐI QUAN TRỌNG:**
+    - Sơ đồ C4 Level 1 (Context).
+    - Sơ đồ C4 Level 2 (Container with DMZ/Internal boundary).
+    - Toàn bộ Sequence Diagrams cho từng Module trọng yếu.
+    - Cấm tuyệt đối việc bỏ bớt Loop/Alt trong Sequence Diagram.
+
+### GIAI ĐOẠN 4: IMPLEMENTATION & SOLUTIONS INJECTION (Bơm thực thi)
+- **Hành động:** Bơm nội dung từ `part_05_implementation_security.md` vào Mục 4 và Mục 5.
+- **Yêu cầu:** Bê nguyên xi ASCII Project Tree và các bảng ATTT (Zoning), Caching, Sharding.
+
+### GIAI ĐOẠN 5: QUANTITATIVE AUDIT & ADR (Đối soát định lượng)
+- **Hành động:** Thực hiện kiểm toán tài liệu cuối cùng.
+- **Chỉ tiêu đối soát (Audit Checklist):**
+    - [ ] **WBS Injection (verify)**: §3.2.0 của HLD đã chứa cả Function Decomposition Tree (ASCII) + Coverage Matrix bảng 4 cột, copy verbatim từ `project_wbs.md` (write action thực hiện ở Giai đoạn 3, mục này chỉ verify).
+    - [ ] **Data Integrity**: Đối soát tất cả Object/Table trong Sequence và Data Flow (phần 3.2.2) với sơ đồ ERD (phần 3.1.3). Nếu phát hiện thực thể 'ngoài luồng' -> Agent E phải yêu cầu Agent C cập nhật lại ERD.
+    - [ ] **No Orphan Entities**: Đảm bảo 100% thực thể trong ERD đều có quan hệ (arrow), không có thực thể đứng độc lập.
+    - [ ] **Data Consistency**: Đảm bảo sơ đồ ERD trong tài liệu HLD chính (3.1.3) khớp 100% với ERD trong tài liệu Tích hợp hệ thống (Module 0).
+    - [ ] **Code-to-Design Mapping:** Kiểm tra tính logic giữa Folder Path trong phần 4.1 và Modules đã khai báo.
+    - [ ] **Diagram Count:** Tổng số sơ đồ Mermaid trong HLD phải khớp 100% với tổng số sơ đồ trong các file thô.
+    - [ ] **ADR Integrity:** Có ít nhất 3 bản ghi ADR được tổng hợp tại Mục 6.
+    - [ ] **WBS Traceability:** Mọi ID tính năng (vd: `RAG-01`) phải xuất hiện ít nhất một lần trong sơ đồ Sequence hoặc Data Flow kỹ thuật tại Mục 3.2.0.
+- **Xử lý hụt:** Nếu số lượng sơ đồ/bảng không khớp -> Agent E PHẢI thực hiện `replace_file_content` để bơm lại đoạn bị thiếu.
+
+---
+
+### 7.3 Tổng hợp ADR (Architectural Decision Records)
+Quét toàn bộ các file intermediate để thu thập các quyết định kiến trúc quan trọng. Mỗi quyết định lớn (chọn DB, chọn pattern, chọn giao thức) phải có 1 ADR entry:
+
+```markdown
+### ADR-{XXX}: {Tiêu đề quyết định}
+- **Ngày:** {YYYY-MM-DD}
+- **Bối cảnh:** {Vấn đề cần giải quyết — trích xuất từ NFR hoặc Tech Proposal}
+- **Các phương án đã xem xét:** {A: ..., B: ..., C: ...}
+- **Quyết định:** {Phương án được chọn}
+- **Lý do:** {Lý do kỹ thuật, liên kết với NFR cụ thể}
+- **Hệ quả (Consequences):** {Điều gì sẽ thay đổi khi áp dụng quyết định này}
+```
+
+**Số lượng ADR tối thiểu:** 3 entries (Tech Stack chính, DB chính, Pattern chính).
+
+---
+
+### 7.4 Merge Final HLD Document
+Hợp nhất theo đúng cấu trúc của `architecture_design_final_template.md`:
+
+```markdown
+# TÀI LIỆU THIẾT KẾ KIẾN TRÚC TỔNG THỂ: {Tên dự án}
+
+## BẢNG GHI NHẬN THAY ĐỔI
+{Điền metadata: date, version, change description}
+
+## 1. GIỚI THIỆU & PHÂN TÍCH CHIẾN LƯỢC
+{Nội dung từ part_02_context_strategy.md - BẮT BUỘC COPY 1:1}
+
+## 2. KIẾN TRÚC ỨNG DỤNG
+{Nội dung từ part_04.1_global_architecture.md & part_04.2_modular_deepdive.md - BẮT BUỘC COPY 1:1}
+
+## 3. CHIẾN LƯỢC TRIỂN KHAI VẬT LÝ & GIẢI PHÁP
+{Nội dung từ part_05_implementation_security.md - BẮT BUỘC COPY 1:1}
+
+## 4. NHẬT KÝ QUYẾT ĐỊNH KIẾN TRÚC (ADR)
+{Các ADR entries được tổng hợp ở bước 6.3}
+
+```
+
+**Quy tắc merge:**
+- KHÔNG lược bỏ bất kỳ nội dung nào từ các file intermediate.
+- KHÔNG thay đổi số liệu hoặc thuật ngữ — chỉ ghép nối.
+- Kiểm tra tính nhất quán: tên Container ở Section 3 phải khớp chính xác với tên Folder ở Section 4.
+- Bảng BẢNG GHI NHẬN THAY ĐỔI phải điền: ngày hôm nay, version, "Khởi tạo HLD bởi Multi-Agent System".
+
+---
+
+### 7.5 Dual-Write Output (Canonical + Archive)
+
+Agent E PHẢI thực hiện 4 bước sau:
+
+1. **Tạo archive folder** (idempotent):
+   ```
+   mkdir -p {planning_artifacts}/archive/
+   ```
+
+2. **Detect next version number `N_next`:**
+   - List existing archive: `ls {planning_artifacts}/archive/architecture_design_v*.md`
+   - Parse `v{N}` từ tên file → `N_next = max(N) + 1` (hoặc `1` nếu archive rỗng).
+
+3. **Ghi 2 file (cùng nội dung HLD đã merge):**
+   - **Canonical:** `{planning_artifacts}/architecture_design.md` (overwrite — latest pointer).
+   - **Archive:** `{planning_artifacts}/archive/architecture_design_v{N_next}.md` (new snapshot).
+
+4. **Cascade Module 0 sync (R8 logic mới):**
+   - Vì HLD vừa update, Module 0 BẮT BUỘC re-run Step 06 để cập nhật theo HLD mới.
+   - Agent E auto-trigger Step 06 nếu phát hiện HLD changed (so sánh nội dung canonical với archive v{N_next - 1} nếu có).
+
+---
+
+### 7.6 Trình bày kết quả cho người dùng
+Sau khi ghi file thành công, Agent E hiển thị tóm tắt:
+
+```markdown
+## ✅ HOÀN THÀNH — Thiết kế Kiến trúc Tổng thể (HLD)
+
+**Canonical (latest):** `{planning_artifacts}/architecture_design.md`
+**Archive (v{N_next}):** `{planning_artifacts}/archive/architecture_design_v{N_next}.md`
+
+**Tóm tắt:**
+- Section 1: {N} thuật ngữ, {N} tài liệu tham khảo
+- Section 2: {N} NFR được xác định
+- Section 3: {N} Containers, {N} nodes luồng Inbound, {N} nodes luồng Query
+- Section 4: {N} Epics được mapping vào folder structure
+- Section 5: {N} cơ chế ATTT, Caching TTL = {X}h
+- Section 6 (ADR): {N} quyết định kiến trúc được ghi lại
+
+**Cảnh báo (nếu có):**
+- {Danh sách các NFR chưa xác định để người dùng theo dõi}
+
+---
+Bạn có muốn điều chỉnh phần nào hoặc bắt đầu tạo Tech Spec tiếp theo không?
+```
+
+---
+
+## ĐIỀU KIỆN HOÀN THÀNH (Done Criteria)
+
+- [ ] QA Checklist tất cả sections PASS.
+- [ ] ADR có ít nhất 3 entries.
+- [ ] Canonical `{planning_artifacts}/architecture_design.md` đã ghi (overwrite latest).
+- [ ] Archive `{planning_artifacts}/archive/architecture_design_v{N_next}.md` đã tạo.
+- [ ] Module 0 đã được cascade re-run (Step 06) nếu HLD content đã thay đổi.
+- [ ] Tóm tắt kết quả đã được hiển thị cho người dùng.
+- [ ] File `architecture_design_parts/` intermediate có thể được giữ lại để audit sau.
+
+**🎉 KẾT THÚC WORKFLOW — Architecture Design hoàn thành.**