update skill and docs

2026-09-22 13:46:36 +07:00
parent 343ad8bbbc
commit 51506aabc7
149 changed files with 43752 additions and 300 deletions
--- a/.claude/skills/ba-2-analysis/SKILL.md
+++ b/.claude/skills/ba-2-analysis/SKILL.md
@@ -25,7 +25,13 @@ Nạp thêm: `../ba-lifecycle/references/domain-profiles.md` · `../ba-lifecycle
 (giai đoạn này sinh nhiều sơ đồ nhất: quy trình, use case, trạng thái, ERD).
 Ví dụ minh hoạ nhiều domain: `examples.md`.

-🔴 **Mọi sơ đồ vẽ bằng mermaid, không ASCII art, và luôn có bảng đi kèm** (quy tắc W13).
+🔴 **Mọi sơ đồ theo chuẩn Archify** (`W13`, `../ba-lifecycle/references/diagram-rules.md`): spec JSON
+`diagrams/<ARTIFACT>_<slug>.<type>.json` (`quality_profile: showcase`, validate 0 lỗi) **+** mermaid có
+marker `<!-- archify: <type> · <spec> -->` (hoặc `mermaid-only` cho ERD/use case/2×2) **+** bảng đi kèm.
+Một đường chính, ≤ 12 node, nhãn cạnh là điều kiện/giao thức, không màu. Không có Bash ⇒ ghi
+`humanInputNeeded` "chạy archify validate/deliver + diagram-check", không tự nhận đã validate.
+Quy trình → `workflow` · vòng đời → `lifecycle` · use case, cây RQ→US, ERD → `mermaid-only`. Spec mẫu
+đã pass: `templates/diagrams/PROCESS_to-be.workflow.json`, `templates/diagrams/BR_vong-doi.lifecycle.json`.
 Sơ đồ để nhìn, bảng để truy vết và test — sơ đồ đứng một mình là bức tranh đẹp mà QA không
 viết được test case từ đó.

--- a/.claude/skills/ba-2-analysis/templates/business-rules.md
+++ b/.claude/skills/ba-2-analysis/templates/business-rules.md
@@ -81,6 +81,7 @@

 **Sơ đồ:**

+<!-- archify: lifecycle · diagrams/BR_vong-doi-<thuc-the>.lifecycle.json -->
 ```mermaid
 stateDiagram-v2
    state "Nháp" as Nhap
@@ -115,6 +116,7 @@ stateDiagram-v2
 🔴 **Mục bắt buộc khi US có từ 2 thực thể trở lên.** Không có nó, dev tự suy ra quan hệ giữa
 các thực thể từ những bảng field rời rạc của từng màn hình — và mỗi người suy một kiểu.

+<!-- archify: mermaid-only -->
 ```mermaid
 erDiagram
    CUA_HANG ||--o{ GIAO_DICH : "phát sinh"
--- a/.claude/skills/ba-2-analysis/templates/diagrams/BR_vong-doi.lifecycle.json
+++ b/.claude/skills/ba-2-analysis/templates/diagrams/BR_vong-doi.lifecycle.json
@@ -0,0 +1,157 @@
+{
+  "schema_version": 1,
+  "diagram_type": "lifecycle",
+  "meta": {
+    "title": "Vòng đời Phiếu chênh lệch (mẫu)",
+    "quality_profile": "showcase",
+    "viewBox": [
+      1080,
+      640
+    ],
+    "views": [
+      {
+        "id": "duong-chinh",
+        "label": "Đường chính",
+        "focus": [
+          "Nhap",
+          "ChoDuyet",
+          "DaDuyet",
+          "DaDong"
+        ],
+        "note": "Nháp → Chờ duyệt → Đã duyệt → Đã đóng."
+      },
+      {
+        "id": "tu-choi",
+        "label": "Bị từ chối",
+        "focus": [
+          "ChoDuyet",
+          "TuChoi",
+          "Nhap"
+        ],
+        "note": "Từ chối quay về Nháp để sửa, không phải trạng thái cuối."
+      }
+    ]
+  },
+  "lanes": [
+    {
+      "id": "main",
+      "label": "Trạng thái chính"
+    },
+    {
+      "id": "waiting",
+      "label": "Chờ người"
+    },
+    {
+      "id": "terminal",
+      "label": "Kết thúc"
+    }
+  ],
+  "states": [
+    {
+      "id": "Nhap",
+      "type": "start",
+      "label": "Nháp",
+      "sublabel": "ROLE-01 tạo",
+      "lane": "main",
+      "col": 0,
+      "step": "01"
+    },
+    {
+      "id": "ChoDuyet",
+      "type": "waiting",
+      "label": "Chờ duyệt",
+      "sublabel": "gửi khi đủ trường",
+      "lane": "main",
+      "col": 1,
+      "step": "02"
+    },
+    {
+      "id": "DaDuyet",
+      "type": "active",
+      "label": "Đã duyệt",
+      "sublabel": "ROLE-02 · BR-021",
+      "lane": "main",
+      "col": 2,
+      "step": "03"
+    },
+    {
+      "id": "DaDong",
+      "type": "success",
+      "label": "Đã đóng",
+      "sublabel": "có ghi chú lý do",
+      "lane": "main",
+      "col": 3,
+      "step": "04"
+    },
+    {
+      "id": "TuChoi",
+      "type": "failure",
+      "label": "Bị từ chối",
+      "sublabel": "quay về Nháp",
+      "lane": "waiting",
+      "col": 0,
+      "tag": "phục hồi được"
+    }
+  ],
+  "transitions": [
+    {
+      "id": "t1",
+      "from": "Nhap",
+      "to": "ChoDuyet",
+      "label": "gửi duyệt",
+      "labelDy": 55
+    },
+    {
+      "id": "t2",
+      "from": "ChoDuyet",
+      "to": "DaDuyet",
+      "label": "duyệt ≤ 10tr",
+      "variant": "emphasis",
+      "labelDy": -30,
+      "route": "straight"
+    },
+    {
+      "id": "t3",
+      "from": "DaDuyet",
+      "to": "DaDong",
+      "label": "đóng",
+      "labelDy": 55
+    },
+    {
+      "id": "t4",
+      "from": "ChoDuyet",
+      "to": "TuChoi",
+      "label": "từ chối",
+      "variant": "security",
+      "labelDy": 40
+    },
+    {
+      "id": "t5",
+      "from": "TuChoi",
+      "to": "Nhap",
+      "label": "sửa lại",
+      "variant": "dashed",
+      "route": "left-channel",
+      "fromSide": "left",
+      "toSide": "left"
+    }
+  ],
+  "cards": [
+    {
+      "dot": "cyan",
+      "title": "Đường chính",
+      "items": [
+        "Bốn trạng thái, Đã đóng là trạng thái cuối duy nhất",
+        "Chỉ ROLE-02 được duyệt, người tạo không tự duyệt (SoD)"
+      ]
+    },
+    {
+      "dot": "rose",
+      "title": "Chuyển bị cấm",
+      "items": [
+        "Đã đóng không quay lại bất kỳ trạng thái nào",
+        "Nháp không nhảy thẳng sang Đã duyệt — xem bảng chuyển bị cấm BR §3"
+      ]
+    }
+  ]
+}
--- a/.claude/skills/ba-2-analysis/templates/diagrams/PROCESS_to-be.workflow.json
+++ b/.claude/skills/ba-2-analysis/templates/diagrams/PROCESS_to-be.workflow.json
@@ -0,0 +1,228 @@
+{
+  "schema_version": 2,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "Quy trình TO-BE — Đối soát cuối ca (mẫu)",
+    "quality_profile": "showcase",
+    "views": [
+      {
+        "id": "duong-chinh",
+        "label": "Đường chính",
+        "focus": [
+          "START",
+          "B1",
+          "B2",
+          "D1",
+          "END"
+        ],
+        "note": "Không lệch thì kết thúc ngay sau đối soát tự động."
+      },
+      {
+        "id": "nhanh-lech",
+        "label": "Nhánh có sai lệch",
+        "focus": [
+          "D1",
+          "B3",
+          "B4",
+          "END"
+        ],
+        "note": "Có lệch: hệ thống tạo phiếu, trưởng nhóm duyệt."
+      }
+    ]
+  },
+  "lanes": [
+    {
+      "id": "cua_hang",
+      "label": "Cửa hàng"
+    },
+    {
+      "id": "he_thong",
+      "label": "Hệ thống đối soát"
+    },
+    {
+      "id": "truong_nhom",
+      "label": "Trưởng nhóm"
+    },
+    {
+      "id": "ngoai_le",
+      "label": "Ngoại lệ",
+      "variant": "exception"
+    }
+  ],
+  "phases": [
+    {
+      "id": "thu_thap",
+      "label": "Thu thập",
+      "fromCol": 0,
+      "toCol": 1
+    },
+    {
+      "id": "doi_soat",
+      "label": "Đối soát tự động",
+      "fromCol": 2,
+      "toCol": 3,
+      "variant": "emphasis"
+    },
+    {
+      "id": "xu_ly",
+      "label": "Xử lý lệch",
+      "fromCol": 4,
+      "toCol": 5
+    }
+  ],
+  "mainPath": [
+    "START",
+    "B1",
+    "B2",
+    "D1",
+    "END"
+  ],
+  "nodes": [
+    {
+      "id": "START",
+      "lane": "cua_hang",
+      "col": 0,
+      "type": "external",
+      "label": "Kết ca",
+      "sublabel": "sự kiện kích hoạt",
+      "width": 120
+    },
+    {
+      "id": "B1",
+      "lane": "cua_hang",
+      "col": 1,
+      "type": "frontend",
+      "label": "🆕 B1 Tải file POS",
+      "sublabel": "SCR-01 · ROLE-01",
+      "width": 150
+    },
+    {
+      "id": "B2",
+      "lane": "he_thong",
+      "col": 2,
+      "type": "backend",
+      "label": "🆕 B2 Đối soát tự động",
+      "sublabel": "BR-014 · ⏱ ≤ 5 phút",
+      "width": 170
+    },
+    {
+      "id": "D1",
+      "lane": "he_thong",
+      "col": 3,
+      "type": "backend",
+      "label": "D1 Có sai lệch?",
+      "sublabel": "ngưỡng BR-015",
+      "width": 140
+    },
+    {
+      "id": "B3",
+      "lane": "he_thong",
+      "col": 4,
+      "type": "backend",
+      "label": "🔄 B3 Tạo phiếu lệch",
+      "sublabel": "CHENH_LECH · Chờ duyệt",
+      "width": 160
+    },
+    {
+      "id": "B4",
+      "lane": "truong_nhom",
+      "col": 5,
+      "type": "frontend",
+      "label": "⬜ B4 Duyệt phiếu",
+      "sublabel": "SCR-04 · ROLE-02",
+      "width": 150
+    },
+    {
+      "id": "END",
+      "lane": "he_thong",
+      "col": 5,
+      "type": "database",
+      "label": "Kết thúc",
+      "sublabel": "ghi sổ đối soát",
+      "width": 130
+    },
+    {
+      "id": "X1",
+      "lane": "ngoai_le",
+      "col": 2,
+      "type": "security",
+      "label": "File hỏng",
+      "sublabel": "E-POS-0400",
+      "width": 160
+    }
+  ],
+  "edges": [
+    {
+      "from": "START",
+      "to": "B1",
+      "label": "cuối ca"
+    },
+    {
+      "from": "B1",
+      "to": "B2",
+      "label": "file hợp lệ",
+      "variant": "emphasis"
+    },
+    {
+      "from": "B2",
+      "to": "D1",
+      "variant": "emphasis"
+    },
+    {
+      "from": "D1",
+      "to": "END",
+      "label": "không lệch",
+      "variant": "emphasis"
+    },
+    {
+      "from": "D1",
+      "to": "B3",
+      "label": "lệch > ngưỡng",
+      "role": "branch"
+    },
+    {
+      "from": "B3",
+      "to": "B4",
+      "label": "gửi duyệt",
+      "role": "branch"
+    },
+    {
+      "from": "B4",
+      "to": "END",
+      "label": "đã duyệt",
+      "role": "branch"
+    },
+    {
+      "from": "B1",
+      "to": "X1",
+      "label": "file sai định dạng",
+      "variant": "security",
+      "role": "error"
+    },
+    {
+      "from": "X1",
+      "to": "B1",
+      "label": "tải lại",
+      "variant": "dashed",
+      "role": "return"
+    }
+  ],
+  "cards": [
+    {
+      "dot": "emerald",
+      "title": "Thay đổi so với AS-IS",
+      "items": [
+        "🆕 B1, B2 thay bước copy Excel thủ công (A2, A3 bỏ)",
+        "Thời gian đối soát từ 2 giờ xuống ≤ 5 phút (GOAL-01)"
+      ]
+    },
+    {
+      "dot": "rose",
+      "title": "Ngoại lệ",
+      "items": [
+        "File sai định dạng trả về cửa hàng kèm E-POS-0400, không vào đối soát",
+        "Lệch vượt ngưỡng BR-015 bắt buộc trưởng nhóm duyệt (SoD)"
+      ]
+    }
+  ]
+}
--- a/.claude/skills/ba-2-analysis/templates/process-model.md
+++ b/.claude/skills/ba-2-analysis/templates/process-model.md
@@ -34,6 +34,7 @@

 ## A1. Sơ đồ luồng

+<!-- archify: workflow · diagrams/PROCESS_as-is.workflow.json -->
 ```mermaid
 flowchart TD
    START(["Sự kiện kích hoạt: …"]) --> A1["A1. &lt;việc&gt; · &lt;vai trò&gt; · ⏱ …"]
@@ -105,6 +106,7 @@ thành defect ở UAT.

 ## B1. Sơ đồ luồng

+<!-- archify: workflow · diagrams/PROCESS_to-be.workflow.json -->
 ```mermaid
 flowchart TD
    START(["Sự kiện kích hoạt: …"]) --> B1["🆕 B1. &lt;việc&gt; · &lt;vai trò&gt; · ⏱ …"]
--- a/.claude/skills/ba-2-analysis/templates/user-story-backlog.md
+++ b/.claude/skills/ba-2-analysis/templates/user-story-backlog.md
@@ -22,6 +22,7 @@
 *Một hình cho PO thấy **ai làm được gì** trong phạm vi này. Đây là thứ mang vào buổi duyệt
 G2, không phải bảng US 40 dòng.*

+<!-- archify: mermaid-only -->
 ```mermaid
 flowchart LR
    NV(["👤 Nhân viên đối soát"])
@@ -65,6 +66,7 @@ lượng, phụ thuộc, hay `RQ` nào sinh ra US đó.

 ## 1. Cây phân rã

+<!-- archify: mermaid-only -->
 ```mermaid
 flowchart LR
    RQ007["RQ-007 &lt;phát biểu ngắn&gt;"]