genneral/sys-analysis-design

Fork 0

Files

Leonard-ThindPad-P50 c81f249920 init git

2026-09-08 10:26:21 +07:00

9.1 KiB

Raw Blame History

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

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

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

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

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

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

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

9.1 KiB Raw Blame History Unescape Escape