# Quy tắc vẽ sơ đồ trong tài liệu BA

Mọi sơ đồ trong bộ skill này viết bằng **mermaid**, không dùng ASCII art.

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 |

---

## W13 — Mỗi sơ đồ phải có bảng đi kèm

🔴 **Quy tắc quan trọng nhất của file này.**

**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ừ đó.

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

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

---

## Chọn loại sơ đồ

| Cần thể hiện | Dùng | Ở đâu trong bộ skill |
|---|---|---|
| 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 |

**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).

---

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

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

### Vòng đời trạng thái

````markdown
```mermaid
stateDiagram-v2
    state "Nháp" as Nhap
    state "Chờ duyệt" as ChoDuyet
    state "Đã duyệt" as DaDuyet
    state "Đã đóng" as DaDong

    [*] --> Nhap
    Nhap --> ChoDuyet: gửi duyệt (đủ trường bắt buộc)
    ChoDuyet --> DaDuyet: duyệt
    ChoDuyet --> Nhap: từ chố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

````markdown
```mermaid
sequenceDiagram
    autonumber
    actor U as Nhân viên
    participant FE as Giao diện
    participant BE as Hệ thống
    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
        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

````markdown
```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]
    "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.

---

## Khi mermaid không diễn đạt được

Ba trường hợp, và cách xử lý:

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

**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ơ đồ.