405 lines
19 KiB
Markdown
405 lines
19 KiB
Markdown
# 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
|
||
```
|