sys-analysis-design/.claude/skills/sa-3-enablement/templates/architecture-guidelines.md

# AGD — Architecture Guidelines — <PROJECT>

| | |
|---|---|
| **Version** | 1.0 |
| **Date** | YYYY-MM-DD |
| **Author** | <SA> (skill sa-3-enablement) |
| **Status** | 🟡 Draft |
| **Approved by** | Tech Lead: — |
| **Source** | SAD_… v1.0 · ADR-001..0nn · ICD_… v1.0 · FAIL_… v1.0 |
| **Scope** | |
| **Confidence** | 🟢 |

## Change Log

| Version | Date | Người sửa | Thay đổi | ADR |
|---|---|---|---|---|
| 1.0 | | | Bản đầu | — |

> **Tài liệu này chỉ chứa thứ truy được về một `ADR` hoặc `QAS`.** Quy ước đặt tên biến, thứ
> tự import, độ dài hàm thuộc Tech Lead và nằm ở tài liệu khác. Trộn hai loại làm dev ngừng
> phân biệt cái nào quan trọng.

---

## 1. Đọc gì trước

| Bạn là | Đọc theo thứ tự |
|---|---|
| Dev mới vào dự án | §2 → reference implementation → `SAD` §4 |
| Dev thêm một tính năng | §3 (ràng buộc) → `ICD` cho interface liên quan |
| Dev sửa một bug | §4 (đường lỗi) → `FAIL` |
| Người review PR | §3 + bảng `FIT` |

## 2. Reference implementation

| | |
|---|---|
| **Đường dẫn** | `<repo>/<module mẫu>` |
| **Chạy thử** | `<lệnh>` |
| **Thể hiện các quyết định** | `ADR-002`, `ADR-004`, `ADR-007` |

Module mẫu thể hiện đủ sáu thứ. Thiếu thứ nào thì dev sẽ tự bịa thứ đó:

| # | Thể hiện | Ở file nào |
|---|---|---|
| 1 | Cấu trúc module chuẩn | |
| 2 | Xử lý lỗi + mã lỗi theo `ICD` §3 | |
| 3 | Log có correlation id | |
| 4 | Gọi phụ thuộc ngoài có timeout/retry theo `FAIL` | |
| 5 | Kiểm tra quyền theo `SEC` §3 | |
| 6 | Kiểm thử ở đủ các mức | |

🔴 **Code luôn thắng văn bản về khả năng được đọc.** Mọi thứ giải thích dài hơn 10 dòng nên
chuyển thành code mẫu.

## 3. Ràng buộc kiến trúc

*Bốn cột bắt buộc. Ràng buộc không có nguồn là sở thích cá nhân, và team sẽ nhận ra.*

### 3.1 Ranh giới module & phụ thuộc

| # | Ràng buộc | Nguồn | Ví dụ đúng / sai | Cách kiểm |
|---|---|---|---|---|
| 1 | Tầng domain không import tầng infra | `ADR-002` | ✅ `domain/Order.ts` không import `infra/` · ❌ import `infra/db` | `FIT-01` |
| 2 | Module chỉ giao tiếp qua interface công khai | `ADR-004` | | `FIT-02` |

### 3.2 Dữ liệu

| # | Ràng buộc | Nguồn | Ví dụ đúng / sai | Cách kiểm |
|---|---|---|---|---|
| | Chỉ hệ thống chủ được ghi thực thể X | `DAT` §1 | | |
| | Truy vấn danh sách phải có phân trang | `QAS-001` | | |
| | Không dùng dữ liệu production ở non-prod | `SEC` §5 | | `FIT-nn` |

### 3.3 Interface & contract

| # | Ràng buộc | Nguồn | Ví dụ đúng / sai | Cách kiểm |
|---|---|---|---|---|
| | Số lớn (id, tiền) truyền dạng `string` | `ICD` §1 | ✅ `"1234567890123456789"` · ❌ `1234567890123456789` | `FIT-nn` |
| | Thời gian dùng ISO-8601 UTC | `ICD` §1 | | |
| | Lỗi nghiệp vụ trả HTTP 4xx | `ICD` §1 | ❌ 200 kèm `{success:false}` | |
| | Đổi contract breaking phải qua `ADR` | `ICD` §3 | | `FIT-nn` (Pact) |

### 3.4 Bảo mật

| # | Ràng buộc | Nguồn | Ví dụ đúng / sai | Cách kiểm |
|---|---|---|---|---|
| | Không có secret trong mã nguồn | `SEC` §6 | | `FIT-nn` |
| | Kiểm quyền ở tầng service, không chỉ ở gateway | `SEC` §3 | | ⚠️ Khuyến nghị |
| | Không log dữ liệu PII | `SEC` §5 | | ⚠️ Khuyến nghị |

### 3.5 Ràng buộc chỉ là khuyến nghị

*Quy tắc `D8`: không kiểm tự động được ⇒ phải ghi nhãn, kèm cách kiểm thủ công.*

| Ràng buộc | Vì sao không tự kiểm được | Kiểm thủ công thế nào | Tần suất |
|---|---|---|---|

---

## 4. Đường lỗi — dev phải làm gì

*Trích từ `FAIL`. Đây là chỗ dev hay tự bịa nhất, nên viết cực cụ thể.*

| Gọi tới | Timeout | Retry | Idempotent | Hết retry | Người dùng thấy gì |
|---|---|---|---|---|---|
| CSDL chính | … ms | 0 | — | trả 503 | |
| API ngoài … | … ms | 3 · mũ + jitter | ✅ khoá … | vào hàng đợi | |

**Mẫu code chuẩn:** `<đường dẫn trong reference implementation>`

🔴 **Không tự đặt timeout.** Ngân sách timeout theo tầng ở `FAIL` §2 — đặt sai một tầng làm
sai cả chuỗi.

## 5. Log, metric, trace

| | Quy tắc | Nguồn |
|---|---|---|
| Định dạng log | JSON, các trường bắt buộc: `ts`, `level`, `correlationId`, `service`, `msg` | `SAD` §9 |
| Correlation id | lấy từ header `…`, truyền xuống mọi lời gọi | `SAD` §9 |
| Mức log | `error` cho lỗi cần người xử lý · `warn` cho lỗi tự hồi phục | |
| **Cấm log** | PII, secret, toàn bộ request body | `SEC` §5 |
| Metric bắt buộc mỗi endpoint | số request, tỉ lệ lỗi, phân vị độ trễ | `QAS` |

## 6. Kiểm thử

| Mức | Kiểm gì | Bắt buộc khi nào | Ngưỡng |
|---|---|---|---|
| Đơn vị | logic nghiệp vụ thuần | mọi rule trong `BR` của BA | |
| Tích hợp | ranh giới với CSDL/hàng đợi | mọi repository | |
| Contract | `IF-nnn` không đổi breaking | mọi interface công khai | `FIT-nn` |
| Hiệu năng | `QAS` mức Must | trước mỗi release | `FIT-nn` |

## 7. Khi nào phải hỏi SA

*Ranh giới rõ ràng giúp team không bị chặn, và SA không thành nút thắt.*

| Tình huống | Quyết định bởi |
|---|---|
| Đặt tên, cấu trúc thư mục trong module, chọn thư viện tiện ích | **Dev / Tech Lead** — không cần hỏi |
| Thêm một bảng vào CSDL của chính module mình | Tech Lead |
| Thêm một endpoint theo đúng chuẩn `ICD` | Tech Lead |
| Gọi trực tiếp dữ liệu của module khác | **Hỏi SA** — chạm `ADR-004` |
| Thêm một phụ thuộc hạ tầng mới (cache, queue, dịch vụ ngoài) | **Hỏi SA** |
| Đổi contract công khai theo hướng breaking | **Hỏi SA** — cần `ADR` |
| Bỏ qua một ràng buộc ở §3 vì gấp | **Hỏi SA** — thành `TD-nn` có hạn |

Chấm nhanh: `../../sa-lifecycle/references/decision-radar.md` §2. Điểm ≥ 5 ⇒ hỏi SA.

## 8. Ngoài phạm vi

*Những gì tài liệu này KHÔNG quy định:*

- Quy ước đặt tên, format code, độ dài hàm ⟶ tài liệu của Tech Lead
- Quy trình Git, đặt tên nhánh, mẫu commit ⟶ tài liệu quy trình
- Thiết kế giao diện, design system ⟶ tài liệu thiết kế

## 9. Open Questions

| ID | Câu hỏi | Hỏi ai | Từ ngày | Chặn gì |
|---|---|---|---|---|