192 lines
6.6 KiB
Markdown
192 lines
6.6 KiB
Markdown
# 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.*
|
||
|
||
<!-- archify: architecture · diagrams/SAD_c4-context.architecture.json -->
|
||
```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.*
|
||
|
||
<!-- archify: architecture · diagrams/SAD_c4-container.architecture.json -->
|
||
```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.*
|
||
|
||
<!-- archify: architecture · diagrams/SAD_c4-component.architecture.json -->
|
||
```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>
|
||
|
||
<!-- archify: sequence · diagrams/SAD_luong-chinh.sequence.json -->
|
||
```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.*
|
||
|
||
<!-- archify: architecture · diagrams/SAD_deployment.architecture.json -->
|
||
```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 |
|
||
|---|---|---|---|---|---|
|