12 KiB
12 KiB
Bản đồ artifact SA
1. Toàn bộ artifact, ai sinh, ai tiêu thụ
| Mã | Tên đầy đủ | Thư mục | Sinh bởi | Tiêu thụ bởi |
|---|---|---|---|---|
CTX |
Solution Context & Drivers | 01-context/ |
sa-1 | PO, Tech Lead, toàn team |
OPT |
Solution Options & Trade-off | 01-context/ |
sa-1 | PO, Tech Lead, PM |
TCO |
Cost Model / TCO | 01-context/ |
sa-1 | PO, PM, tài chính |
ARISK |
Architecture Risk Register & POC plan | 01-context/ |
sa-1 | PM, Tech Lead |
ASR |
Architecturally Significant Requirements | 02-architecture/ |
sa-2 | sa-2, Tech Lead |
QAS |
Quality Attribute Scenarios (NFR lượng hoá) | 02-architecture/ |
sa-2 | QA, SRE, Dev |
SAD |
Solution Architecture Document | 02-architecture/ |
sa-2 | Toàn team, khách hàng |
ADR |
Architecture Decision Record | 02-architecture/adr/ |
sa-2, mọi giai đoạn | Team hiện tại + người 2 năm sau |
ICD |
Integration & Interface Catalog | 02-architecture/ |
sa-2 | Dev BE/FE, đối tác, BA |
DAT |
Data Architecture | 02-architecture/ |
sa-2 | Dev, DBA, DPO |
SEC |
Security Architecture & Threat Model | 02-architecture/ |
sa-2 | Security, kiểm toán |
INF |
Infrastructure & Deployment Design | 02-architecture/ |
sa-2 | DevOps/SRE |
FAIL |
Failure Mode & Resilience Design | 02-architecture/ |
sa-2 | Dev, SRE, QA |
DOM |
Domain Model — class diagram theo bounded context, aggregate, invariant ↔ BR |
02-architecture/ |
sa-2 (dom) |
Dev BE, Tech Lead |
CTR |
Contract Files Index + file thật contracts/{openapi,asyncapi,partners}/*.yaml |
02-architecture/ |
sa-2 (ctr) |
Dev BE/FE, QA (contract test), đối tác |
PDM |
Physical Data Model + file thật schema/<kho>/V*.sql (DDL, migration có down, seed) |
02-architecture/ |
sa-2 (pdm) |
Dev BE, DBA, DevOps |
HANDOFF |
Gói bàn giao dev — mục lục đường dẫn thật + checklist đủ/thiếu + dev ký đã nhận | 03-enablement/ |
sa-3 (handoff) |
Dev BE/FE, QA, Tech Lead |
AGD |
Architecture Guidelines & Reference Impl | 03-enablement/ |
sa-3 | Dev |
FIT |
Fitness Functions | 03-enablement/ |
sa-3 | Dev, CI |
DREV |
Design Review Log | 03-enablement/ |
sa-3 | Tech Lead, Dev |
TDEBT |
Technical Debt Register | 03-enablement/ |
sa-3 | PM, PO, Tech Lead |
CONF |
Architecture Conformance Report | 04-evolution/ |
sa-4 | PO, SRE, EA |
TRM |
Technical Roadmap / Migration Plan | 04-evolution/ |
sa-4 | PM, PO |
PMR |
Architecture Review / Post-mortem | 04-evolution/ |
sa-4 | Tech Lead, EA |
DTM |
Decision Traceability Matrix | 00-index/ |
sa-conformance | Mọi vai trò |
ADL |
ADR Ledger (mục lục quyết định) | 00-index/ |
sa-conformance | Mọi vai trò |
GLOSSARY |
Từ điển thuật ngữ kỹ thuật | 00-index/ |
sa-1, bồi đắp dần | Mọi vai trò |
DEC |
Sổ quyết định không đủ tầm ADR (DEC-nn) |
00-index/ |
mọi skill | Mọi vai trò |
OQ |
Sổ open question (OQ-nnn) |
00-index/ |
mọi skill | Mọi vai trò |
INDEX |
Mục lục dự án | 00-index/ |
sa-lifecycle | Mọi vai trò |
2. Cây thư mục
sa-output/<PROJECT>/
├── 00-index/
│ ├── INDEX_<PROJECT>.md
│ ├── ADL_<PROJECT>.md
│ ├── DTM_<PROJECT>.md
│ ├── GLOSSARY_<PROJECT>.md
│ ├── DEC_<PROJECT>.md
│ └── OQ_<PROJECT>.md
├── 01-context/ CTX · OPT · TCO · ARISK
├── 02-architecture/
│ ├── ASR · QAS · SAD · ICD · DAT · SEC · INF · FAIL · DOM · CTR · PDM
│ ├── adr/
│ │ ├── ADR-001_<slug>.md
│ │ └── archive/
│ ├── contracts/
│ │ ├── openapi/<module>.yaml ← OpenAPI 3.1 — nguồn sự thật của IF sync
│ │ ├── asyncapi/<domain>-events.yaml ← AsyncAPI 3.0 — IF async
│ │ └── partners/<ten>.yaml ← mirror tài liệu đối tác (ghi nguồn, ngày)
│ ├── schema/<kho>/
│ │ ├── V001__init_<schema>.sql · V001__init_<schema>.down.sql
│ │ └── seed/R__reference_data.sql
│ └── diagrams/ ← <ARTIFACT>_<slug>.<type>.json (spec Archify) + .html
├── 03-enablement/ HANDOFF · AGD · FIT · DREV · TDEBT
│ └── diagrams/
└── 04-evolution/ CONF · TRM · PMR
3. Header bắt buộc của mọi artifact
Mọi file .md sinh ra phải mở đầu bằng khối này. Thiếu một dòng ⇒ gate không chấm được.
# <LOẠI> — <Tên phạm vi>
| | |
|---|---|
| **Version** | 1.0 |
| **Date** | 2026-08-30 |
| **Author** | <tên SA> (qua skill sa-2-architecture) |
| **Status** | 🟡 Draft / 🟠 In Review / 🔵 Approved / ✅ Baselined / 📦 Archived |
| **Approved by** | — *(điền tên + vai trò + ngày khi được ký)* |
| **Source** | <danh sách file input đã dùng, mỗi cái một dòng> |
| **Scope** | <hệ thống / module / phạm vi kiến trúc> |
| **Confidence** | 🟢 Đã kiểm chứng / 🟡 Ước lượng có cơ sở / 🔴 Giả định chưa xác minh |
## Change Log
| Version | Date | Người sửa | Thay đổi | ADR/DEC |
|---|---|---|---|---|
| 1.0 | 2026-08-30 | … | Bản đầu | — |
🔴 Dòng Confidence là thứ bộ SA có mà bộ BA không có. Tài liệu kiến trúc luôn chứa cả
sự thật lẫn ước lượng; không phân biệt hai thứ đó thì người đọc coi ước lượng là cam kết.
Một tài liệu có nhiều mức thì ghi mức thấp nhất ở header và đánh dấu từng mục bên trong.
Ý nghĩa Status — đây là thứ gate đọc, không phải tên file:
| Status | Nghĩa | Ai được sửa file |
|---|---|---|
| 🟡 Draft | SA đang viết | SA tự do |
| 🟠 In Review | Đã gửi duyệt | SA sửa theo comment |
| 🔵 Approved | Người duyệt đã đồng ý nội dung | SA sửa, ghi Change Log |
| ✅ Baselined | Đã qua gate, là nguồn sự thật | Chỉ sửa qua ADR mới hoặc DEC-nn |
| 📦 Archived | Đã bị thay bằng version mới | Không sửa |
4. ADR — quy ước riêng
ADR không dùng version như artifact khác. ADR bất biến sau khi Accepted: muốn đổi quyết định thì viết ADR mới thay thế nó.
Tên file: ADR-<nnn>_<slug-ngắn>.md — ví dụ ADR-007_chon-postgres-thay-mongo.md.
Số tăng dần toàn dự án, không bao giờ tái sử dụng.
Vòng đời trạng thái:
| Status | Nghĩa | Chuyển tiếp hợp lệ |
|---|---|---|
Proposed |
Đang đề xuất, chưa ai ký | → Accepted · Rejected |
Accepted |
Đã chốt, là ràng buộc | → Superseded · Deprecated |
Rejected |
Đã cân nhắc và loại | (cuối) — giữ file, không xoá |
Superseded by ADR-nnn |
Bị thay bởi quyết định mới | (cuối) |
Deprecated |
Không còn áp dụng, chưa có bản thay | → Superseded |
🔴 ADR bị loại vẫn phải giữ. Giá trị lớn nhất của ADR là ghi lại phương án đã cân nhắc và vì sao loại. Xoá đi thì sáu tháng sau có người đề xuất lại đúng phương án đó và cả team tranh luận lại từ đầu.
5. Quy tắc version (cho artifact không phải ADR)
| Thay đổi | Tăng |
|---|---|
| Sửa lỗi chính tả, làm rõ câu chữ, không đổi ràng buộc | +0.1 |
| Thêm/sửa nội dung kỹ thuật không đổi quyết định kiến trúc | +0.1 |
| Đổi một quyết định kiến trúc, đổi phạm vi, tái cấu trúc tài liệu | +1.0 và phải có ADR đi kèm |
| Qua gate lần đầu | đặt 1.0, Status ✅ Baselined |
File đạt ✅ Baselined mà cần sửa: tạo version mới, chuyển bản cũ vào archive/ cùng thư
mục, Status bản cũ đổi thành 📦 Archived. Không xoá file.
6. Quan hệ phụ thuộc
Mũi tên = "cần cái kia mới viết đúng được". Thiếu input ⇒ vẫn làm, nhưng phải ghi OQ và
hạ Confidence xuống 🔴.
BRIEF/BACKLOG (BA) ──► CTX ──► OPT ──► TCO
│ │
│ └──► ARISK ──► POC
│
└──► ASR ──┬──► QAS ──────────────┬──► FIT ──► CONF
│ │
└──► SAD ──┬──► ICD ──► CTR ──┤
│ ├──► DAT ──► DOM ──► PDM ──┼──► HANDOFF ──► AGD ──► DREV
│ ├──► SEC │
│ ├──► INF └──► TDEBT ──► TRM
│ └──► FAIL
└──► ADR (sinh ở mọi nhánh)
BA: API ──► ICD/CTR (file contract thắng) · BR ──► DOM (invariant) · FLD (bảng field SRS) ──► PDM (cột)
DTM đọc: CTX(DRV) · ASR · QAS · ADR · SAD(CMP) · ICD(IF) · CTR · DAT · PDM(TBL) · FIT · CONF
ADL đọc: toàn bộ adr/
Đọc xuôi mũi tên để biết sửa cái này thì phải sửa tiếp cái nào. Ví dụ đổi một QAS ⇒ rà
lại SAD (còn đáp ứng không), FIT (bài kiểm thử còn đúng không), CONF (bài đo còn đúng
không), và mọi ADR có QAS đó trong mục Context.
7. Ánh xạ sang artifact của bộ BA
Hai bộ dùng chung OQ và DEC. Những chỗ còn lại phải khớp nhau, không sao chép:
| Artifact BA | Artifact SA tương ứng | Quan hệ |
|---|---|---|
BRIEF · GOAL-nn |
CTX · DRV-nn |
SA đọc GOAL để suy ra driver kiến trúc |
NFR (BA đề xuất) |
QAS (SA lượng hoá) |
QAS thắng. BA ghi nhu cầu, SA chốt con số và cách đo |
API (BA đề xuất) |
ICD (SA chốt) → CTR (file OpenAPI) |
File contract trong CTR thắng. BA đánh dấu "chờ xác nhận", SA xác nhận qua ICD và sinh file; API ghi operationId |
SRS PART 2 bảng field FLD-* |
PDM cột |
Cùng độ dài/kiểu/null — UI và DB chặn cùng ngưỡng; lệch ⇒ OQ, không im lặng chọn một bên |
BR-nnn ràng buộc dữ liệu / tính toán |
DOM invariant |
BR là nguồn, DOM nói invariant sống ở class nào |
RBAC |
SEC §authz |
SEC map ma trận RBAC nghiệp vụ xuống cơ chế kỹ thuật |
IMPACT |
SAD + DAT |
BA nêu module nghiệp vụ bị ảnh hưởng, SA nêu component và dữ liệu |
BR-nnn |
ADR khi rule ép ràng buộc kiến trúc |
Ví dụ rule "không được mất giao dịch" ⇒ ADR về consistency |
CR-nnn |
ADR mới nếu CR chạm kiến trúc |
CR không chạm kiến trúc thì không cần ADR |
🔴 Không copy nội dung giữa hai bộ. Tham chiếu bằng đường dẫn + ID. Copy là cách chắc chắn nhất để hai tài liệu lệch nhau sau ba lần sửa.
8. Mẫu INDEX_<PROJECT>.md
# INDEX — <PROJECT> (kiến trúc)
| | |
|---|---|
| **Cập nhật** | 2026-08-30 |
| **Giai đoạn hiện tại** | GĐ2 · Architecture |
| **Gate gần nhất đã qua** | AG1 (2026-08-25, ký bởi …) |
| **ADR đang Proposed** | ADR-011, ADR-012 |
## Artifact
| Loại | File mới nhất | Version | Status | Confidence | Cập nhật |
|---|---|---|---|---|---|
| CTX | `01-context/CTX_<...>_v1.0.md` | 1.0 | ✅ | 🟢 | 2026-08-25 |
## Open Question đang mở
| ID | Nội dung | Hỏi ai | Từ ngày | Chặn gì |
|---|---|---|---|---|
## Rủi ro kiến trúc mức cao đang mở
| ID | Rủi ro | Chủ | Cách hạ | Hạn |
|---|---|---|---|---|
INDEX do sa-lifecycle cập nhật mỗi lần chạy. Các skill giai đoạn không sửa INDEX —
chúng chỉ ghi artifact của mình rồi báo người dùng chạy /sa-lifecycle để đồng bộ.