@@ -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 tro ng `.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– `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–
| 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× `STAKEHOLDER` §2) | `quadrantChart` | — |
| Ma trận ≥ 3× **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>.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–
```
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 × (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 × `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× `quadrantChart` | `STAKEHOLDER` §2 |
| Ma trận 3× **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:
```
❌ Nhận file POS
```
Với `stateDiagram-v2` dùng dạng khai báo riêng:
```
```
### 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):
```
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 · ..."` · `"➖
### 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: 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"]
A 1 --> A2["A2. Xuất file cuối ca "]
A 2 --> D1{"Có sai lệch?"}
D1 -->|K hông| END( ["Kết thúc"] )
D1 -->|Có | A 3["⚠️ P1 · A3. Đối chiếu thủ công "]
A 3 --> 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"]
B 1 -->|file hợp lệ| B2["🆕 B2 Đối soát tự động "]
B 2 --> D1{"D1 Có sai lệch?"}
D1 -->|k hông lệch | END[( "Kết thúc")]
D1 -->|lệch > ngưỡng | B 3["🔄 B3 Tạo phiếu lệch "]
B 3 -->|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–
### 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×
### 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–
### 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× mermaid-only`)
` ```markdown
<!-- archify: mermaid-only -->
` ``mermaid
quadrantChart
title Stakeholder — Quan tâm ×
@@ -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 m ermaid không diễn đạt được
Ba trường hợp, và cách xử lý:
## 7. Khi M ermaid 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×
| Sơ đồ > 20 node | Tách thành nhiều sơ đồ theo phân vùng , mỗi cái một mục con |
1 2 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 |
vì "hình này mermaid vẽ xấu" . Xấu thì tách nhỏ hoặc
đổi loại sơ đồ.
đổ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
` ``
Canhchimlac