init git

.claude/skills/sa-2-architecture/templates/sad.md

@@ -0,0 +1,186 @@
+# SAD — Solution Architecture Document — <PROJECT>
+
+| | |
+|---|---|
+| **Version** | 1.0 |
+| **Date** | YYYY-MM-DD |
+| **Author** | <SA> (skill sa-2-architecture) |
+| **Status** | 🟡 Draft |
+| **Approved by** | Tech Lead: — · Security: — · SRE: — |
+| **Source** | CTX_… v1.0 · OPT_… v1.0 · QAS_… v1.0 |
+| **Scope** | |
+| **Confidence** | 🟡 |
+
+## Change Log
+
+| Version | Date | Người sửa | Thay đổi | ADR |
+|---|---|---|---|---|
+| 1.0 | | | Bản đầu | — |
+
+> **Thẩm quyền khi mâu thuẫn:** sơ đồ thắng về **quan hệ và luồng** (ai gọi ai, thứ tự nào);
+> bảng/văn bản thắng về **ràng buộc và con số** (timeout, quyền, định dạng, giới hạn).
+> Mâu thuẫn ngoài hai loại trên là lỗi tài liệu, phải sửa chứ không phải chọn bên.
+
+---
+
+## 1. Tóm tắt cho người quyết định
+
+*Năm câu. Đọc xong biết hệ thống gồm mấy khối, khối nào rủi ro nhất, quyết định lớn nhất là gì.*
+
+| | |
+|---|---|
+| **Kiểu kiến trúc** | *(modular monolith / service theo bounded context / event-driven / hybrid)* |
+| **Quyết định lớn nhất** | `ADR-nnn` — |
+| **Rủi ro kiến trúc lớn nhất** | `ARISK-nn` — |
+| **Cái này KHÔNG làm được** | *(giới hạn đã biết trước, ghi ra để không ai kỳ vọng sai)* |
+
+## 2. Kiểu kiến trúc và lý do
+
+Quyết định ở `ADR-001`. Tóm tắt lý do gắn với `ASR` và `CON`:
+
+| Tín hiệu trong dự án này | Nghiêng về | Kết luận |
+|---|---|---|
+| `CON-04`: … team, ai release độc lập với ai | | |
+| `ASR-…`: tải lệch giữa các phần | | |
+| `CON-04`: năng lực đội vận hành | | |
+
+🔴 **Modular monolith là mặc định hợp lý** cho ≤ 2 team và ranh giới nghiệp vụ chưa ổn định.
+Tách service là quyết định phải *thắng* một lập luận, không phải điểm khởi đầu.
+
+---
+
+## 3. C4 — Mức 1: System Context
+
+*Ai dùng hệ thống, hệ thống nói chuyện với cái gì bên ngoài. Không có chi tiết bên trong.*
+
+```mermaid
+flowchart LR
+```
+
+**Legend:** ▭ hệ thống của ta · ▱ hệ thống ngoài · ○ người dùng ·
+──▶ đồng bộ (ghi giao thức trên mũi tên) · ┄▶ bất đồng bộ
+
+| Thực thể ngoài | Vai trò | Ai sở hữu | Giao thức | SLA của họ | `IF-nnn` |
+|---|---|---|---|---|---|
+
+---
+
+## 4. C4 — Mức 2: Container
+
+*Các khối chạy được và triển khai được (ứng dụng, CSDL, hàng đợi, job). Đây là sơ đồ dev dùng
+nhiều nhất.*
+
+```mermaid
+flowchart TB
+```
+
+**Legend:** *(bắt buộc — mũi tên không nhãn giao thức và không phân biệt sync/async là mũi tên
+trang trí)*
+
+### 4.1 Bảng container/component — `CMP-nn`
+
+| ID | Tên | Trách nhiệm *(một câu)* | **Cái nó KHÔNG làm** | Dữ liệu sở hữu | Interface vào | Interface ra | Team | `ASR` ép ra |
+|---|---|---|---|---|---|---|---|---|
+| `CMP-01` | | | | | `IF-001` | `IF-004` | | `ASR-001` |
+
+🔴 **Cột "cái nó KHÔNG làm" là cột ngăn phình chức năng.** Component không có ranh giới viết
+ra sẽ nuốt dần mọi thứ trong 6 tháng.
+
+🔴 Component không phục vụ `ASR` nào và không có nhu cầu chức năng rõ ⇒ hỏi lại vì sao nó tồn tại.
+
+### 4.2 Ranh giới thay đổi
+
+*Thay đổi loại nào chỉ chạm một container? Loại nào chạm nhiều? Đây là thước đo chất lượng
+của cách phân rã.*
+
+| Loại thay đổi hay xảy ra | Chạm những container nào | Có chấp nhận được không |
+|---|---|---|
+| Thêm một loại báo cáo | | |
+| Thêm một kênh thanh toán | | |
+| Đổi quy tắc tính phí | | |
+
+Một loại thay đổi thường xuyên mà chạm ≥ 3 container ⇒ phân rã đang cắt sai chỗ.
+
+---
+
+## 5. C4 — Mức 3: Component *(chỉ cho container phức tạp nhất)*
+
+*Không vẽ mức này cho mọi container. Vẽ cho cái khó nhất, để dev có mẫu.*
+
+```mermaid
+flowchart TB
+```
+
+---
+
+## 6. Luồng chính
+
+*Sequence diagram cho 2–4 luồng quan trọng nhất. Mỗi luồng ghi rõ: đồng bộ hay bất đồng bộ,
+timeout ở đâu, giao dịch bắt đầu và kết thúc ở đâu.*
+
+### 6.1 <tên luồng>
+
+```mermaid
+sequenceDiagram
+```
+
+| Bước | Thành phần | Đồng bộ? | Timeout | Lỗi thì sao | `FAIL` |
+|---|---|---|---|---|---|
+
+---
+
+## 7. Deployment view
+
+*Cái gì chạy ở đâu, mấy bản, ranh giới mạng, ranh giới tin cậy.*
+
+```mermaid
+flowchart TB
+```
+
+| Thành phần | Môi trường | Số bản | Cấu hình | Vùng/AZ | Ranh giới tin cậy |
+|---|---|---|---|---|---|
+
+**Ranh giới tin cậy** — nơi dữ liệu đi từ vùng ít tin cậy sang vùng tin cậy hơn. Mỗi ranh giới
+phải có kiểm tra đầu vào; liệt kê ở `SEC`.
+
+---
+
+## 8. Quyết định kiến trúc đã ghi
+
+| `ADR` | Quyết định | Trạng thái | Điểm radar | Có POC |
+|---|---|---|---|---|
+| `ADR-001` | Kiểu kiến trúc | Accepted | 9 | POC-01 ✅ |
+
+*Sổ đầy đủ: `../00-index/ADL_<PROJECT>.md`*
+
+## 9. Mối quan tâm xuyên suốt
+
+*Những thứ mọi component đều phải làm giống nhau — không thống nhất ở đây thì mỗi dev một kiểu.*
+
+| Mối quan tâm | Quyết định | Ở đâu | `ADR` |
+|---|---|---|---|
+| Định dạng log & correlation id | | `AGD` | |
+| Xử lý lỗi & mã lỗi | | `ICD` | |
+| Xác thực & phân quyền | | `SEC` | |
+| Cấu hình & secret | | `SEC`, `INF` | |
+| Múi giờ & định dạng thời gian | | `ICD` | |
+| Số lớn (id/tiền) | | `ICD` | |
+| Đa ngôn ngữ | | | |
+| Idempotency | | `ICD`, `FAIL` | |
+
+## 10. Giả định & Ngoài phạm vi
+
+**Giả định:**
+
+| ID | Giả định | Cách xác minh | Nếu sai |
+|---|---|---|---|
+
+**Ngoài phạm vi** *(quy tắc `D11` — những thứ người đọc có thể tưởng là có)*:
+
+- *(ví dụ: không hỗ trợ đa vùng; DR dựa trên khôi phục từ backup, RTO 4 giờ)*
+- *(ví dụ: không nhắm tới tải × 100 — ngưỡng xét lại: … giao dịch/giờ)*
+
+## 11. Open Questions
+
+| ID | Câu hỏi | Hỏi ai | Từ ngày | Chặn gì | Hệ quả nếu trả lời ngược |
+|---|---|---|---|---|---|