用户指南 03 · 后端接入（REST API）

四版 demo 提供完全一致的端点（路径、响应结构、submitType 行为与 mldong 生态一致，用于对接 mldong 生态前端）。本文以 Python demo（:8100）为例，其他后端接口相同。

⚠️ 注意：这是 demo 参考实现，不是通用契约。demo 无登录体系，operator 显式传参（便于演示站切换人员）；鉴权/抄送差异见 设计原理 06 §6.2。

0. 通用约定

• 所有 /wf/* 端点为 POST，Content-Type: application/json
• 响应统一（mldong 框架 CommonResult）：成功 { "code": 0, "msg": "成功", "data": ... }；失败 { "code": 99999999, "msg": "..." }（HTTP 仍为 200）
• 分页响应：data = { pageNum, pageSize, rows, recordCount, totalPage }

1. 流程定义

1.1 列表

POST /wf/processDefine/page
body: { "pageNum": 1, "pageSize": 50 }

{ "code": 0, "msg": "成功", "data": { "rows": [
  { "id": 1, "name": "simple", "displayName": "简单审批流程", "type": "approval", "state": 1, "version": 1 }
]}}

1.2 详情（含流程图）

POST /wf/processDefine/detail
body: { "id": "1" }

{ "code": 0, "msg": "成功", "data": {
  "id": 1, "name": "simple", "displayName": "简单审批流程",
  "type": "approval", "state": 1, "version": 1,
  "jsonObject": { "name": "simple", "nodes": [...], "edges": [...] }
}}

jsonObject 直接喂给前端设计器渲染（mldong 框架 ProcessDefineVO.jsonObject）。

2. 流程实例

2.1 启动（自动完成申请节点）

POST /wf/processDefine/startAndExecute     ← mldong 框架主入口
POST /wf/processInstance/startAndExecute   ← 兼容路径，行为相同
body: { "processDefineId": 1, "operator": "user1", "amount": 3000 }

{ "code": 0, "msg": "成功", "data": null }

operator 为发起人；其他字段（amount/reason 等）进入流程变量，供决策表达式使用。启动后调用方自动完成"发起申请"节点（submitType=0 APPLY），流程推进到第一个审批节点。

2.2 我的实例列表

POST /wf/processInstance/page
body: { "pageNum": 1, "pageSize": 50, "operator": "user1" }

{ "code": 0, "msg": "成功", "data": { "rows": [
  { "id": 1, "processDefineId": 1, "state": 10,
    "operator": "user1", "createTime": "2026-08-01 10:00:00",
    "displayName": "简单审批流程", "name": "simple", "version": 1,
    "jsonObject": { ... },
    "activeTaskList": [ { "id": 12, "taskName": "task1", "displayName": "上级审批",
                          "taskState": 10, "taskActorIdList": ["leader"] } ] }
]}}

2.3 实例详情

POST /wf/processInstance/detail
body: { "id": "1" }

{ "code": 0, "msg": "成功", "data": {
  "id": 1, "parentId": null, "processDefineId": 1, "state": 10,
  "parentNodeName": "", "businessNo": "BIZ-...", "operator": "user1",
  "variable": "{\"amount\": 3000}", "createTime": "...", "createUser": "user1",
  "displayName": "简单审批流程", "name": "simple", "version": 1,
  "jsonObject": { ... },
  "activeTaskList": [ ... ]
}}

审批记录与高亮为独立端点（mldong 框架 同构）：/wf/processInstance/approvalRecord、/wf/processInstance/highLight。

2.4 审批记录

POST /wf/processInstance/approvalRecord
body: { "id": "1" }

{ "code": 0, "msg": "成功", "data": [
  { "id": 11, "taskName": "apply", "displayName": "发起申请",
    "taskState": 20, "operator": "user1", "taskActorIdList": ["user1"],
    "createTime": "...", "finishTime": "...",
    "processDefineDisplayName": "简单审批流程" }
]}

2.5 高亮数据

POST /wf/processInstance/highLight
body: { "id": "1" }

{ "code": 0, "msg": "成功", "data": {
  "historyNodeNames": ["apply", "task1"],
  "historyEdgeNames": ["e1"],
  "activeNodeNames": ["task2"]
}}

供前端设计器高亮：历史节点/边 + 进行中节点（mldong 框架 HighLightVO）。

3. 任务

3.1 待办列表

POST /wf/processTask/todoList
body: { "pageNum": 1, "pageSize": 50, "userId": "leader" }

{ "code": 0, "msg": "成功", "data": { "rows": [
  { "id": 12, "processInstanceId": 1, "taskName": "task1",
    "displayName": "上级审批", "taskState": 10, "formKey": "leave-form",
    "createTime": "...", "processDefineDisplayName": "简单审批流程",
    "taskActorIdList": ["leader"] }
]}}

3.2 已办列表

POST /wf/processTask/doneList
body: { "pageNum": 1, "pageSize": 50, "userId": "leader" }

响应结构与 todoList 相同（taskState=20）。

3.3 执行任务

POST /wf/processTask/execute
body: { "processTaskId": "12", "operator": "leader", "submitType": 1, "comment": "同意" }

submitType 全枚举（取值与行为均对齐 mldong 框架 ProcessSubmitTypeEnum）：

submitType	含义	调用方行为
0 (APPLY)	发起申请 / 重新提交	executeProcessTask
1 (AGREE)	同意	executeProcessTask
2 (REJECT)	拒绝	executeAndJumpToEnd（实例 → 45 已拒绝）
3 (ROLLBACK)	退回上一步	沿边回溯上一任务节点 → executeAndJumpTask
4 (JUMP)	跳转	executeAndJumpTask(..., taskName)，taskName 取自 jumpAbleTaskNameList
5 (RE_APPLY)	重新提交	executeProcessTask
6 (ROLLBACK_TO_OPERATOR)	退回发起人	executeAndJumpToFirstTaskNode（发起人收到新待办，实例保持 10）
20 (COUNTERSIGN_DISAGREE)	会签不同意	executeProcessTask + countersignDisagreeFlag=1

{ "code": 0, "msg": "成功", "data": null }

3.4 可跳转节点列表

POST /wf/processTask/jumpAbleTaskNameList
body: { "processInstanceId": "1" }

{ "code": 0, "msg": "成功", "data": [
  { "label": "上级审批", "value": "task1" }
]}

错误场景：

{ "code": 99999999, "msg": "operator leader not allowed" }

错误消息	原因
task not found	任务不存在
task not doing	任务已处理
operator xxx not allowed	非参与者操作

4. 仪表盘统计（UI 用，非 mldong 框架 端点）

GET /api/stats?userId=user1

{ "code": 0, "msg": "成功", "data": { "todoCount": 2, "myInstanceCount": 5 } }

5. 接入自己的业务

引擎是库，接入方式（非 demo）：

你的 Controller/Service
    │ 调引擎方法（构造器注入 SPI）
    ▼
EngineImpl.startProcessInstanceById / executeProcessTask / executeAndJumpTask / executeAndJumpToEnd / executeAndJumpToFirstTaskNode
    │
    ▼
你的 Repository 实现（ProcessRepository SPI）
    │
    ▼
你的数据库（5 张表，见 SPEC §2）

关键点：

1. 实现 ProcessRepository（必须）——内存/MyBatis/JPA/SQLAlchemy 随意，接口见 SPEC §7
2. 按契约调用：启动后自动完成申请节点（submitType=0）；submitType 行为表见 设计原理 06 §3-4
3. 事务：引擎方法不带事务，业务层用 TransactionTemplate 包裹
4. 扩展：拦截器/事件/处理器注册见 04-扩展开发

6. 源码锚点（各语言 demo 的 API 实现）

端点	Java	Go	Node.js	Python
全部	jeeflow-demo-boot4/.../DemoController.java	demo/controller.go	demo/main.ts	demo/main.py