# Chuẩn sơ đồ — theo tiêu chuẩn và phong cách Archify

Á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.

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.

---

## 0. Ba câu chốt

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 🔵/✅.

---

## 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 (`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 / 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 |
| 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 |

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.

---

## 5. Tệp, marker, lệnh

### 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 |
|---|---|---|
| `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 |

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 trình (`workflow`) — Mermaid

````markdown
<!-- archify: workflow · diagrams/PROCESS_to-be.workflow.json -->
```mermaid
flowchart TD
    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 (`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 (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 --> [*]
```
````

### 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 Settlement API
    participant POS as Hệ thống POS

    U->>FE: Bấm Lưu
    FE->>BE: POST /stores
    BE->>POS: GET /verify (timeout 3s)
    alt POS phản hồi kịp
        POS-->>BE: 200 OK
        BE-->>FE: 200 + id
        FE-->>U: Toast "Đã lưu"
    else POS 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
```
````

### 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
    x-axis "Quan tâm thấp" --> "Quan tâm cao"
    y-axis "Ảnh hưởng thấp" --> "Ảnh hưởng cao"
    quadrant-1 "Quản lý sát"
    quadrant-2 "Giữ hài lòng"
    quadrant-3 "Theo dõi"
    quadrant-4 "Giữ thông tin"
    "STK-01 Trưởng phòng TC": [0.85, 0.90]
```
````

⚠️ `quadrantChart` cần mermaid ≥ 10; giữ bảng phân nhóm bên dưới làm dự phòng.

---

## 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` + `.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ơ đồ > 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. 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
```