# 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 | | `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// ├── 00-index/ │ ├── INDEX_.md │ ├── ADL_.md │ ├── DTM_.md │ ├── GLOSSARY_.md │ ├── DEC_.md │ └── OQ_.md ├── 01-context/ CTX · OPT · TCO · ARISK ├── 02-architecture/ │ ├── ASR · QAS · SAD · ICD · DAT · SEC · INF · FAIL │ └── adr/ │ ├── ADR-001_.md │ └── archive/ ├── 03-enablement/ AGD · FIT · DREV · TDEBT └── 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 # — | | | |---|---| | **Version** | 1.0 | | **Date** | 2026-08-30 | | **Author** | (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** | | | **Scope** | | | **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-_.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 ────┤ │ ├──► DAT ├──► AGD ──► DREV │ ├──► SEC │ │ ├──► INF └──► TDEBT ──► TRM │ └──► FAIL └──► ADR (sinh ở mọi nhánh) DTM đọc: CTX(DRV) · ASR · QAS · ADR · SAD(CMP) · 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) | **`ICD` thắng.** BA đánh dấu "chờ xác nhận", SA là người xác nhận | | `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_.md` ```markdown # INDEX — (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ộ.