genneral/sys-analysis-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
51506aabc7f2e0946078c5ec1cbe594597ade36c
sys-analysis-design/.claude/skills/ba-lifecycle/references/diagram-rules.md
Canhchimlac 51506aabc7 update skill and docs
2026-09-22 13:46:36 +07:00

19 KiB
Raw Blame History

Chuẩn sơ đồ — theo tiêu chuẩn và phong cách Archify

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

Chuẩn tham chiếu: 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.

0. Ba câu chốt

  1. Một sơ đồ = spec JSON Archify + Mermaid trong .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 🔵/✅.

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–§5, §7 · 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–use case là liên kết, không phải luồng
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×2 (STAKEHOLDER §2) quadrantChart —
Ma trận ≥ 3×3, bảng số liệu 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 (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 / 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
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

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.

5. Tệp, marker, lệnh

5.1 Vị trí

<thư mục artifact>/diagrams/<ARTIFACT>_<slug>.<type>.json     ← spec (nguồn sự thật)
<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

<!-- 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ơ đồ

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–A7, exit 1 nếu 🔴

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 × số ký tự ASCII + 13 + 8 (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
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

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 trình (workflow) — Mermaid

<!-- archify: workflow · diagrams/PROCESS_to-be.workflow.json -->
```mermaid
flowchart TD
    START(["Kết ca"]) -->|cuối ca| B1["🆕 B1 Tải file POS"]
    B1 -->|file hợp lệ| B2["🆕 B2 Đối soát tự động"]
    B2 --> D1{"D1 Có sai lệch?"}
    D1 -->|không lệch| END[("Kết thúc")]
    D1 -->|lệch > ngưỡng| B3["🔄 B3 Tạo phiếu lệch"]
    B3 -->|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 (lifecycle) — Mermaid

<!-- 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 (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 --> [*]
```

Sequence (sequence) — Mermaid, bắt buộc nhánh lỗi

<!-- 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 Settlement API
    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 sau 3s
        BE-->>FE: 503 · E-STR-0503
        FE-->>U: Báo lỗi, GIỮ NGUYÊN dữ liệu đã nhập
    end
```

C4 Container (architecture) — Mermaid

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

<!-- 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–use case là liên kết, không phải luồng.

ERD khái niệm (mermaid-only)

<!-- 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×2 (mermaid-only)

<!-- archify: mermaid-only -->
```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]
```

⚠️ quadrantChart cần mermaid ≥ 10; giữ bảng phân nhóm bên dưới làm dự phòng.

7. Khi Mermaid 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 + .html (ba-3), HIFI (ba-design) — không phải sơ đồ
Ma trận ≥ 3×3, bảng số liệu Bảng markdown
Sơ đồ > 12 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

Không bao giờ quay lại ASCII art. Xấu thì tách nhỏ hoặc đổ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