M-002: Workflow Module — Kiến trúc Kỹ thuật

Version: v1-draft | Date: 2026-03-03 Lead: claude_ai | Critic: gemini Status: ✅ APPROVED — bpmn-js (Camunda). Bắt đầu Sprint 2. Giải pháp: bpmn-js v18+ | BPMN 2.0 XML | ~80 dòng Vue wrapper

---

1. Tổng quan Kiến trúc

┌─────────────────────────────────────────────────┐
│                    Nuxt Frontend                 │
│                                                  │
│  ┌──────────────────┐  ┌──────────────────────┐  │
│  │ WorkflowViewer   │  │ WorkflowModeler      │  │
│  │ (bpmn-js viewer) │  │ (bpmn-js modeler)    │  │
│  │ Read-only display│  │ Drag-drop + Annotate │  │
│  │ ~ 50 dòng        │  │ ~ 80 dòng            │  │
│  └────────┬─────────┘  └────────┬─────────────┘  │
│           │                     │                 │
│  ┌────────┴─────────────────────┴─────────────┐  │
│  │          useWorkflows.ts                    │  │
│  │  Composable: CRUD workflows, load XML      │  │
│  └────────────────────┬───────────────────────┘  │
│                       │                           │
│  ┌────────────────────┴───────────────────────┐  │
│  │          CommentModule (M-001)              │  │
│  │  Annotations → Intent → Comment            │  │
│  └────────────────────────────────────────────┘  │
└───────────────────────┬───────────────────────────┘
                        │ REST API
┌───────────────────────┴───────────────────────────┐
│                   Directus CMS                     │
│  Collection: workflows                             │
│  - id, title, bpmn_xml, status, task_id            │
└───────────────────────┬───────────────────────────┘
                        │ Webhook / Prefect
┌───────────────────────┴───────────────────────────┐
│              Prefect Orchestrator (Phase 3)         │
│  BPMN XML → Parse → Generate Prefect Flows         │
└────────────────────────────────────────────────────┘

2. Component Architecture

2.1 Cấu trúc file

components/modules/workflow-module/
├── WorkflowViewer.vue          # Viewer (read-only BPMN diagram)
├── WorkflowModeler.vue         # Modeler (edit + annotations) [Sprint 4]
├── composables/
│   └── useWorkflows.ts         # Logic: load/save BPMN XML
├── types.ts                    # TypeScript interfaces
└── README.md                   # Docs cho Claude Code CLI

2.2 Protocol Definition

Mục	Chi tiết
Props	workflow-id (required, number) — ID workflow trong Directus
	task-id (optional, number) — Liên kết với task
	mode (optional, 'viewer' | 'modeler') — Chế độ hiển thị, default: 'viewer'
	height (optional, string) — Chiều cao container, default: '500px'
Events	@workflow-loaded — Khi BPMN XML load xong
	@annotation-added — Khi user thêm annotation trên diagram
	@workflow-saved — Khi XML được lưu về Directus
Data Source	Collection: workflows (Directus — cần tạo)
	Composable: useWorkflows(workflowId)
Permissions	Public: read (viewer)

2.3 useWorkflows Composable

interface UseWorkflowsOptions {
  workflowId: number
}

interface UseWorkflowsReturn {
  workflow: Ref<Workflow | null>
  bpmnXml: Ref<string>
  loading: Ref<boolean>
  error: Ref<string | null>
  loadWorkflow: () => Promise<void>
  saveWorkflow: (xml: string) => Promise<void>
  parseAnnotations: (xml: string) => Annotation[]
}

3. Data Model

Collection: workflows (Directus — cần tạo Sprint 1)

Field	Type	Description
id	integer (PK)	Auto
title	string	Tên workflow
description	text (nullable)	Mô tả
bpmn_xml	text	BPMN 2.0 XML content
status	enum	draft / active / archived
task_id	integer (FK, nullable)	Liên kết task
version	integer	Version counter
date_created	datetime	Auto
date_updated	datetime	Auto

4. Phân tầng triển khai

Phase 1 — Viewer (Sprint 2)

<!-- WorkflowViewer.vue — ~50 dòng -->
<template>
  <div ref="container" :style="{ height }" />
</template>

<script setup>
import BpmnViewer from 'bpmn-js'

const props = defineProps({
  workflowId: { type: Number, required: true },
  height: { type: String, default: '500px' }
})

// Load XML từ Directus → render bpmn-js viewer
</script>

Deliverables:

• npm install bpmn-js trong project
• WorkflowViewer.vue — render BPMN diagram
• useWorkflows.ts — load XML từ Directus
• BPMN XML mẫu — 1 workflow đơn giản để test
• Lắp vào trang Tasks hoặc trang riêng

Phase 2 — Modeler + Annotations (Sprint 4)

<!-- WorkflowModeler.vue — ~80 dòng -->
<template>
  <div ref="container" :style="{ height }" />
</template>

<script setup>
import BpmnModeler from 'bpmn-js/lib/Modeler'
// Modeler = Viewer + editing capabilities + Annotations
</script>

Deliverables:

• WorkflowModeler.vue — drag-drop BPMN editor
• Annotation support: click node → ghi chú intent
• Save modified XML về Directus

Phase 3 — Prefect Integration (sau Sprint 4)

• AI đọc BPMN XML → parse annotations → hiểu intent
• Auto-generate Prefect flow code từ BPMN structure
• Selftest → deploy → evidence report

5. Liên thông M-001 ↔ M-002

User thêm Annotation trên BPMN diagram
  → WorkflowModeler emit @annotation-added
  → Auto-create comment trong CommentModule (tab: planning)
  → AI Critic đọc comment → review → approve/reject
  → Nếu approved → save XML mới → re-render viewer

Fields liên thông (thêm vào task_comments):

• workflow_id (nullable) — comment liên quan workflow nào
• bpmn_element_id (nullable) — node/edge nào trên diagram

6. bpmn-js Key Facts

Thông tin	Giá trị
GitHub	bpmn-io/bpmn-js
Stars	9,000+
Version	v18.10+
License	MIT (viewer) / Camunda (modeler features)
Format	BPMN 2.0 XML
Bundles	Viewer (~200KB) / Modeler (~400KB)
Dependencies	diagram-js, bpmn-moddle

7. Liên kết

• Tech evaluation: tech-evaluation.md
• Discussions: discussions.md
• Execution plan: modules-execution-plan.md
• Comment Module (M-001): ../comment-module/design.md
• Module Protocol: search_knowledge("module protocol standard")

---

Claude Code CLI: Sprint 2 bắt đầu từ npm install bpmn-js. Đọc Phase 1 deliverables trước khi code.