@qilitt-mickey/vue3-temp-skill 1.0.12 → 1.1.2

package/references/workflow-bpmn.md

@@ -1,206 +1,207 @@
-# BPMN 工作流查看器
-
-## 依赖
-
-`bpmn-js/lib/Viewer` — BPMN 流程图的只读查看器（不含建模器）。
-
-## 类型定义
-
-```typescript
-// src/views/workflow/types/bpmn.ts
-
-export type BpmnElementType =
-  | 'bpmn:StartEvent' | 'bpmn:EndEvent'
-  | 'bpmn:UserTask' | 'bpmn:ServiceTask'
-  | 'bpmn:ExclusiveGateway' | 'bpmn:SequenceFlow' | 'bpmn:Process'
-
-export interface BpmnElement {
-  id: string
-  type: string | BpmnElementType
-  name?: string
-  businessObject?: any
-}
-
-export interface ProcessInfo {
-  finishedTasks?: string[]
-  finishedTaskSet?: Set<string>
-  activeTasks?: string[]
-  activeTaskSet?: Set<string>
-  unfinishedTasks?: string[]
-  unfinishedTaskSet?: Set<string>
-  finishedSequenceFlows?: string[]
-  finishedSequenceFlowSet?: Set<string>
-}
-
-export interface BpmnWorkflowData {
-  xml: string
-  processInfo?: ProcessInfo
-}
-
-export interface WorkflowViewerProps {
-  xml?: string
-  processInfo?: ProcessInfo
-  height?: string | number
-  showToolbar?: boolean
-  allowExport?: boolean
-}
-```
-
-## 组件结构
-
-```vue
-<!-- src/views/workflow/components/WorkflowViewer.vue -->
-<script setup lang="ts">
-import Viewer from 'bpmn-js/lib/Viewer'
-import type { BpmnWorkflowData, ProcessInfo } from '../types/bpmn'
-
-defineOptions({ name: 'WorkflowViewer' })
-
-const props = withDefaults(defineProps<WorkflowViewerProps>(), {
-  height: '500px',
-  showToolbar: true,
-  allowExport: false,
-})
-
-const containerRef = ref<HTMLElement>()
-let viewer: Viewer | null = null
-
-// 初始化查看器
-const initViewer = async () => {
-  if (!containerRef.value) return
-  viewer = new Viewer({ container: containerRef.value })
-}
-
-// 导入 BPMN XML
-const importXml = async (xml: string) => {
-  if (!viewer) return
-  try {
-    await viewer.importXML(xml)
-    // 缩放适配
-    const canvas = viewer.get('canvas') as any
-    canvas.zoom('fit-viewport')
-  } catch (err) {
-    console.error('BPMN XML 导入失败', err)
-  }
-}
-
-// 高亮已完成/活动节点
-const highlightProcess = (processInfo: ProcessInfo) => {
-  if (!viewer) return
-  const canvas = viewer.get('canvas') as any
-  const elementRegistry = viewer.get('elementRegistry') as any
-
-  // 高亮已完成任务
-  processInfo.finishedTaskSet?.forEach((id: string) => {
-    const element = elementRegistry.get(id)
-    if (element) canvas.addMarker(id, 'bpmn-finished')
-  })
-
-  // 高亮当前活动任务
-  processInfo.activeTaskSet?.forEach((id: string) => {
-    const element = elementRegistry.get(id)
-    if (element) canvas.addMarker(id, 'bpmn-active')
-  })
-
-  // 高亮已完成序列流
-  processInfo.finishedSequenceFlowSet?.forEach((id: string) => {
-    const element = elementRegistry.get(id)
-    if (element) canvas.addMarker(id, 'bpmn-flow-finished')
-  })
-}
-
-// 导出 SVG
-const exportSvg = async () => {
-  if (!viewer) return null
-  const svgResult = await viewer.saveSVG()
-  return svgResult.svg
-}
-
-onMounted(async () => {
-  await initViewer()
-  if (props.xml) await importXml(props.xml)
-  if (props.processInfo) highlightProcess(props.processInfo)
-})
-
-onBeforeUnmount(() => {
-  viewer?.destroy()
-  viewer = null
-})
-</script>
-
-<template>
-  <div class="workflow-viewer">
-    <div v-if="showToolbar" class="viewer-toolbar">
-      <el-button size="small" @click="handleZoomIn">放大</el-button>
-      <el-button size="small" @click="handleZoomOut">缩小</el-button>
-      <el-button size="small" @click="handleFitView">适配</el-button>
-      <el-button v-if="allowExport" size="small" @click="handleExportSvg">导出 SVG</el-button>
-    </div>
-    <div ref="containerRef" :style="{ height: typeof height === 'number' ? height + 'px' : height }" />
-  </div>
-</template>
-
-<style>
-/* BPMN 高亮样式（全局，不加 scoped） */
-:deep(.bpmn-active) .djs-visual > :nth-child(1) {
-  fill: #409eff !important;
-  stroke: #409eff !important;
-}
-:deep(.bpmn-finished) .djs-visual > :nth-child(1) {
-  fill: #67c23a !important;
-  stroke: #67c23a !important;
-}
-:deep(.bpmn-flow-finished) .djs-visual > :nth-child(1) {
-  stroke: #67c23a !important;
-}
-</style>
-```
-
-## 页面调用
-
-```vue
-<!-- src/views/workflow/bpmn/index.vue -->
-<script setup lang="ts">
-import { ReDialog } from '@/components/ReDialog'
-import WorkflowViewer from '../components/WorkflowViewer.vue'
-
-defineOptions({ name: 'WorkflowBpmn' })
-const showDialog = ref(false)
-</script>
-
-<template>
-  <el-button type="primary" size="large" @click="showDialog = true">查看流程图</el-button>
-  <ReDialog v-model="showDialog" title="BPMN流程图查看器">
-    <WorkflowViewer />
-    <template #footer>
-      <el-button @click="showDialog = false">关闭</el-button>
-    </template>
-  </ReDialog>
-</template>
-```
-
-## 数据获取
-
-```typescript
-// API 返回格式
-interface WorkflowApiResponse {
-  data: BpmnWorkflowData  // { xml: string, processInfo?: ProcessInfo }
-  code?: number
-  message?: string
-}
-```
-
-## 关键约定
-
-1. 使用 `bpmn-js/lib/Viewer`（只读），不使用 `Modeler`（可编辑）除非有流程设计需求。
-2. 组件销毁时必须调用 `viewer.destroy()` 释放资源。
-3. 高亮通过 `canvas.addMarker(id, className)` 实现，CSS 使用 `:deep()` 穿透 BPMN 内部 SVG。
-4. 流程数据（已完成/活动任务）由后端接口统一返回，前端只负责渲染。
-5. 弹窗内使用时注意容器高度，BPMN 需要明确的宽高才能正确渲染。
-6. `canvas.zoom('fit-viewport')` 自动缩放适配视口。
-
-## 关联文件
-
-- [src/views/workflow/bpmn/index.vue](file:///e:/work/vue3-web-temp/src/views/workflow/bpmn/index.vue)
-- [src/views/workflow/components/WorkflowViewer.vue](file:///e:/work/vue3-web-temp/src/views/workflow/components/WorkflowViewer.vue)
-- [src/views/workflow/types/bpmn.ts](file:///e:/work/vue3-web-temp/src/views/workflow/types/bpmn.ts)
+# BPMN 工作流查看器
+
+> 按本文件示例编写；必须使用选型表中的 `bpmn-js` Viewer（见 project-inventory），勿改用同类其他流程引擎；新依赖须待确认。
+
+## 依赖（缺则先装）
+
+| 包 | 版本 | 说明 |
+|---|---|---|
+| `bpmn-js` | `18.19.0` | 仅用 `bpmn-js/lib/Viewer`（只读），不用 Modeler |
+
+```bash
+pnpm add bpmn-js@18.19.0
+```
+
+## 类型定义
+
+```typescript
+
+export type BpmnElementType =
+  | 'bpmn:StartEvent' | 'bpmn:EndEvent'
+  | 'bpmn:UserTask' | 'bpmn:ServiceTask'
+  | 'bpmn:ExclusiveGateway' | 'bpmn:SequenceFlow' | 'bpmn:Process'
+
+export interface BpmnElement {
+  id: string
+  type: string | BpmnElementType
+  name?: string
+  businessObject?: any
+}
+
+export interface ProcessInfo {
+  finishedTasks?: string[]
+  finishedTaskSet?: Set<string>
+  activeTasks?: string[]
+  activeTaskSet?: Set<string>
+  unfinishedTasks?: string[]
+  unfinishedTaskSet?: Set<string>
+  finishedSequenceFlows?: string[]
+  finishedSequenceFlowSet?: Set<string>
+}
+
+export interface BpmnWorkflowData {
+  xml: string
+  processInfo?: ProcessInfo
+}
+
+export interface WorkflowViewerProps {
+  xml?: string
+  processInfo?: ProcessInfo
+  height?: string | number
+  showToolbar?: boolean
+  allowExport?: boolean
+}
+```
+
+## 组件结构
+
+```vue
+<!-- WorkflowViewer.vue -->
+<script setup lang="ts">
+import Viewer from 'bpmn-js/lib/Viewer'
+import type { BpmnWorkflowData, ProcessInfo } from '../types/bpmn'
+
+defineOptions({ name: 'WorkflowViewer' })
+
+const props = withDefaults(defineProps<WorkflowViewerProps>(), {
+  height: '500px',
+  showToolbar: true,
+  allowExport: false,
+})
+
+const containerRef = ref<HTMLElement>()
+let viewer: Viewer | null = null
+
+// 初始化查看器
+const initViewer = async () => {
+  if (!containerRef.value) return
+  viewer = new Viewer({ container: containerRef.value })
+}
+
+// 导入 BPMN XML
+const importXml = async (xml: string) => {
+  if (!viewer) return
+  try {
+    await viewer.importXML(xml)
+    // 缩放适配
+    const canvas = viewer.get('canvas') as any
+    canvas.zoom('fit-viewport')
+  } catch (err) {
+    console.error('BPMN XML 导入失败', err)
+  }
+}
+
+// 高亮已完成/活动节点
+const highlightProcess = (processInfo: ProcessInfo) => {
+  if (!viewer) return
+  const canvas = viewer.get('canvas') as any
+  const elementRegistry = viewer.get('elementRegistry') as any
+
+  // 高亮已完成任务
+  processInfo.finishedTaskSet?.forEach((id: string) => {
+    const element = elementRegistry.get(id)
+    if (element) canvas.addMarker(id, 'bpmn-finished')
+  })
+
+  // 高亮当前活动任务
+  processInfo.activeTaskSet?.forEach((id: string) => {
+    const element = elementRegistry.get(id)
+    if (element) canvas.addMarker(id, 'bpmn-active')
+  })
+
+  // 高亮已完成序列流
+  processInfo.finishedSequenceFlowSet?.forEach((id: string) => {
+    const element = elementRegistry.get(id)
+    if (element) canvas.addMarker(id, 'bpmn-flow-finished')
+  })
+}
+
+// 导出 SVG
+const exportSvg = async () => {
+  if (!viewer) return null
+  const svgResult = await viewer.saveSVG()
+  return svgResult.svg
+}
+
+onMounted(async () => {
+  await initViewer()
+  if (props.xml) await importXml(props.xml)
+  if (props.processInfo) highlightProcess(props.processInfo)
+})
+
+onBeforeUnmount(() => {
+  viewer?.destroy()
+  viewer = null
+})
+</script>
+
+<template>
+  <div class="workflow-viewer">
+    <div v-if="showToolbar" class="viewer-toolbar">
+      <el-button size="small" @click="handleZoomIn">放大</el-button>
+      <el-button size="small" @click="handleZoomOut">缩小</el-button>
+      <el-button size="small" @click="handleFitView">适配</el-button>
+      <el-button v-if="allowExport" size="small" @click="handleExportSvg">导出 SVG</el-button>
+    </div>
+    <div ref="containerRef" :style="{ height: typeof height === 'number' ? height + 'px' : height }" />
+  </div>
+</template>
+
+<style>
+/* BPMN 高亮样式（全局，不加 scoped） */
+:deep(.bpmn-active) .djs-visual > :nth-child(1) {
+  fill: #409eff !important;
+  stroke: #409eff !important;
+}
+:deep(.bpmn-finished) .djs-visual > :nth-child(1) {
+  fill: #67c23a !important;
+  stroke: #67c23a !important;
+}
+:deep(.bpmn-flow-finished) .djs-visual > :nth-child(1) {
+  stroke: #67c23a !important;
+}
+</style>
+```
+
+## 页面调用
+
+```vue
+<!-- bpmn 页面示例 -->
+<script setup lang="ts">
+import { ReDialog } from '@/components/ReDialog'
+import WorkflowViewer from '../components/WorkflowViewer.vue'
+
+defineOptions({ name: 'WorkflowBpmn' })
+const showDialog = ref(false)
+</script>
+
+<template>
+  <el-button type="primary" size="large" @click="showDialog = true">查看流程图</el-button>
+  <ReDialog v-model="showDialog" title="BPMN流程图查看器">
+    <WorkflowViewer />
+    <template #footer>
+      <el-button @click="showDialog = false">关闭</el-button>
+    </template>
+  </ReDialog>
+</template>
+```
+
+## 数据获取
+
+```typescript
+// API 返回格式
+interface WorkflowApiResponse {
+  data: BpmnWorkflowData  // { xml: string, processInfo?: ProcessInfo }
+  code?: number
+  message?: string
+}
+```
+
+## 关键约定
+
+1. 使用 `bpmn-js/lib/Viewer`（只读），不使用 `Modeler`（可编辑）除非有流程设计需求。
+2. 组件销毁时必须调用 `viewer.destroy()` 释放资源。
+3. 高亮通过 `canvas.addMarker(id, className)` 实现，CSS 使用 `:deep()` 穿透 BPMN 内部 SVG。
+4. 流程数据（已完成/活动任务）由后端接口统一返回，前端只负责渲染。
+5. 弹窗内使用时注意容器高度，BPMN 需要明确的宽高才能正确渲染。
+6. `canvas.zoom('fit-viewport')` 自动缩放适配视口。