130 lines
7.1 KiB
Markdown
130 lines
7.1 KiB
Markdown
# Radar quyết định — cái gì cần ADR, cái gì không
|
||
|
||
Câu hỏi khó nhất của nghề SA không phải "quyết thế nào" mà "cái này có phải việc của tôi
|
||
không". Tài liệu này chốt ngưỡng đó, để skill và người dùng không tranh cãi mỗi lần.
|
||
|
||
## 1. Phép thử một câu
|
||
|
||
> Quyết định sai, sửa mất **≤ 2 ngày** → không phải việc của SA. Ghi `DEC-nn` là đủ.
|
||
> Sai mà sửa mất **≥ 4 tuần**, hoặc phải **migrate dữ liệu**, hoặc phải **đổi contract công
|
||
> khai** → bắt buộc `ADR`.
|
||
> Ở giữa → dùng bảng chấm điểm §2.
|
||
|
||
## 2. Bảng chấm điểm
|
||
|
||
Chấm 5 tiêu chí, mỗi tiêu chí 0–2 điểm.
|
||
|
||
| # | Tiêu chí | 0 điểm | 1 điểm | 2 điểm |
|
||
|---|---|---|---|---|
|
||
| 1 | **Chi phí đảo ngược** | < 2 ngày | 1–3 tuần | > 4 tuần hoặc phải migrate dữ liệu |
|
||
| 2 | **Bán kính ảnh hưởng** | Trong một module | Nhiều module cùng team | Nhiều team / hệ thống ngoài / khách hàng |
|
||
| 3 | **Chạm thuộc tính chất lượng** | Không | Ảnh hưởng gián tiếp | Quyết định trực tiếp một `QAS` mức Must |
|
||
| 4 | **Ràng buộc dài hạn** | Đổi lúc nào cũng được | Ràng trong một release | Ràng buộc ≥ 1 năm (license, vendor, mô hình dữ liệu) |
|
||
| 5 | **Tranh cãi** | Cả team đồng ý ngay | Có ý kiến khác | Đã tranh luận ≥ 2 lần hoặc có bên phản đối |
|
||
|
||
| Tổng | Xử lý |
|
||
|---|---|
|
||
| **0–2** | Không ghi gì. Là quyết định thi công, thuộc Tech Lead/Dev |
|
||
| **3–4** | Ghi `DEC-nn` trong `00-index/` — một dòng, không cần ADR |
|
||
| **5–7** | **`ADR` bắt buộc** |
|
||
| **8–10** | `ADR` + phải có POC hoặc bài đo trước khi chuyển `Accepted` |
|
||
|
||
🔴 Tiêu chí 5 hay bị coi thường. Một quyết định team đã cãi nhau hai lần mà không ai ghi lại
|
||
sẽ được cãi lại lần thứ ba, thứ tư — chi phí thật nằm ở đó, không nằm ở kỹ thuật.
|
||
|
||
## 3. Danh mục quyết định thường đạt ngưỡng ADR
|
||
|
||
Dùng làm checklist rà soát: dự án nào cũng nên trả lời được từng dòng, hoặc bằng một ADR,
|
||
hoặc bằng câu "không áp dụng vì …".
|
||
|
||
### Cấu trúc hệ thống
|
||
|
||
- Kiểu kiến trúc tổng thể (modular monolith / microservices / serverless / hybrid)
|
||
- Ranh giới service — cắt theo đâu, vì sao (thường là quyết định đắt nhất cả dự án)
|
||
- Đồng bộ hay bất đồng bộ giữa các thành phần lõi
|
||
- Có event bus / message broker không, loại nào
|
||
- Chiến lược multi-tenant (chung DB / chung schema / tách schema / tách DB)
|
||
|
||
### Dữ liệu
|
||
|
||
- Loại CSDL chính và vì sao (quan hệ / tài liệu / khoá-giá trị / cột / đồ thị)
|
||
- Ai là single source of truth cho từng thực thể lõi
|
||
- Consistency model: mạnh hay eventual, eventual thì trễ tối đa bao nhiêu
|
||
- Cơ chế giao dịch xuyên service (saga / outbox / 2PC / không có)
|
||
- Chiến lược migration dữ liệu legacy, cách rollback
|
||
- Sharding / partitioning, khoá phân mảnh
|
||
- Retention và xoá dữ liệu cá nhân (ràng buộc pháp lý)
|
||
|
||
### Tích hợp
|
||
|
||
- Kiểu contract công khai (REST / GraphQL / gRPC / event)
|
||
- Chính sách versioning và thời gian hỗ trợ phiên bản cũ
|
||
- Idempotency: khoá là gì, giữ bao lâu
|
||
- Cách xử lý khi hệ thống ngoài hỏng (degrade / hàng đợi / từ chối)
|
||
|
||
### Bảo mật
|
||
|
||
- Mô hình xác thực (session / JWT / OAuth2 / mTLS) và nơi giữ trạng thái
|
||
- Mô hình phân quyền (RBAC / ABAC / kết hợp) và **chỗ ra quyết định** (gateway hay service)
|
||
- Quản lý secret và xoay khoá
|
||
- Phân loại dữ liệu nhạy cảm và ranh giới mã hoá
|
||
- Mô hình audit log: ghi gì, giữ bao lâu, ai đọc được
|
||
|
||
### Hạ tầng & vận hành
|
||
|
||
- Cloud/vùng, và có ràng buộc dữ liệu phải nằm trong lãnh thổ không
|
||
- Mô hình chạy (VM / container / K8s / PaaS / serverless)
|
||
- Chiến lược HA và DR kèm RTO/RPO
|
||
- Chiến lược release (blue-green / canary / rolling) và cách rollback
|
||
- Bộ observability và nơi giữ log, chi phí kèm theo
|
||
|
||
### Frontend *(khi giải pháp có giao diện)*
|
||
|
||
- SPA / SSR / hybrid và lý do gắn với `QAS` (SEO, thời gian hiển thị đầu, thiết bị yếu)
|
||
- Chiến lược trạng thái và cache phía client
|
||
- Cách xử lý số lớn (`id`/số tiền vượt `2^53`) xuyên suốt tầng giao diện
|
||
- Chiến lược đa ngôn ngữ và nơi giữ chuỗi hiển thị
|
||
|
||
## 4. Cái KHÔNG nên viết ADR
|
||
|
||
Viết ADR cho những thứ này làm loãng sổ quyết định, và người đọc sẽ ngừng đọc:
|
||
|
||
| Không ADR | Vì sao | Ghi ở đâu |
|
||
|---|---|---|
|
||
| Chọn thư viện tiện ích (date, lodash…) | Thay được trong một buổi chiều | Không ghi, hoặc `AGD` |
|
||
| Quy ước đặt tên, format code | Không phải quyết định kiến trúc | `AGD` |
|
||
| Cấu trúc thư mục trong một module | Bán kính hẹp | `AGD` |
|
||
| Chọn màu, spacing, component UI | Thuộc design system | Tài liệu thiết kế |
|
||
| "Dùng interface hay abstract class" | Quyết định thi công | Code review |
|
||
| Bug fix, tối ưu cục bộ | Không ràng buộc gì về sau | Commit message |
|
||
|
||
🔴 **Ngoại lệ:** một quyết định nhỏ trở thành ADR khi nó **thiết lập tiền lệ**. "Dùng thư viện
|
||
X" là nhỏ; "mọi service từ nay dùng cùng một thư viện logging và cùng một định dạng log" là
|
||
ADR, vì nó ràng buộc mọi service tương lai.
|
||
|
||
## 5. Ai được đề xuất, ai được chốt
|
||
|
||
| Loại quyết định | Đề xuất | Chốt | Phủ quyết |
|
||
|---|---|---|---|
|
||
| Cấu trúc hệ thống, dữ liệu, tích hợp | SA | SA + Tech Lead | EA (nếu lệch chuẩn doanh nghiệp) |
|
||
| Bảo mật, quyền riêng tư | SA | **Security** | Security |
|
||
| Hạ tầng, HA/DR, chi phí vận hành | SA | SA + SRE | PO (nếu vượt ngân sách) |
|
||
| Đánh đổi nghiệp vụ (rẻ hơn nhưng chậm hơn) | SA trình bảng | **PO** | — |
|
||
| Công cụ, thư viện, quy ước code | Tech Lead | Tech Lead | SA (nếu chạm `QAS`) |
|
||
|
||
Dev và Tech Lead **được quyền đề xuất ADR**. Một tổ chức mà chỉ SA viết được ADR là tổ chức
|
||
mà kiến trúc sẽ bị vòng qua chứ không bị phản biện.
|
||
|
||
## 6. Khi nào một ADR cần POC trước
|
||
|
||
Bắt buộc POC trước khi chuyển `Proposed → Accepted` nếu có bất kỳ điều nào:
|
||
|
||
- Điểm radar ≥ 8
|
||
- Quyết định dựa trên một con số hiệu năng **chưa ai đo trong ngữ cảnh này**
|
||
- Công nghệ chưa ai trong team từng chạy production
|
||
- Phụ thuộc vào hành vi của hệ thống bên ngoài mà ta chỉ đọc tài liệu, chưa gọi thật
|
||
- Ước lượng chi phí hạ tầng dựa trên suy đoán, không có báo giá hay bài đo
|
||
|
||
POC phải có **tiêu chí pass/fail viết trước khi làm**, và kết quả (kể cả fail) ghi vào `ARISK`
|
||
rồi tham chiếu từ ADR. POC không có tiêu chí trước là POC luôn "thành công".
|