BPMN 2.0 diagrams

Từ v2.1.0, Bakit sinh BPMN 2.0 chuẩn OMG qua kiến trúc 2 lớp: producer chỉ viết business intent, engine của controller làm phần kỹ thuật. BA không bao giờ phải chạm vào XML hay tọa độ.

Kiến trúc 2 lớp

Producer (BA)                    Engine (controller)
─────────────                    ───────────────────
viết business intent:      →     semcheck
  {process}.ir.json              layout (grid/auto)
  {process}.src.json             emit OMG BPMN 2.0 XML
                                 rebuild editor HTML

• Producer viết: IR (intent) + src (facts để semcheck coverage)
• Engine làm: semcheck → layout → XML → editor rebuild
• Producer không bao giờ viết: .bpmn XML hay tọa độ

Yêu cầu

• Use case canon (usecases/index.md) — không có thì fallback sang phỏng vấn business language 4 nhóm: roles/lanes, main steps, decision points, outcomes
• Node.js ≥18 trên PATH — thiếu node thì command từ chối nhẹ nhàng: "node runtime required for BPMN engine. Install Node.js >=18 or run bakit doctor."

Cách gọi

/ba-start bpmn --slug <slug> --module <module_slug>

File producer viết

{process}.ir.json — business intent

{
  "process": { "id": "login-email", "title": "Đăng nhập bằng email" },
  "lanes": [...],
  "nodes": [
    { "kind": "start|task|gateway|end", "lane": "...", "name": "..." }
  ],
  "flows": [
    { "src": "...", "tgt": "...", "name": "điều kiện nhánh" }
  ]
}

IR là source of intent — update mode chỉ sửa IR, layout tự regenerate.

{process}.src.json — facts cho coverage semcheck

{ "actors": [...], "branches": [...], "errors": [...] }

Bắt buộc per process — extract từ use cases.

Quy tắc: 1 process = 1 business goal

login-email và login-google là 2 process riêng, không gộp.

Mapping từ use case sang IR (deterministic)

Recoverable errors (user sửa rồi resubmit) = back-edge từ task "Show message" về retry point — không bao giờ là terminal end, không bao giờ self-loop.

Naming conventions

• task = verb + object ("Nhập email")
• gateway = câu hỏi quyết định ("Credentials valid?")
• gateway outgoing flow = điều kiện nhánh ngắn ("Valid" / "Invalid")
• end = terminal outcome
• Business language only

Engine chạy

ba-kit bpmn-build --dir {bpmn_root} --verify

Engine: semcheck (structural blocks, coverage warns) → layout (grid nếu ≥1 lane, else auto) → emit OMG BPMN 2.0 XML {process}.bpmn → rebuild {module}-bpmn-editor.html.

--verify check XML markers + geometry: overlapping collinear segments và edges cắt task bodies làm build fail. Không báo success khi --verify chưa pass.

Kết quả tạo ra

03_modules/{module}/bpmn/
├── {process}.ir.json          # Producer: intent
├── {process}.src.json         # Producer: facts
├── {process}.bpmn             # Engine: OMG XML
├── {module}-bpmn-editor.html  # Engine: editor viewer
└── index.md                   # BPMN index

Lỗi thường gặp

• Tự viết XML hoặc tọa độ bằng tay → phá vỡ kiến trúc 2 lớp; sửa IR rồi rebuild
• Gateway chỉ có 1 outgoing branch → invalid; bỏ gateway hoặc thêm nhánh
• Coverage warnings → đọc lại use case; thêm actor/branch/error còn thiếu vào IR nếu thực sự thiếu, nếu không thì chấp nhận warning
• Editor cần internet lần đầu — bpmn-js load từ CDN

Tiếp theo

• ba-start — toàn bộ pipeline
• Hướng dẫn từng bước — flow thực tế