# bpmn

**Repository Path**: SweetSunnyFlower/bpmn

## Basic Information

- **Project Name**: bpmn
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-04
- **Last Updated**: 2026-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BPMN 审批流编辑器

基于 bpmn.js 的可视化审批流程设计器，适配 Java Flowable 后端引擎，导出标准 BPMN 2.0 XML。

## 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue 3 | ^3.5 | Composition API + `<script setup>` |
| Vite | ^6.2 | 构建工具 |
| Tailwind CSS | ^3.4 | 原子化 CSS |
| bpmn-js | ^17.11 | BPMN 2.0 建模器 |
| Pinia | ^3.0 | 状态管理 |
| Axios | ^1.7 | HTTP 请求 |

## 快速开始

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 生产构建
npm run build
```

访问 `http://localhost:5173` 打开编辑器。

## 项目结构

```
src/
├── bpmn/                            # bpmn-js 核心配置
│   ├── flowableModdle.json          # Flowable 命名空间描述符
│   ├── modeler.js                   # BpmnModeler 工厂函数
│   ├── customTranslate/             # 中文翻译模块
│   │   ├── index.js
│   │   └── zh-CN.js
│   ├── customPalette/               # 自定义左侧工具栏
│   │   ├── index.js
│   │   └── CustomPaletteProvider.js
│   ├── customRenderer/              # 自定义画布渲染
│   │   ├── index.js
│   │   └── CustomRenderer.js
│   ├── customContextPad/            # 自定义右键快捷操作
│   │   ├── index.js
│   │   └── CustomContextPadProvider.js
│   └── utils/
│       ├── elementHelper.js         # BPMN 元素属性读写工具
│       ├── flowableHelper.js        # Flowable 属性操作工具
│       └── xml.js                   # XML 导入/导出/Camunda 兼容转换
├── assets/styles/
│   ├── index.css                    # Tailwind 指令 + 全局样式
│   └── bpmn-overrides.css           # bpmn-js 样式覆盖（Palette/ContextPad/图标）
├── components/
│   ├── BpmnEditor/                  # 编辑器主体
│   │   ├── index.vue                # 主布局（工具栏 + 画布 + 属性面板）
│   │   ├── BpmnCanvas.vue           # bpmn-js 画布容器
│   │   └── BpmnToolbar.vue          # 工具栏
│   └── PropertiesPanel/             # 自定义属性面板（Vue 3 原生）
│       ├── index.vue                # 面板容器，按元素类型动态切换
│       ├── GeneralProps.vue         # 通用属性（ID / 名称 / 描述）
│       ├── ProcessProps.vue         # 流程属性
│       ├── UserTaskProps.vue        # 用户任务属性
│       ├── ServiceTaskProps.vue     # 服务任务属性
│       ├── GatewayProps.vue         # 网关配置
│       ├── SequenceFlowProps.vue    # 连线条件表达式
│       ├── EventProps.vue           # 事件属性
│       ├── MultiInstanceProps.vue   # 多实例（会签/或签）
│       ├── ListenerProps.vue        # 执行监听器 / 任务监听器
│       └── components/              # 可复用子组件
├── api/                             # 后端 API 接口
│   ├── request.js                   # Axios 实例（拦截器、Token）
│   ├── workflow.js                  # 流程定义 CRUD
│   └── deployment.js               # 部署到 Flowable 引擎
├── stores/
│   └── editor.js                    # Pinia 编辑器状态
├── config/
│   └── index.js                     # 应用配置
└── utils/
    ├── download.js                  # 文件下载
    └── message.js                   # 消息提示
```

## 核心功能

### 流程建模

- 完整 BPMN 2.0 元素支持：开始/结束事件、用户任务、服务任务、排他/并行/包含网关、子流程、调用活动等
- 拖拽式画布编辑，支持连线、对齐、撤销/重做
- 缩放适配
- 全中文界面（Palette 图标下方直接显示中文名称）

### 属性面板

自定义 Vue 3 原生属性面板（未使用官方 Preact 版本），按元素类型动态渲染：

| 元素类型 | 可配置属性 |
|----------|-----------|
| 流程 (Process) | isExecutable、candidateStarterUsers/Groups、category |
| 用户任务 (UserTask) | assignee、candidateUsers、candidateGroups、formKey、dueDate、priority |
| 服务任务 (ServiceTask) | class / expression / delegateExpression 三种实现方式 |
| 网关 (Gateway) | 出口连线条件一览、默认流设置 |
| 顺序流 (SequenceFlow) | UEL 条件表达式 |
| 多实例 | 并行(会签)/串行、collection、elementVariable、completionCondition |
| 监听器 | 执行监听器、任务监听器（增删改） |

### 工具栏

新建 / 导入 / 导出 XML / 导出 SVG / 保存 / 撤销 / 重做 / 缩放 / 自适应 / 对齐 / XML 预览 / 部署

## Flowable 适配

### 命名空间

导出的 XML 使用 Flowable 标准命名空间：

```xml
xmlns:flowable="http://flowable.org/bpmn"
targetNamespace="http://flowable.org/bpmn"
```

### XML 输出示例

```xml
<bpmn2:userTask id="Task_1" name="经理审批"
  flowable:assignee="${manager}"
  flowable:candidateGroups="managers"
  flowable:formKey="approval-form"
  flowable:priority="50">
  <bpmn2:extensionElements>
    <flowable:taskListener event="complete"
      expression="${taskService.onComplete(task)}" />
  </bpmn2:extensionElements>
  <bpmn2:multiInstanceLoopCharacteristics isSequential="false">
    <bpmn2:completionCondition>
      ${nrOfCompletedInstances / nrOfInstances >= 0.5}
    </bpmn2:completionCondition>
  </bpmn2:multiInstanceLoopCharacteristics>
</bpmn2:userTask>
```

### Camunda 兼容

导入时自动将 `camunda:` 命名空间转换为 `flowable:`，兼容从 Camunda Modeler 导出的文件。

## 后端 API 对接

默认连接 `http://localhost:8080`，通过环境变量配置：

```bash
# .env.local
VITE_API_BASE_URL=http://your-server:8080
```

### 接口说明

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 保存流程 | POST | `/api/workflow/save` | 提交 `{ processId, processName, xml }` |
| 获取流程 | GET | `/api/workflow/:id` | 返回流程定义 |
| 流程列表 | GET | `/api/workflow/list` | 分页查询 |
| 删除流程 | DELETE | `/api/workflow/:id` | 删除定义 |
| 部署流程 | POST | `/api/deployment/create` | 上传 `.bpmn20.xml` 文件部署到 Flowable |
| 部署列表 | GET | `/api/deployment/list` | 查询部署记录 |

### Java 后端参考实现

```java
@RestController
@RequestMapping("/api/deployment")
public class DeploymentController {

    @Autowired
    private RepositoryService repositoryService;

    @PostMapping("/create")
    public Result create(@RequestParam("file") MultipartFile file,
                         @RequestParam("name") String name) {
        Deployment deployment = repositoryService.createDeployment()
            .name(name)
            .addInputStream(file.getOriginalFilename(), file.getInputStream())
            .deploy();
        return Result.success(deployment.getId());
    }
}
```

## 设计决策

**为什么自建属性面板而非使用官方 bpmn-js-properties-panel？**

1. 官方面板基于 Preact，嵌入 Vue 3 存在框架混用问题
2. 官方面板仅支持 Camunda 命名空间，Flowable 需要 hack 内部实现
3. 自建面板可完全使用 Tailwind CSS 样式，并实现自定义 UI（候选人选择器、表单配置等）
4. 所有属性修改通过 `modeling.updateModdleProperties()` 完成，保证撤销/重做一致性

## 自定义指南

项目的 UI 样式均可自行修改，以下是各个自定义点的文件位置和说明。

### 1. Palette（左侧工具栏）

**增删节点类型** → `src/bpmn/customPalette/CustomPaletteProvider.js`

- `descriptions` 对象：每个节点的 hover 提示文字（中文 + 英文 + 功能说明）
- `getPaletteEntries()` 返回的对象：控制 Palette 显示哪些条目
- 每个条目的 `className` 对应 CSS 图标类名（如 `custom-icon-user-task`）
- 添加新节点：在 return 对象中新增一条 `createAction(bpmnType, group, className, title)` 即可
- 移除节点：删除对应的条目

**Palette 布局和样式** → `src/assets/styles/bpmn-overrides.css`

- `.djs-palette` — 工具栏容器（位置、圆角、阴影、**宽度控制列数**）
  - 默认 `width: 130px`（2 列），矮屏 `192px`（3 列）
- `.djs-palette .entry` — 每个图标按钮（尺寸、圆角、flex 排列）
- `.djs-palette .entry::before` — 图标样式（字号）
- `.djs-palette .entry::after` — 图标下方中文标签样式（字号、颜色）

**图标下方中文标签** → `src/assets/styles/bpmn-overrides.css`（搜索 `仅 Palette`）

```css
/* 示例：修改文字 */
.djs-palette .custom-icon-user-task::after { content: '用户' !important; }

/* 示例：添加新节点的标签 */
.djs-palette .custom-icon-xxx::after { content: '新节点' !important; }
```

**图标 SVG** → `src/assets/styles/bpmn-overrides.css`（搜索对应类名 `::before`）

每个图标使用内联 SVG data URI 作为背景图，如：

```css
.custom-icon-user-task::before {
  content: '' !important;
  display: block;
  width: 22px; height: 22px;
  background: url("data:image/svg+xml,...") no-repeat center / contain;
}
```

替换 `url(...)` 中的 SVG 即可更换图标。可使用 [URL Encoder for SVG](https://yoksel.github.io/url-encoder/) 工具转换。

### 2. Canvas Renderer（画布节点渲染）

**节点颜色、形状、边框** → `src/bpmn/customRenderer/CustomRenderer.js`

- `COLORS` 对象：各类型节点的填充色和边框色
- `drawShape()` 方法：控制每种节点的画布渲染逻辑
  - Task 类节点：圆角矩形 + 左侧彩色指示条
  - 网关：菱形 + 内部符号
  - 事件：圆形 + 不同的边框/填充
- `drawConnection()` 方法：连线样式

### 3. Context Pad（点击节点弹出的快捷操作）

**操作按钮增删** → `src/bpmn/customContextPad/CustomContextPadProvider.js`

- `getContextPadEntries()` 返回的 `actions` 对象：控制显示哪些操作
- 当前内置：删除、连线、追加用户任务、追加排他网关、追加结束事件
- 添加新操作：在 `actions` 中新增条目，使用 `appendAction(type, className, title)`
- 每个条目的 `className` 同样对应 CSS 图标类名

**按钮样式** → `src/assets/styles/bpmn-overrides.css`（搜索 `Context Pad`）

- `.djs-context-pad .entry` — 按钮尺寸、圆角、阴影
- `.djs-context-pad .entry:hover` — 悬停效果

> 注意：Context Pad 中的图标复用 Palette 的 `::before` SVG 图标，但**不显示** `::after` 中文标签（已通过 `.djs-palette` 前缀限定）。

### 4. 中文翻译

**翻译字典** → `src/bpmn/customTranslate/zh-CN.js`

- 键为 bpmn-js 英文原文，值为中文翻译
- 格式建议：`'Send Task': '发送任务 (Send Task)'`（保留英文方便搜索）
- 覆盖范围：元素名称、Popup Menu、属性面板标签、校验消息等

**翻译机制** → `src/bpmn/customTranslate/index.js`

- 通过直接修改内置 `translateModule.translate` 属性实现全局替换
- 无需额外配置，所有依赖 `translate` 的内部模块自动使用中文

### 5. 属性面板

**按元素类型显示不同面板** → `src/components/PropertiesPanel/index.vue`

- 根据 `element.businessObject.$type` 动态渲染对应组件
- 添加新元素类型的面板：创建新的 `XxxProps.vue`，在 `index.vue` 中添加判断条件

**各属性面板** → `src/components/PropertiesPanel/` 下各组件

| 文件 | 对应元素 | 可配置项 |
|------|----------|----------|
| `GeneralProps.vue` | 所有元素 | id、name、documentation |
| `ProcessProps.vue` | Process | isExecutable、candidateStarter、category |
| `UserTaskProps.vue` | UserTask | assignee、candidateUsers/Groups、formKey、dueDate、priority |
| `ServiceTaskProps.vue` | ServiceTask | class / expression / delegateExpression |
| `GatewayProps.vue` | Gateway | 出口连线条件、默认流 |
| `SequenceFlowProps.vue` | SequenceFlow | 条件表达式 |
| `EventProps.vue` | Event | 事件类型、定义 |
| `MultiInstanceProps.vue` | 任意 Task | 串行/并行、collection、completionCondition |
| `ListenerProps.vue` | 任意元素 | 执行监听器、任务监听器 |

**可复用子组件** → `src/components/PropertiesPanel/components/`

- `PropertyGroup.vue` — 可折叠分组容器
- `PropertyField.vue` — 标签 + 输入框的统一布局
- `ExpressionEditor.vue` — UEL 表达式编辑器
- `ListEditor.vue` — 通用列表编辑器（用于监听器等）

### 6. Flowable 扩展属性

**Moddle 描述符** → `src/bpmn/flowableModdle.json`

定义了 `flowable:` 命名空间下的所有类型和属性，bpmn-js 据此读写 XML。新增 Flowable 属性时需在此文件中添加类型定义。

**属性读写工具** → `src/bpmn/utils/flowableHelper.js`

- `getFlowableProperty()` / `setFlowableProperty()` — 通用读写
- `getConditionExpression()` / `setConditionExpression()` — 条件表达式
- `getMultiInstanceConfig()` / `setMultiInstanceConfig()` — 多实例配置
- 监听器 CRUD 函数
- 所有写操作使用 `modeling.updateModdleProperties()` 保证撤销/重做