134 lines
4.1 KiB
Markdown
134 lines
4.1 KiB
Markdown
# ADR-<nnn> — <quyết định, viết ở thể khẳng định>
|
|
|
|
*Tên file: `adr/ADR-<nnn>_<slug-ngắn>.md` — ví dụ `ADR-007_chon-postgres-thay-mongo.md`*
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Status** | `Proposed` / `Accepted` / `Rejected` / `Superseded by ADR-nnn` / `Deprecated` |
|
|
| **Date** | YYYY-MM-DD |
|
|
| **Người quyết** | *(ai ký — theo `decision-radar.md` §5)* |
|
|
| **Người đề xuất** | |
|
|
| **Điểm radar** | … /10 *(chấm theo `decision-radar.md` §2)* |
|
|
| **Supersedes** | — |
|
|
| **Superseded by** | — |
|
|
| **Liên quan** | `ASR-nnn` · `QAS-nnn` · `CON-nn` · `ADR-nnn` |
|
|
|
|
> ⚠️ **ADR bất biến sau khi `Accepted`.** Muốn đổi quyết định thì viết ADR mới có
|
|
> `Supersedes: ADR-<nnn>` và đổi trạng thái bản cũ thành `Superseded by`. Không sửa nội dung
|
|
> ADR đã Accepted, không xoá ADR đã Rejected.
|
|
|
|
---
|
|
|
|
## 1. Bối cảnh
|
|
|
|
*Tình huống buộc phải quyết. Viết ở **thì hiện tại**, mô tả sự thật đang có — không viết
|
|
"chúng tôi sẽ…". Người đọc sau 2 năm phải hiểu được vì sao lúc đó việc này là một vấn đề.*
|
|
|
|
**Ràng buộc đang chi phối:**
|
|
|
|
| Nguồn | Nội dung |
|
|
|---|---|
|
|
| `CON-nn` | |
|
|
| `QAS-nnn` | |
|
|
| `ASR-nnn` | |
|
|
|
|
**Cái đã biết chắc / cái còn là giả định:**
|
|
|
|
| Điều | 🟢 Đã kiểm chứng / 🔴 Giả định | Bằng chứng |
|
|
|---|---|---|
|
|
| | | POC-nn / bài đo / tài liệu … |
|
|
|
|
## 2. Phương án đã cân nhắc
|
|
|
|
*Bắt buộc ≥ 2 phương án (quy tắc `D3`). Một phương án duy nhất không phải quyết định.*
|
|
|
|
### PA-1 — <tên>
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Mô tả** | |
|
|
| **Ưu** | |
|
|
| **Nhược** | |
|
|
| **Chi phí đảo ngược** | *(nếu sau này sai thì sửa mất bao lâu)* |
|
|
|
|
### PA-2 — <tên>
|
|
|
|
*(cùng cấu trúc)*
|
|
|
|
### Bảng so sánh
|
|
|
|
| Tiêu chí *(sinh từ `QAS`/`CON`)* | PA-1 | PA-2 |
|
|
|---|---|---|
|
|
| | | |
|
|
|
|
## 3. Quyết định
|
|
|
|
> **Chọn PA-…**
|
|
|
|
*Viết ở thể khẳng định, một câu, đủ cụ thể để kiểm chứng được là có tuân thủ hay không.*
|
|
|
|
**Vì sao:** *(gắn với `CON-nn` hoặc `QAS-nnn` cụ thể, không phải sở thích)*
|
|
|
|
**Phạm vi áp dụng:** *(toàn hệ thống / chỉ component nào / chỉ tới khi nào)*
|
|
|
|
## 4. Phương án bị loại và lý do
|
|
|
|
| Phương án | Loại vì | Gắn với | Điều kiện nào thì xét lại |
|
|
|---|---|---|---|
|
|
| PA-… | | `CON-nn` / `QAS-nnn` | |
|
|
|
|
*"Team quen công nghệ X" là lý do hợp lệ — nhưng phải viết thành `CON-nn` có tên, để sau này
|
|
biết quyết định gắn với con người chứ không phải với kỹ thuật.*
|
|
|
|
## 5. Hệ quả
|
|
|
|
*Phần quan trọng nhất và bị viết sơ sài nhất. Ghi cả hệ quả tốt lẫn xấu — ADR chỉ có hệ quả
|
|
tốt là ADR viết để hợp thức hoá.*
|
|
|
|
**Hệ quả tích cực**
|
|
|
|
-
|
|
|
|
**Hệ quả tiêu cực phải sống chung**
|
|
|
|
-
|
|
|
|
**Cái quyết định này khoá lại** *(chi phí đảo ngược sau này)*
|
|
|
|
| Muốn đổi về sau thì | Tốn |
|
|
|---|---|
|
|
|
|
**Việc phát sinh**
|
|
|
|
| Việc | Chủ | Hạn | Ghi ở đâu |
|
|
|---|---|---|---|
|
|
| Cập nhật `SAD` §… | | | |
|
|
| Thêm fitness function | | | `FIT-nn` |
|
|
| Đào tạo team về … | | | `TCO` §5 |
|
|
|
|
## 6. Cách kiểm chứng quyết định này được tuân thủ
|
|
|
|
*Quy tắc `D8`: không verify tự động được thì chỉ là khuyến nghị.*
|
|
|
|
| Cách kiểm | Công cụ | Chạy ở đâu | `FIT` |
|
|
|---|---|---|---|
|
|
| | ArchUnit / dependency-cruiser / lint / kiểm thử tải / kiểm tra hạ tầng | CI | `FIT-nn` |
|
|
|
|
Không kiểm tự động được ⇒ ghi thẳng: `⚠️ Khuyến nghị — không tự kiểm được`, và nêu cách kiểm
|
|
thủ công cùng tần suất.
|
|
|
|
## 7. Điều kiện xét lại
|
|
|
|
*ADR không vĩnh viễn. Ghi trước dấu hiệu nào thì phải mở lại quyết định này.*
|
|
|
|
| Dấu hiệu | Ngưỡng | Ai theo dõi |
|
|
|---|---|---|
|
|
| | *(ví dụ: thông lượng vượt … msg/s, chi phí vượt … /tháng, team vượt … người)* | |
|
|
|
|
## 8. Tham chiếu
|
|
|
|
- POC: `ARISK_… §6 POC-nn`
|
|
- Bài đo:
|
|
- Tài liệu ngoài:
|
|
- Thảo luận: *(link biên bản họp, ngày)*
|