init git
This commit is contained in:
Leonard-ThindPad-P50
275
.claude/skills/ba-lifecycle/references/diagram-rules.md
Normal file
275
.claude/skills/ba-lifecycle/references/diagram-rules.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# 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ơ đồ.
|
||||
Reference in New Issue
Block a user