220 lines
12 KiB
Markdown
220 lines
12 KiB
Markdown
# 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.
|
|
|
|
```markdown
|
|
# <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`
|
|
|
|
```markdown
|
|
# 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ộ.
|