jeecg-bpmn（jeecg bpmn 命令行）

JeecgBoot BPM 流程自动生成器

将自然语言的流程描述转换为 Flowable BPMN 2.0 XML，并通过 API 在 JeecgBoot 系统中自动创建流程。

前置条件

用户必须提供以下信息（或由 AI 引导确认）：

1. API 地址：JeecgBoot 后端地址（如 https://api3.boot.jeecg.com）
2. X-Access-Token：JWT 登录令牌（从浏览器 F12 获取）

如果用户未提供，提示：

请提供 JeecgBoot 后端地址和 X-Access-Token（从浏览器 F12 → Network → 任意请求的 Request Headers 中复制）。

交互流程

Step 0: 解析用户需求

从用户描述中提取以下信息：

Step 1: 识别节点并构建流程结构

支持的节点类型：

审批人配置映射：

审批人数据查询： 当用户提到具体角色/用户/部门名称时，可查数据库获取准确编码：

• 角色编码：SELECT role_code, role_name FROM sys_role
• 用户名：SELECT username, realname FROM sys_user
• 部门/岗位ID：SELECT id, depart_name, org_category FROM sys_depart（org_category: 1=公司, 2=部门, 3=岗位, 4=子公司）

Step 2: 展示流程摘要并确认

必须展示以下内容，等待用户确认后再执行：

## 流程摘要

- 流程名称：员工请假审批流程
- 流程类型：oa
- 目标环境：https://api3.boot.jeecg.com

### 流程节点

| 序号 | 节点名称 | 类型 | 审批人 |
|------|---------|------|--------|
| 1 | 开始 | startEvent | - |
| 2 | 员工提交申请 | userTask | ${applyUserId} |
| 3 | 部门经理审批 | userTask | manager (角色组) |
| 4 | 审批结果 | exclusiveGateway | 条件分支 |
| 5 | HR审批 | userTask | hr (角色组) |
| 6 | 结束 | endEvent | - |

### 连线与条件

开始 → 员工提交申请 → 部门经理审批 → 审批结果
  ├─ 通过 (result==1) → HR审批 → 结束
  └─ 拒绝 (result==0) → 结束

确认以上信息正确？(y/n)

Step 3: 生成 BPMN XML 并调用 API

用户确认后，执行以下步骤：

3.1 生成唯一标识

import time
ts = str(int(time.time() * 1000))
process_key = f"process_{ts}"

3.2 构造 BPMN XML

阅读以下参考文件（按需）：

• references/bpmn-xml-skeleton.md — XML 骨架 + 基本节点模板（必读）
• references/bpmn-assignee-types.md — 审批人配置 + 表达式审批人 + groupType速查（必读）
• references/bpmn-layout.md — 节点ID命名 + 布局计算（必读）
• references/bpmn-countersign.md — 会签配置（需要会签时读）
• references/bpmn-task-extend.md — taskExtendJson + 监听器完整清单（配置节点行为时读）
• references/bpmn-examples.md — 完整示例 + Python脚本 + 流程模式
• references/bpmn-advanced.md — 条件表达式 + 抄送 + 按钮 + 服务任务 + API
• references/bpmn-subprocess-gateway.md — 网关 + 子流程（子流程/网关时读）
• references/bpmn-db-config.md — 数据库配置表
• references/example/*.bpmn — 生产环境真实流程示例（生成前先阅读最相似的示例学习写法）

核心要点：

• 使用 bpmn2: 命名空间前缀（新版设计器规范）
• 必须包含流程结束监听器和任务创建监听器
• 必须包含 bpmndi:BPMNDiagram 图形布局信息
• 节点 ID 使用有意义的命名（如 task_apply、gateway_result）

3.3 构造 nodes 参数

从所有 userTask 节点中提取，格式：

id=<节点ID>###nodeName=<节点名称>@@@id=<节点ID>###nodeName=<节点名称>@@@

3.4 使用 Python 调用 API（必须用 Python，不要用 curl）

重要限制（实战踩坑）：

1. Windows 环境下 curl 发送中文会乱码，必须使用 Python 的 urllib 确保 UTF-8 编码
2. 禁止使用 python3 -c "..." 内联方式，因为 BPMN XML 中的 ${applyUserId} 等表达式会被 bash 当作 shell 变量展开，导致 unexpected EOF 错误
3. 必须先用 Write 工具写入 .py 临时文件，再用 Bash 执行，最后删除临时文件

执行步骤：

1. Write 工具 → 写入 create_process.py（项目根目录）
2. Bash 工具 → python create_process.py
3. Bash 工具 → rm create_process.py（清理）

Python f-string 中的转义要点：

• BPMN 表达式 ${applyUserId} → f-string 中写作 ${{applyUserId}}（双花括号转义）
• taskExtendJson 的 value 属性用单引号包裹 JSON → value='{{"sameMode":2,...}}'（避免与 XML 双引号冲突，同时 JSON 花括号也需双花括号转义）
• flowable:candidateUsers="${flowNodeExecution.getDepartLeaders(execution)}" → f-string 中写作 ${{flowNodeExecution.getDepartLeaders(execution)}}

Python 脚本模板：

import urllib.request
import urllib.parse
import json
import time

API_BASE = '{用户提供的后端地址}'
TOKEN = '{用户提供的 X-Access-Token}'

ts = str(int(time.time() * 1000))
process_key = f'process_{ts}'
process_name = '流程名称'

# 用 f-string 构造 XML，注意 ${{}} 双花括号转义
bpmn_xml = f'''<?xml version="1.0" encoding="UTF-8"?>
<bpmn2:definitions ...>
  <bpmn2:process id="{process_key}" name="{process_name}">
    ...
    <bpmn2:userTask id="task_apply" name="申请人填写" flowable:assignee="${{applyUserId}}">
      <bpmn2:extensionElements>
        <flowable:taskExtendJson value='{{"sameMode":2,...}}' />
        ...
      </bpmn2:extensionElements>
    </bpmn2:userTask>
    ...
  </bpmn2:process>
  <bpmndi:BPMNDiagram>...</bpmndi:BPMNDiagram>
</bpmn2:definitions>'''

nodes_str = 'id=task_apply###nodeName=申请人填写@@@...'

data = {
    'processDefinitionId': '0',
    'processName': process_name,
    'processkey': process_key,
    'typeid': 'oa',
    'lowAppId': '',
    'params': '',
    'nodes': nodes_str,
    'processDescriptor': bpmn_xml,
    'realProcDefId': '',
    'startType': 'manual'
}

encoded_data = urllib.parse.urlencode(data).encode('utf-8')

req = urllib.request.Request(
    f'{API_BASE}/act/designer/api/saveProcess',
    data=encoded_data,
    headers={
        'X-Access-Token': TOKEN,
        'X-Sign': '00000000000000000000000000000000',
        'X-Tenant-Id': '1',
        'X-Timestamp': str(int(time.time() * 1000)),
        'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8'
    },
    method='POST'
)

resp = urllib.request.urlopen(req)
result = json.loads(resp.read().decode('utf-8'))
print(json.dumps(result, ensure_ascii=False, indent=2))
print(f'\\nProcess Key: {process_key}')

3.5 检查结果

• success: true → 流程创建成功，记录返回的 obj（流程ID）
• success: false → 输出错误信息，检查 processkey 是否重复等

Step 4: 输出结果

## 流程创建成功

- 流程ID：{obj}
- 流程名称：{processName}
- 流程Key：{processkey}
- 目标环境：{API_BASE}

请在流程设计器中查看：打开 JeecgBoot 后台 → 流程管理 → 流程设计 → 找到该流程

编辑已有流程

如果用户要修改已有流程，需提供 processDefinitionId（流程数据表ID），调用同一接口，将 processDefinitionId 改为实际ID 即可。

错误处理

数据库配置表

流程创建后，可通过以下数据库表进一步配置节点行为、表单绑定和字段权限：

详细的字段说明和取值参见 references/bpmn-db-config.md。

参考文档

• 阅读 references/bpmn-templates.md 获取参考文件索引（已拆分为 8 个子文件）