# Bản đồ artifact

## 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 |
|---|---|---|---|---|
| `BRIEF` | Project Brief | `01-discovery/` | ba-1 | PO, toàn team |
| `STAKEHOLDER` | Stakeholder Map & Analysis | `01-discovery/` | ba-1 | BA, PM |
| `ELICITATION` | Biên bản khai thác yêu cầu | `01-discovery/` | ba-1 | ba-2 |
| `RISK` | Sổ rủi ro & giả định | `01-discovery/` | ba-1 | PM, ba-5 |
| `PROCESS` | Quy trình AS-IS / TO-BE | `02-analysis/` | ba-2 | Dev, QA, ba-5 |
| `BACKLOG` | Feature list & User story backlog | `02-analysis/` | ba-2 | PO, ba-3 |
| `BR` | Business Rules | `02-analysis/` | ba-2 | ba-3, Dev, QA |
| `RBAC` | Ma trận phân quyền | `02-analysis/` | ba-2 | ba-3, Dev, Security |
| `IMPACT` | Phân tích tác động | `02-analysis/` | ba-2 | Tech Lead, QA |
| `SRS` | Software Requirements Specification | `03-specification/` | ba-3 | Dev, QA |
| `AC` | Acceptance Criteria (nếu tách khỏi SRS) | `03-specification/` | ba-3 | QA |
| `API` | API contract đề xuất | `03-specification/` | ba-3 | Dev BE/FE |
| `NFR` | Yêu cầu phi chức năng | `03-specification/` | ba-3 | Dev, Ops, QA |
| `WF` | Wireframe & bố cục (`.md` bảng vùng/thành phần/lệch + `.html` low-fi) — chỉ `PRODUCT = screen` | `03-specification/` | ba-3 (activity `wf`) | Dev FE, Designer, PO |
| `UICONV` | Quy ước giao diện cấp project — chỉ `PRODUCT = screen`, sinh một lần | `00-index/` | ba-3 (activity `uiconv`) | Dev FE, Designer, mọi SRS/WF |
| `DS` | Design system cấp project (`.md` + `ds/tokens.json` chuẩn W3C DTCG, `ds/tokens.css`, `ds/components.html`) — chỉ `PRODUCT = screen`, sinh một lần | `00-index/` | ba-design (activity `ds`) | Dev FE, Designer, mọi HIFI/FIGMA |
| `HIFI` | Mockup hi-fi tự chứa (`.html`: mọi `SCR` × trạng thái × breakpoint, chế độ prototype bấm được) — chỉ `screen` | `03-specification/design/` | ba-design (`hifi`, `proto`) | Dev FE, Designer, PO |
| `FIGMA` | Gói nhập Figma (thư mục: SVG mỗi `SCR` × khung nhìn, `tokens.dtcg.json`, `png/`, `README-import.md`) — chỉ `screen`; **không có `.fig`** | `03-specification/design/` | ba-design (`figma`) | Designer |
| `DSPEC` | Đặc tả thiết kế & bàn giao (redline, ánh xạ component, truy cập, bảng lệch HIFI ↔ WF/SRS/DS) — chỉ `screen` | `03-specification/design/` | ba-design (`dspec`) | Dev FE, QA (review giao diện) |
| `QLOG` | Clarification log | `04-delivery/` | ba-4 | Dev, QA |
| `CR` | Change Request | `04-delivery/` | ba-4 | PO, PM, Dev |
| `TCREVIEW` | Biên bản review test case | `04-delivery/` | ba-4 | QA |
| `UAT` | Kế hoạch & kết quả UAT | `04-delivery/` | ba-4 | PO |
| `RELNOTE` | Release note nghiệp vụ | `05-post-release/` | ba-5 | Người dùng |
| `MANUAL` | Tài liệu hướng dẫn sử dụng | `05-post-release/` | ba-5 | Người dùng, CS |
| `BENEFIT` | Benefit realization review | `05-post-release/` | ba-5 | PO, BA Lead |
| `RTM` | Requirements Traceability Matrix | `00-index/` | ba-traceability | Mọi vai trò |
| `GLOSSARY` | Từ điển thuật ngữ | `00-index/` | ba-1, bồi đắp dần | Mọi vai trò |
| `DECISION` | Sổ quyết định (`DEC-nn`) | `00-index/` | mọi skill | Mọi vai trò |
| `OQ` | Sổ open question | `00-index/` | mọi skill | Mọi vai trò |
| `INDEX` | Mục lục dự án | `00-index/` | ba-lifecycle | Mọi vai trò |

## 2. 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 BA> (qua skill ba-3-specification) |
| **Status** | 🟡 Draft / 🟠 In Review / 🔵 Approved / ✅ Baselined / 📦 Archived |
| **Approved by** | — *(điền tên + ngày khi được ký)* |
| **Source** | <danh sách file input đã dùng, mỗi cái một dòng> |
| **Scope** | <module / US id> |

## Change Log

| Version | Date | Người sửa | Thay đổi | CR |
|---|---|---|---|---|
| 1.0 | 2026-08-30 | … | Bản đầu | — |
```

Artifact **không phải `.md`** (`WF_*.html`, `HIFI_*.html`, thư mục `FIGMA_*/`, `ds/*`) không có header riêng:
trạng thái duyệt của chúng nằm ở artifact `.md` đi kèm (`WF.md` cho `WF.html`; `DSPEC` cho `HIFI` và `FIGMA`;
`DS.md` cho `ds/*`). Gate chấm file `.md` đó, và kiểm file kèm có tồn tại + qua `design-check`.

**Ý nghĩa `Status`** — đây là thứ gate đọc, không phải tên file:

| Status | Nghĩa | Ai được sửa file |
|---|---|---|
| 🟡 Draft | BA đang viết | BA tự do |
| 🟠 In Review | Đã gửi duyệt | BA sửa theo comment |
| 🔵 Approved | Người duyệt đã đồng ý nội dung | BA sửa, ghi Change Log |
| ✅ Baselined | Đã qua gate, là nguồn sự thật | **Chỉ sửa qua `CR-nnn`** |
| 📦 Archived | Đã bị thay bằng version mới | Không sửa |

## 3. Quy tắc version

| Thay đổi | Tăng |
|---|---|
| Sửa lỗi chính tả, làm rõ câu chữ, không đổi nghĩa | `+0.1` |
| Thêm/sửa nội dung nghiệp vụ, thêm AC, sửa rule | `+0.1` |
| Tái cấu trúc tài liệu, đổi phạm vi, gộp/tách US | `+1.0` |
| 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.

## 4. Mẫu `INDEX_<PROJECT>.md`

```markdown
# INDEX — <PROJECT>

| | |
|---|---|
| **Cập nhật** | 2026-08-30 |
| **Giai đoạn hiện tại** | GĐ2 · Analysis |
| **Gate gần nhất đã qua** | G1 (2026-08-20, ký bởi …) |

## Artifact

| Loại | File mới nhất | Version | Status | Cập nhật |
|---|---|---|---|---|
| BRIEF | `01-discovery/BRIEF_<...>_v1.0.md` | 1.0 | ✅ | 2026-08-20 |

## Open Question đang mở

| ID | Nội dung | Hỏi ai | Từ ngày | Chặn gì |
|---|---|---|---|---|

## Quyết định đã chốt

| ID | Quyết định | Người quyết | Ngày | Ảnh hưởng |
|---|---|---|---|---|
```

`INDEX` do `ba-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 cho người dùng chạy `/ba-lifecycle` để đồng bộ.

## 5. 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à
nêu rõ trong Source là đã dùng nguồn thay thế nào.

<!-- archify: mermaid-only -->
```mermaid
flowchart LR
    STK["STAKEHOLDER"] --> BRIEF["BRIEF"]
    ELI["ELICITATION"] --> BRIEF
    BRIEF --> RISK["RISK"]
    BRIEF --> BACKLOG["BACKLOG"]
    PROCESS["PROCESS"] --> BACKLOG
    BACKLOG --> BR["BR"]
    BACKLOG --> RBAC["RBAC"]
    IMPACT["IMPACT"] --> SRS["SRS"]
    BR --> SRS
    RBAC --> SRS
    SRS --> AC["AC"]
    SRS --> API["API"]
    SRS --> NFR["NFR"]
    UICONV["UICONV"] --> SRS
    UICONV --> WF["WF"]
    SRS --> WF
    PROTO[["Prototype / design system (ngoài bộ BA)"]] -.-> UICONV
    PROTO -.-> WF
    UICONV --> DS["DS"]
    BRAND[["Brand guideline (ngoài bộ BA)"]] -.-> DS
    PROTO -.-> DS
    DS --> HIFI["HIFI"]
    WF --> HIFI
    SRS --> HIFI
    HIFI --> FIGMA["FIGMA"]
    HIFI --> DSPEC["DSPEC"]
    DS --> FIGMA
    AC --> UAT["UAT"]
    UAT --> BENEFIT["BENEFIT"]
    UAT --> RELNOTE["RELNOTE"]
    UAT --> MANUAL["MANUAL"]
```

**RTM đọc:** `BRIEF`(RQ) · `BACKLOG`(US) · `SRS`+`AC`(AC, field, mã lỗi) · `WF`(C-id, SCR) · `HIFI`(`data-c`, `data-key`, `SCR`) · `DS`(token) · `UAT`(test case) · `CR`

`WF` và `UICONV` chỉ tồn tại khi `PRODUCT = screen`. `WF` **không** là nguồn sự thật về hành
vi — nó tham chiếu ngược về `SRS`; đổi prototype ⇒ đổi `WF`, `SRS` chỉ đổi khi lệch loại
Tồn tại/Hành vi được PO chấp nhận (qua `CR` nếu SRS đã Baselined).

`DS`, `HIFI`, `FIGMA`, `DSPEC` cũng chỉ tồn tại khi `PRODUCT = screen` và do `ba-design` sinh **sau** `WF`.
`HIFI` **không** là nguồn sự thật về hành vi hay text — nó *chép* từ `SRS` (`design-check` H3/H4 kiểm); `DS` là
nguồn sự thật về visual (token). Đổi brand ⇒ đổi `DS` ⇒ chạy lại mọi `HIFI`/`FIGMA`; đổi `SRS`/`WF` ⇒ chạy lại
`HIFI` → `FIGMA` → `DSPEC` của US đó.

Đọ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ụ sửa một `BR` ⇒
phải rà lại `SRS`, `AC`, test case, và cập nhật `RTM`.