276 lines
9.1 KiB
Markdown
276 lines
9.1 KiB
Markdown
# 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 | Wireframe ảnh — mermaid không phải công cụ vẽ UI |
|
||
| 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ơ đồ.
|