6.6 KiB
SAD — Solution Architecture Document —
| Version | 1.0 |
| Date | YYYY-MM-DD |
| Author | (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.
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.
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.
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>
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.
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 |
|---|