update skill and docs

2026-09-22 13:46:36 +07:00
parent 343ad8bbbc
commit 51506aabc7
149 changed files with 43752 additions and 300 deletions
--- a/.claude/skills/ba-lifecycle/references/diagram-rules.md
+++ b/.claude/skills/ba-lifecycle/references/diagram-rules.md
@@ -1,224 +1,269 @@
-# Quy tắc vẽ sơ đồ trong tài liệu BA
+# Chuẩn sơ đồ — theo tiêu chuẩn và phong cách Archify

-Mọi sơ đồ trong bộ skill này viết bằng **mermaid**, không dùng ASCII art.
+Áp dụng cho **mọi sơ đồ** của cả ba bộ skill (`ba-*`, `sa-*`, `sad-*` và các agent SAD/proposal/bid).
+Quy tắc `W13` của bộ BA và `D4` của bộ SA đều trỏ về file này.

-Lý do không phải thẩm mỹ:
-
-| ASCII art | mermaid |
-|---|---|
-| Dán vào Confluence/PowerPoint là vỡ, phải vẽ lại tay | GitHub · GitLab · Confluence · Artifact của Claude Code render thẳng |
-| `git diff` ra một khối rác | Diff theo dòng, review được từng cạnh |
-| Ký hiệu tự chế, khách quen UML/BPMN đọc lệch | Ký hiệu chuẩn của từng loại sơ đồ |
-| Sửa một node phải căn lại cả hình | Sửa một dòng |
+Chuẩn tham chiếu: [Archify](https://github.com/tt-a1i/archify) (MIT) — gói đã nhúng tại
+`.claude/skills/archify/` (đọc `SKILL.md`, `schemas/`, `references/authoring-contract.md` ở đó khi
+cần chi tiết trường). Không cài thêm gì, chỉ cần Node ≥ 18.

 ---

-## W13 — Mỗi sơ đồ phải có bảng đi kèm
+## 0. Ba câu chốt

-🔴 **Quy tắc quan trọng nhất của file này.**
+1. **Một sơ đồ = spec JSON Archify + Mermaid trong `.md` + bảng đi kèm.** Spec là nguồn sự thật về
+   topology (node, cạnh, ranh giới); Mermaid là bản chiếu để GitHub/Confluence render và `git diff`
+   đọc được; bảng để truy vết, đặt con số và viết test. Ba thứ phải khớp nhau.
+2. **Một đường chính rõ ràng, ≤ 12 node chính, nhãn cạnh là dữ liệu ngữ nghĩa.** Nhánh phụ rời khỏi
+   node gần nhất trên đường chính. Quá 12 node ⇒ tách sơ đồ, không thu nhỏ chữ.
+3. **Kiểm bằng máy trước khi trình gate.** `archify validate … --quality showcase` phải pass 0 lỗi,
+   và `diagram-check.mjs` phải xanh. Sơ đồ chưa validate là bản nháp, không đưa vào artifact 🔵/✅.

-**Sơ đồ để nhìn, bảng để truy vết và test.** Sơ đồ không diễn đạt được: điều kiện chính xác,
-ai được làm, mã lỗi nào, quy tắc nào chi phối, ai chịu trách nhiệm. Một sơ đồ đứng một mình
-là một bức tranh đẹp mà QA không viết được test case từ đó.
+---
+
+## 1. Chọn loại — bộ định tuyến
+
+| Cần thể hiện | Loại Archify | Mermaid đi kèm | Sinh ở |
+|---|---|---|---|
+| Ranh giới hệ thống (BRIEF §5.3), phương án mức khối (`OPT` §3) | `architecture` | `flowchart LR` + `subgraph` | ba-1, sa-1 |
+| C4 Context / Container / Component, deployment view, ranh giới tin cậy | `architecture` | `flowchart LR/TB` + `subgraph` | `SAD` §3–§5, §7 · `INF` §3 · `SEC` §1 |
+| Quy trình AS-IS / TO-BE, luồng phê duyệt, phân loại Defect/CR | `workflow` | `flowchart TD` | `PROCESS` A1/B1 · `CR` §0 |
+| Điều hướng màn hình, phụ thuộc job | `workflow` | `flowchart LR` | `srs-part2/screen` §2.2 · `batch-job` §2.2 |
+| Luồng nhiều bên theo thời gian, **có nhánh lỗi** | `sequence` | `sequenceDiagram` | `srs-part2/*` §2.3 · `SAD` §6 |
+| Luồng dữ liệu, lineage, ownership dữ liệu | `dataflow` | `flowchart LR` | `srs-part2/data-pipeline` §2.2 · `DAT` §1 |
+| Vòng đời trạng thái | `lifecycle` | `stateDiagram-v2` | `BR` §3 · SAD-pipeline mục 6 |
+| Phụ thuộc mục roadmap | `workflow` | `flowchart LR` | `TRM` §4 |
+
+**Không có loại Archify — chỉ Mermaid** (`mermaid-only`), vẫn áp §3 phong cách và §4 bảng:
+
+| Sơ đồ | Mermaid | Vì sao Mermaid-only |
+|---|---|---|
+| ERD khái niệm (`BR` §4, `DAT` §2) | `erDiagram` | Archify không có kiểu quan hệ thực thể |
+| Class diagram (`DOM`, SAD-pipeline mục 6) | `classDiagram` | Như trên |
+| Use case (`BACKLOG` §0) | `flowchart LR` + `subgraph` | Quan hệ actor–use case là liên kết, không phải luồng |
+| Cây phân rã RQ→US (`BACKLOG` §1), 5-Why (`ELICITATION` §A9) | `flowchart LR/TD` | Cây tư duy, không phải hệ thống |
+| Ma trận 2×2 (`STAKEHOLDER` §2) | `quadrantChart` | — |
+| Ma trận ≥ 3×3, bảng số liệu | **bảng markdown** | Không phải sơ đồ |
+| Bố cục màn hình | `WF_<US>.md` + `.html` | Mermaid không vẽ UI; xem ba-3 |
+
+Lưỡng lự ⇒ `node .claude/skills/archify/bin/archify.mjs guide "<mô tả>" --json`.
+
+---
+
+## 2. Từ vựng Archify áp cho miền của ta
+
+### 2.1 `type` của node
+
+| `type` | Dùng cho |
+|---|---|
+| `external` | Người dùng/actor (`ROLE-nn`), hệ thống ngoài phạm vi, đối tác (VNPay, GHN…), sự kiện kích hoạt |
+| `frontend` | Web/mobile client, màn hình `SCR-nn`, bước do người thao tác trên giao diện |
+| `backend` | Service/module `CMP-nn`, job, bước xử lý của hệ thống, điểm quyết định |
+| `database` | CSDL, cache, object store, kho dữ liệu, "kết thúc: ghi sổ" |
+| `messagebus` | Queue, topic, event bus, luồng bất đồng bộ |
+| `security` | IdP, WAF, KMS, kiểm quyền, vùng cách ly, bước dừng vì lỗi/bảo mật |
+| `cloud` | Hạ tầng quản lý: ALB, CDN, DNS, vùng/AZ khi là node |
+
+Với `lifecycle`, `type` là trạng thái: `start` · `active` · `waiting` (chờ người/hệ khác) · `decision` ·
+`success` (cuối, tốt) · `failure` (cuối xấu **hoặc** phục hồi được — phải có cạnh quay lại) · `neutral` · `external`.
+
+### 2.2 `variant` của cạnh
+
+| `variant` | Nghĩa |
+|---|---|
+| `emphasis` | **Đường chính** (happy path) — mỗi sơ đồ có đúng một đường chính |
+| `default` | Nhánh phụ đồng bộ |
+| `dashed` | Bất đồng bộ, tuỳ chọn, degraded, quay lại/retry |
+| `security` | Xác thực, phân quyền, dữ liệu nhạy cảm, nhánh lỗi/dừng |
+| `return` (chỉ `sequence`) | Phản hồi |
+
+`workflow` thêm `role`: `main` · `branch` · `async` · `return` · `error`.
+
+### 2.3 ID và nhãn
+
+- **ID là mã truy vết, bỏ dấu gạch**: `CMP04`, `SCR01`, `US011`, `IF002`, `A3`, `B2`, `ChoDuyet`. Cùng
+  một ID dùng ở spec, Mermaid và bảng — đó là thứ nối ba thứ với nhau. Mẫu `^[A-Za-z][A-Za-z0-9_-]*$`,
+  không dấu tiếng Việt.
+- **`label` mang mã đầy đủ + tên**: `"CMP-04 Cart & Order"`, `"🆕 B2 Đối soát tự động"`. `sublabel` mang
+  tham chiếu: `"REST/JSON · /v1"`, `"SCR-01 · ROLE-01"`, `"BR-014 · ⏱ ≤ 5 phút"`.
+- **Nhãn cạnh là điều kiện, giao thức, sync/async, hành động** — không phải mô tả: ✅ `"REST · IF-002"`,
+  `"lệch > ngưỡng"`, `"publish · async"` · ❌ `"chuyển sang trạng thái đã duyệt"`. Không xoá nhãn để
+  sửa bố cục; chỉ bỏ khi hai đầu đã nói hết nghĩa và ghi lý do trong bảng.
+- Đánh dấu bằng **tiền tố trong nhãn**, không bằng màu: `⚠️ P1 ·` điểm đau · `🆕` mới · `🔄` đổi ·
+  `⬜` giữ · `➖` bỏ (chỉ ở bảng, không vẽ).
+
+### 2.4 `meta` — mặc định phải giữ
+
+| Trường | Giá trị | Lý do |
+|---|---|---|
+| `quality_profile` | `"showcase"` **bắt buộc** | Đủ 9 phép kiểm bố cục; `standard` không được nhận ở gate |
+| `visual_preset` | **bỏ** (= `classic`) | Chỉ đặt `signal-flow`/`blueprint`/`editorial` khi người dùng yêu cầu đích danh |
+| `subtitle` | **bỏ** | Không lặp lại title/node |
+| `legend` | **bỏ** (= `auto`) | Legend tự liệt kê đúng loại có mặt |
+| `locale` | **bỏ** | Tài liệu tiếng Việt: giao diện viewer sẽ là tiếng Anh; ghi chú điều này một lần ở artifact |
+| `animation` | bỏ | Chỉ `"trace"` cho bản trình chiếu |
+| `views` | ≤ 5, khuyến nghị 2 | "đường chính" và "nhánh lỗi/bất đồng bộ" |
+| `cards` | ≤ 3, mỗi card ≤ 3 dòng | Chỉ chép sự thật đã có trong bảng đi kèm; không viết nội dung mới |
+| `engineering_profile` | bỏ | Chỉ `deployment-ownership` khi làm `INF` fail-closed và biết đủ owner/region |
+
+---
+
+## 3. Phong cách Mermaid (bản chiếu của spec)
+
+1. **Không tô màu, không style** — cấm `style`, `classDef`, `linkStyle`, `:::`. Renderer đổi theme
+   sáng/tối; màu cứng làm chữ biến mất. Phân biệt bằng **hình dạng** và **nhãn**.
+2. **Hình dạng theo `type`**: `["…"]` backend/bước xử lý · `{"…"}` quyết định · `(["…"])` actor/bắt đầu/kết
+   thúc · `[("…")]` database · `[["…"]]` external/ngoài phạm vi · `>"…"]` messagebus.
+3. **Hướng**: `TD` cho quy trình nhiều rẽ nhánh · `LR` cho luồng tuyến tính, lineage, điều hướng, C4.
+4. **`subgraph` = `boundaries`** (region / security-group) hoặc lane. ID subgraph không dấu.
+5. **Cùng tập node và cạnh với spec** — `diagram-check` so hai chiều. Mermaid được thêm chi tiết mà
+   Archify không có (`alt/else` trong sequence, `[*]` trong state) nhưng không thêm node.
+6. **Sequence bắt buộc có nhánh lỗi** (`alt`/`else`) và `autonumber`; số bước là khoá của bảng đi kèm.
+   Trong spec, nhánh lỗi là các `messages` với `segments` "Nhánh lỗi".
+7. `stateDiagram-v2`: `state "Nhãn có dấu" as IDKhongDau`. Cạnh bị cấm không vẽ được ⇒ nằm ở bảng.
+8. Không dùng `gantt` (việc của PM) và `pie` (bảng luôn rõ hơn).
+
+---
+
+## 4. Bảng đi kèm (W13) — bắt buộc
+
+**Sơ đồ để nhìn, bảng để truy vết và test.** Sơ đồ không diễn đạt được điều kiện chính xác, ai được
+làm, mã lỗi nào, timeout bao nhiêu, ai sở hữu.

 | Sơ đồ | Bảng bắt buộc đi kèm |
 |---|---|
-| Quy trình AS-IS/TO-BE | Bảng chi tiết từng bước: ai · input · output · công cụ · thời gian |
-| Vòng đời trạng thái | Bảng chuyển: nguồn · sự kiện · **điều kiện** · đích · ai được làm · BR · ghi vết |
+| Quy trình (`workflow`) | Bảng bước: ai · input · output · công cụ · thời gian |
+| Vòng đời (`lifecycle`) | Bảng chuyển: nguồn · sự kiện · **điều kiện** · đích · ai · BR · ghi vết · **+ bảng chuyển bị cấm** |
 | Use case | Bảng US: id · vai trò · RQ · MoSCoW |
-| ERD | Bảng thực thể: trường · kiểu · khoá · ràng buộc |
+| ERD / class | Bảng thực thể: trường · kiểu · khoá · ràng buộc |
 | Sequence | Bảng bước: mã lỗi mỗi nhánh · timeout · hành vi khi thất bại |
-| Lineage / phụ thuộc | Bảng luồng: tần suất · khối lượng · SLA · chủ sở hữu |
+| C4 / deployment (`architecture`) | Bảng `CMP-nn`: trách nhiệm · **không làm gì** · dữ liệu sở hữu · interface · team · ASR |
+| Lineage / phụ thuộc (`dataflow`, `workflow`) | Bảng luồng: tần suất · khối lượng · SLA · chủ sở hữu |

-Khi sơ đồ và bảng mâu thuẫn: **bảng thắng**. Ghi câu này vào tài liệu (quy tắc W11).
+Sơ đồ mâu thuẫn bảng ⇒ **bảng thắng** về ràng buộc và con số; **sơ đồ thắng** về quan hệ và luồng
+(`W11`, `D12`). Ghi câu này vào tài liệu.

 ---

-## Chọn loại sơ đồ
+## 5. Tệp, marker, lệnh

-| Cần thể hiện | Dùng | Ở đâu trong bộ skill |
+### 5.1 Vị trí
+
+```
+<thư mục artifact>/diagrams/<ARTIFACT>_<slug>.<type>.json     ← spec (nguồn sự thật)
+<thư mục artifact>/diagrams/<ARTIFACT>_<slug>.<type>.html     ← đã deliver (tự chứa, dark/light, export PNG/SVG)
+```
+
+Ví dụ: `sa-output/<P>/02-architecture/diagrams/SAD_c4-container.architecture.json`,
+`ba-output/<P>/02-analysis/diagrams/PROCESS_to-be.workflow.json`, `docs/diagrams/03_c4-container.architecture.json`
+(SAD-pipeline), `bid/diagrams/…`, `docs/proposal/diagrams/…`.
+
+### 5.2 Marker trong `.md` — ngay trên khối Mermaid
+
+```markdown
+<!-- archify: architecture · diagrams/SAD_c4-container.architecture.json -->
+```mermaid
+flowchart LR
+    …
+```
+```
+
+Sơ đồ không có kiểu Archify:
+
+```markdown
+<!-- archify: mermaid-only -->
+```
+
+Thiếu marker ⇒ `diagram-check` 🔴.
+
+### 5.3 Lệnh — người điều phối (có Bash) chạy sau mỗi activity sinh sơ đồ
+
+```bash
+A=.claude/skills/archify/bin/archify.mjs
+node $A validate <type> <spec.json> --quality showcase --json      # sửa theo diagnostics tới khi 0 lỗi
+node $A deliver  <type> <spec.json> <spec.html> --quality showcase --json   # chốt HTML, có SHA-256
+node .claude/skills/ba-lifecycle/scripts/diagram-check.mjs --md <artifact.md>   # A0–A7, exit 1 nếu 🔴
+```
+
+Runner không có Bash ⇒ vẫn viết spec + Mermaid + marker, ghi `humanInputNeeded` "chạy validate/deliver
+ diagram-check", và **không** tự ghi "đã validate".
+
+### 5.4 Sửa lỗi validate — thứ tự (theo `authoring-contract.md`)
+
+1. `meta.quality_profile` và lỗi schema → 2. node chồng nhau / ngoài lưới → 3. cạnh xuyên node, sai hướng
+cổng → 4. cạnh cắt nhau, hành lang mơ hồ → 5. nhãn chồng node/nhãn/tuyến: **giãn khoảng cách hoặc dời
+nhãn (`labelDy`/`labelDx`/`labelAt` theo gợi ý), rồi mới rút ngắn chữ, không xoá nhãn.** Mỗi lần sửa một
+điều khiển hình học. Hai vòng không giảm số lỗi ⇒ dừng và báo trung thực.
+
+Khoảng cách là **khe trống**, không phải khoảng tâm: `khe > 6,5px × số ký tự ASCII + 13 + 8` (chữ CJK tính
+đôi). Node 150px cách tâm 340px ⇒ khe 190px ⇒ nhãn ≤ 26 ký tự.
+
+---
+
+## 6. Mẫu chuẩn — sao chép rồi sửa
+
+Spec mẫu đã validate pass (`showcase`), một mẫu mỗi loại:
+
+| Loại | Spec mẫu | Mermaid tương ứng ở template |
 |---|---|---|
-| Quy trình có rẽ nhánh | `flowchart TD` | `PROCESS` A1/B1 |
-| Vòng đời trạng thái | `stateDiagram-v2` | `BR` §3 |
-| Actor × chức năng, toàn cảnh phạm vi | `flowchart LR` + `subgraph` | `BACKLOG` §0 |
-| Thực thể và quan hệ | `erDiagram` | `BR` §4 |
-| Luồng nhiều bên theo thời gian | `sequenceDiagram` | `srs-part2/*` |
-| Luồng dữ liệu, phụ thuộc job | `flowchart LR` | `srs-part2/data-pipeline`, `batch-job` |
-| Điều hướng màn hình | `flowchart LR` | `srs-part2/screen` |
-| Ma trận 2×2 | `quadrantChart` | `STAKEHOLDER` §2 |
-| Ma trận 3×3 trở lên | **bảng markdown** — mermaid không có loại này | `RISK` §2 |
-| Ranh giới hệ thống | `flowchart LR` + `subgraph` | `BRIEF` §5.3 |
+| `architecture` | `sa-2-architecture/templates/diagrams/SAD_c4-container.architecture.json` | `sad.md` §4 |
+| `sequence` | `sa-2-architecture/templates/diagrams/SAD_luong-chinh.sequence.json` | `sad.md` §6, `srs-part2/screen.md` §2.3.4 |
+| `workflow` | `ba-2-analysis/templates/diagrams/PROCESS_to-be.workflow.json` | `process-model.md` B1 |
+| `lifecycle` | `ba-2-analysis/templates/diagrams/BR_vong-doi.lifecycle.json` | `business-rules.md` §3 |
+| `dataflow` | `ba-3-specification/templates/diagrams/SRS_lineage.dataflow.json` | `srs-part2/data-pipeline.md` §2.2 |

-**Không dùng** `gantt` (tiến độ là việc của PM, không phải BA) và `pie` (một bảng luôn rõ hơn).
+Dùng mẫu để lấy **hình dạng trường**, không lấy sự thật: ID, tên, con số phải là của dự án.

---
-
-## Quy ước bắt buộc
-
-### 1. ID node không dấu, nhãn có dấu
-
-Ký tự tiếng Việt trong **ID** làm vỡ ở một số renderer. Luôn tách ID và nhãn:
-
-```
-✅  A1["Nhận file POS từ cửa hàng"]
-❌  Nhận file POS
-```
-
-Với `stateDiagram-v2` dùng dạng khai báo riêng:
-
-```
-state "Chờ duyệt" as ChoDuyet
-```
-
-### 2. ID mang mã truy vết
-
-Node ID chính là ID trong bảng — đó là thứ nối sơ đồ với bảng (W13):
-
-```
-A3["A3. Đối chiếu thủ công"]     ← khớp cột # của bảng chi tiết bước
-UC11(["US-011 Tải file POS"])     ← khớp id trong BACKLOG
-SCR01["SCR-01 Danh sách"]         ← khớp id trong bảng màn hình
-```
-
-### 3. Không tô màu, không style
-
-Renderer đổi theme sáng/tối; màu cứng làm chữ biến mất. Phân biệt bằng **hình dạng** và
-**nhãn**, không bằng màu:
-
-| Ý nghĩa | Hình dạng |
-|---|---|
-| Bước xử lý | `A["..."]` chữ nhật |
-| Điểm quyết định | `A{"..."}` thoi |
-| Bắt đầu / kết thúc | `A(["..."])` bo tròn |
-| Dữ liệu / tài liệu | `A[("...")]` trụ |
-| Hệ thống ngoài phạm vi | `A[["..."]]` khung đôi |
-
-Đánh dấu đặc biệt bằng **tiền tố trong nhãn**, không bằng màu:
-`"⚠️ P1 · Đối chiếu thủ công"` · `"🆕 B2 · ..."` · `"➖ A5 · (bỏ)"`
-
-### 4. Hướng vẽ
-
-`TD` (trên xuống) cho quy trình có nhiều rẽ nhánh · `LR` (trái sang phải) cho luồng tuyến
-tính, lineage, điều hướng, use case. Sơ đồ quá 20 node ⇒ **tách thành nhiều sơ đồ**, đừng
-thu nhỏ chữ.
-
-### 5. Nhãn cạnh là điều kiện, không phải mô tả
-
-```
-✅  ChoDuyet --> DaDuyet: duyệt (chênh lệch ≤ 10tr)
-❌  ChoDuyet --> DaDuyet: chuyển sang trạng thái đã duyệt
-```
-
-Điều kiện đầy đủ vẫn nằm ở bảng — nhãn cạnh chỉ là gợi nhớ.
-
---
-
-## Mẫu chuẩn — sao chép rồi sửa
-
-### Quy trình
+### Quy trình (`workflow`) — Mermaid

 ````markdown
+<!-- archify: workflow · diagrams/PROCESS_to-be.workflow.json -->
 ```mermaid
 flowchart TD
-    START(["Đơn hàng phát sinh"]) --> A1["A1. Ghi nhận vào POS"]
-    A1 --> A2["A2. Xuất file cuối ca"]
-    A2 --> D1{"Có sai lệch?"}
-    D1 -->|Không| END(["Kết thúc"])
-    D1 -->|Có| A3["⚠️ P1 · A3. Đối chiếu thủ công"]
-    A3 --> EXT[["Gọi điện xác nhận với cửa hàng"]]
-    EXT --> A2
+    START(["Kết ca"]) -->|cuối ca| B1["🆕 B1 Tải file POS"]
+    B1 -->|file hợp lệ| B2["🆕 B2 Đối soát tự động"]
+    B2 --> D1{"D1 Có sai lệch?"}
+    D1 -->|không lệch| END[("Kết thúc")]
+    D1 -->|lệch > ngưỡng| B3["🔄 B3 Tạo phiếu lệch"]
+    B3 -->|gửi duyệt| B4["⬜ B4 Duyệt phiếu"]
+    B4 -->|đã duyệt| END
+    B1 -->|file sai định dạng| X1[["File hỏng · E-POS-0400"]]
+    X1 -.->|tải lại| B1
 ```
 ````

-### Vòng đời trạng thái
+### Vòng đời (`lifecycle`) — Mermaid

 ````markdown
+<!-- archify: lifecycle · diagrams/BR_vong-doi.lifecycle.json -->
 ```mermaid
 stateDiagram-v2
    state "Nháp" as Nhap
    state "Chờ duyệt" as ChoDuyet
    state "Đã duyệt" as DaDuyet
    state "Đã đóng" as DaDong
+    state "Bị từ chối" as TuChoi

    [*] --> Nhap
    Nhap --> ChoDuyet: gửi duyệt (đủ trường bắt buộc)
-    ChoDuyet --> DaDuyet: duyệt
-    ChoDuyet --> Nhap: từ chối
+    ChoDuyet --> DaDuyet: duyệt (chênh lệch ≤ 10tr)
+    ChoDuyet --> TuChoi: từ chối
+    TuChoi --> Nhap: sửa lại
    DaDuyet --> DaDong: đóng (có ghi chú lý do)
    DaDong --> [*]
 ```
 ````

-Kèm bảng chuyển trạng thái đầy đủ, **và bảng "chuyển trạng thái KHÔNG được phép"** — sơ đồ
-chỉ vẽ được cạnh có tồn tại, không vẽ được cạnh bị cấm.
-
-### Use case
-
-Mermaid không có use case diagram; dùng `flowchart LR` với `subgraph` làm ranh giới hệ thống:
-
-````markdown
-```mermaid
-flowchart LR
-    NV(["👤 Nhân viên đối soát"])
-    TN(["👤 Trưởng nhóm"])
-    KT(["👤 Kế toán"])
-
-    subgraph HT["Hệ thống đối soát"]
-        UC11(["US-011 Tải file POS"])
-        UC13(["US-013 Xem chênh lệch"])
-        UC14(["US-014 Đóng chênh lệch"])
-    end
-
-    NV --- UC11
-    NV --- UC13
-    TN --- UC13
-    TN --- UC14
-    KT --- UC13
-```
-````
-
-Dùng `---` (không mũi tên): quan hệ actor–use case là **liên kết**, không phải luồng.
-
-### ERD khái niệm
-
-Tên thực thể **không dấu, viết hoa**; tên tiếng Việt để ở bảng đi kèm.
-
-````markdown
-```mermaid
-erDiagram
-    CUA_HANG ||--o{ GIAO_DICH : "phát sinh"
-    GIAO_DICH ||--o| CHENH_LECH : "sinh ra khi lệch"
-    NGUOI_DUNG ||--o{ CHENH_LECH : "xử lý"
-
-    CUA_HANG {
-        string ma_cua_hang PK "3-20 ký tự"
-        string ten
-        enum   trang_thai
-    }
-    CHENH_LECH {
-        bigint id PK
-        bigint giao_dich_id FK
-        decimal so_tien "VND"
-        enum   trang_thai
-    }
-```
-````
-
-Ký hiệu lực lượng: `||--o{` một-nhiều · `||--||` một-một · `}o--o{` nhiều-nhiều ·
-`||--o|` một-không hoặc một.
-
-🔴 **ERD ở GĐ2 là mô hình khái niệm**, không phải schema. Nêu thực thể, quan hệ, khoá nghiệp
-vụ. Không nêu kiểu dữ liệu vật lý, index, bảng trung gian — đó là việc của SA/dev.
-
-### Sequence
+### Sequence (`sequence`) — Mermaid, bắt buộc nhánh lỗi

 ````markdown
+<!-- archify: sequence · diagrams/SAD_luong-chinh.sequence.json -->
 ```mermaid
 sequenceDiagram
    autonumber
    actor U as Nhân viên
    participant FE as Giao diện
-    participant BE as Hệ thống
+    participant BE as Settlement API
    participant POS as Hệ thống POS

    U->>FE: Bấm Lưu
@@ -229,19 +274,90 @@ sequenceDiagram
        BE-->>FE: 200 + id
        FE-->>U: Toast "Đã lưu"
    else POS timeout
-        POS--xBE: timeout
+        POS--xBE: timeout sau 3s
        BE-->>FE: 503 · E-STR-0503
        FE-->>U: Báo lỗi, GIỮ NGUYÊN dữ liệu đã nhập
    end
 ```
 ````

-`autonumber` đánh số bước để bảng đi kèm tham chiếu được. **Bắt buộc vẽ cả nhánh lỗi** —
-sequence chỉ có luồng thành công là vi phạm quy tắc W4.
-
-### Ma trận 2×2
+### C4 Container (`architecture`) — Mermaid

 ````markdown
+<!-- archify: architecture · diagrams/SAD_c4-container.architecture.json -->
+```mermaid
+flowchart LR
+    NV(["👤 Nhân viên đối soát · ROLE-01"])
+    IDP[["IdP nội bộ · OIDC"]]
+    subgraph REGION["Vùng hệ thống của ta · ap-southeast-1"]
+        WEB["CMP-01 Web App"]
+        API["CMP-02 Settlement API"]
+        DB[("CMP-03 CSDL chính")]
+        QUEUE>"CMP-04 Hàng đợi · SQS FIFO"]
+        WORKER["CMP-05 Worker"]
+    end
+    POS[["Hệ thống POS · đối tác"]]
+
+    NV -->|HTTPS · sync| WEB
+    WEB -->|REST · IF-002| API
+    IDP -->|JWT · IF-001| API
+    API -->|SQL · sync| DB
+    API -.->|publish · async| QUEUE
+    QUEUE -.->|consume · async| WORKER
+    WORKER -->|SQL · sync| DB
+    WORKER -.->|REST · 3s · retry 3| POS
+```
+````
+
+**Legend** (ghi dưới sơ đồ): `["…"]` service của ta · `[["…"]]` ngoài phạm vi · `[("…")]` CSDL ·
+`>"…"]` hàng đợi · `-->` đồng bộ · `-.->` bất đồng bộ · nhãn = giao thức · `IF-nnn`.
+
+### Use case (`mermaid-only`)
+
+````markdown
+<!-- archify: mermaid-only -->
+```mermaid
+flowchart LR
+    NV(["👤 Nhân viên đối soát"])
+    TN(["👤 Trưởng nhóm"])
+    subgraph HT["Hệ thống đối soát"]
+        UC11(["US-011 Tải file POS"])
+        UC13(["US-013 Xem chênh lệch"])
+        UC14(["US-014 Đóng chênh lệch"])
+    end
+    NV --- UC11
+    NV --- UC13
+    TN --- UC13
+    TN --- UC14
+```
+````
+
+Dùng `---` (không mũi tên): quan hệ actor–use case là liên kết, không phải luồng.
+
+### ERD khái niệm (`mermaid-only`)
+
+````markdown
+<!-- archify: mermaid-only -->
+```mermaid
+erDiagram
+    CUA_HANG ||--o{ GIAO_DICH : "phát sinh"
+    GIAO_DICH ||--o| CHENH_LECH : "sinh ra khi lệch"
+    CHENH_LECH {
+        bigint id PK
+        bigint giao_dich_id FK
+        decimal so_tien "VND"
+        enum trang_thai
+    }
+```
+````
+
+Lực lượng: `||--o{` một-nhiều · `||--||` một-một · `}o--o{` nhiều-nhiều · `||--o|` một-không hoặc một.
+🔴 ERD ở GĐ2 (BA) là **khái niệm**; kiểu vật lý, index, bảng trung gian thuộc `PDM` của SA.
+
+### Ma trận 2×2 (`mermaid-only`)
+
+````markdown
+<!-- archify: mermaid-only -->
 ```mermaid
 quadrantChart
    title Stakeholder — Quan tâm × Ảnh hưởng
@@ -252,24 +368,37 @@ quadrantChart
    quadrant-3 "Theo dõi"
    quadrant-4 "Giữ thông tin"
    "STK-01 Trưởng phòng TC": [0.85, 0.90]
-    "STK-04 Pháp chế": [0.20, 0.85]
 ```
 ````

-⚠️ `quadrantChart` cần mermaid ≥ 10. Renderer cũ (một số bản Confluence) không hiểu ⇒ giữ
-bảng phân nhóm bên dưới làm phương án dự phòng.
+⚠️ `quadrantChart` cần mermaid ≥ 10; giữ bảng phân nhóm bên dưới làm dự phòng.

 ---

-## Khi mermaid không diễn đạt được
-
-Ba trường hợp, và cách xử lý:
+## 7. Khi Mermaid hoặc Archify không diễn đạt được

 | Trường hợp | Làm gì |
 |---|---|
-| Bố cục màn hình | `WF_<US>.md` (bảng vùng + bảng vị trí thành phần) **và** `WF_<US>.html` low-fi sinh từ `ba-3-specification/templates/wireframe.html` — mermaid không phải công cụ vẽ UI, ASCII art càng không. Có prototype thì WF ghi lại và đối chiếu; không có thì WF là đề xuất của BA |
+| Bố cục màn hình | `WF_<US>.md` + `.html` (ba-3), `HIFI` (ba-design) — không phải sơ đồ |
 | Ma trận ≥ 3×3, bảng số liệu | Bảng markdown |
-| Sơ đồ > 20 node | Tách thành nhiều sơ đồ theo phân vùng, mỗi cái một mục con |
+| Sơ đồ > 12 node chính | Tách theo phân vùng / bounded context, mỗi cái một mục con, một spec |
+| Nhánh `alt/else` nhiều tầng | Mỗi nhánh lỗi lớn một `sequence` riêng; spec dùng `segments` để đặt tên nhánh |
+| Cần chèn vào HTML proposal/bid/deck | Lấy `<svg>` từ file `.html` đã deliver (tự chứa, không CDN); không render lại Mermaid nếu đã có Archify HTML |

-**Không bao giờ** quay lại ASCII art vì "hình này mermaid vẽ xấu". Xấu thì tách nhỏ hoặc
-đổi loại sơ đồ.
+**Không bao giờ** quay lại ASCII art. Xấu thì tách nhỏ hoặc đổi loại sơ đồ.
+
+---
+
+## 8. Checklist sơ đồ — in ☐/✅ ở cuối mỗi lần chạy skill có sơ đồ
+
+```
+[ ] Mỗi sơ đồ có marker <!-- archify: … --> đúng loại (hoặc mermaid-only có lý do ở §1)
+[ ] Spec JSON: quality_profile = showcase · không subtitle/visual_preset/legend/locale
+[ ] archify validate pass 0 lỗi · đã deliver .html (hoặc humanInputNeeded nếu không có Bash)
+[ ] Một đường chính (emphasis) · ≤ 12 node chính · nhánh phụ rời node gần nhất
+[ ] ID = mã truy vết bỏ gạch, khớp spec ↔ Mermaid ↔ bảng (diagram-check A3/A4 ✅)
+[ ] Nhãn cạnh: giao thức · sync/async · điều kiện — không nhãn mô tả, không xoá nhãn để sửa bố cục
+[ ] Không style/classDef/màu · phân biệt bằng hình dạng và tiền tố nhãn
+[ ] Bảng đi kèm ngay dưới sơ đồ (W13) · câu thẩm quyền sơ đồ vs bảng (W11/D12)
+[ ] Sequence có nhánh lỗi · lifecycle có bảng chuyển bị cấm · C4 khai báo mức và legend
+```