Appearance
设计原理 06 · 契约约定——引擎与调用方的边界
系列：jeeflow 工作流引擎设计原理
1. 为什么需要"契约"
引擎核心是中立的：它不知道你的业务是请假还是报销，也不知道"驳回后发起人该收到什么"。但四版 demo 必须行为一致、且能与 mldong 框架生态对接——所以把"业务层怎么做"固化成契约，调用方遵守契约，引擎不内置。
引擎（中立） 契约（本文件） 调用方（业务层）
│ │ │
│ 创建任务 assignee="applicant" │ 启动后自动完成申请节点
│ 完成任务 → 解析为发起人 │
│ 跳转节点 submitType 枚举 │ REJECT → 跳结束（实例 45）
│ 变量注入 u_* 前缀 │ 决策表达式引用 u_*2. 契约一：发起申请节点
约定：每个流程 start 后的第一个任务节点是"发起申请"节点，assignee 使用特殊值 "applicant"。
json
{ "id":"apply", "type":"snaker:task",
"properties":{ "assignee":"applicant", "performType":0, "taskType":0 },
"text":{"value":"发起申请"} }引擎行为：解析参与者时 "applicant" 替换为 instance.operator（发起人）。
调用方行为（startAndExecute）：
1. startProcessInstanceById
2. 取所有进行中任务，逐个 executeProcessTask（submitType=0 APPLY）为什么这么设计：
- 流程定义里能看到完整的业务闭环（发起 → 审批 → 结束），而不是"审批流从中间开始"
- 审批记录里保留了发起人节点（
approvalRecord完整） - 退回发起人时（submitType=6），第一个任务节点重新执行并强制指派给发起人 = 给发起人建待办（§4 demo 约定）
3. 契约二：submitType 枚举
| code | 枚举 | 含义 | 引擎调用 |
|---|---|---|---|
| 0 | APPLY | 发起申请 | executeProcessTask |
| 1 | AGREE | 同意申请 | executeProcessTask |
| 2 | REJECT | 拒绝申请 | executeAndJumpToEnd（跳结束，实例→45） |
| 3 | ROLLBACK | 退回上一步 | 回溯上一任务节点 → executeAndJumpTask |
| 4 | JUMP | 跳转 | executeAndJumpTask(..., taskName) |
| 5 | RE_APPLY | 重新提交 | executeProcessTask |
| 6 | ROLLBACK_TO_OPERATOR | 退回发起人 | executeAndJumpToFirstTaskNode |
| 20 | COUNTERSIGN_DISAGREE | 拒绝申请（会签） | executeProcessTask + countersignDisagreeFlag=1 |
枚举取值与行为均与 mldong 框架的 ProcessSubmitTypeEnum 一致（这是 mldong 生态前端能直接对接的前提）。
4. Demo 层约定：submitType 行为（与 mldong 框架一致）
本节约定为 demo 参考实现的行为，不是引擎契约。引擎只提供跳转能力（
executeAndJumpToEnd/executeAndJumpTask/executeAndJumpToFirstTaskNode），具体"提交类型做什么"由调用方决定（demo 与 mldong 框架完全一致）。
约定：
| submitType | 调用方动作 | 效果 |
|---|---|---|
| 2 REJECT | executeAndJumpToEnd | 当前任务完成、其余进行中任务废弃，实例→45 已拒绝，无新待办 |
| 3 ROLLBACK | 沿边回溯上一个任务节点 → executeAndJumpTask | 退回上一步审批人，实例保持 10 |
| 4 JUMP | executeAndJumpTask(..., taskName) | 跳到指定已办节点（taskName 取自 jumpAbleTaskNameList） |
| 6 ROLLBACK_TO_OPERATOR | executeAndJumpToFirstTaskNode | 第一个任务节点重新执行、参与者强制为发起人 → 发起人收到新待办，实例保持 10 |
退回 vs 硬驳回：
| 退回（submitType=6） | 硬驳回（submitType=2） | |
|---|---|---|
| 实例状态 | 10 进行中 | 45 已拒绝 |
| 发起人 | 收到新待办，可重新提交 | 无待办 |
| 适用 | 审批不通过但可修改重提 | 流程彻底终止 |
5. 契约四：流程变量注入
引擎每次操作自动注入用户信息（key 与 mldong 框架一致）：
| 变量 | 来源 | 示例 |
|---|---|---|
u_userId | UserProvider | "user1" |
u_realName | UserProvider | "张三" |
u_deptId / u_deptName | UserProvider | "D01" / "技术部" |
u_postId / u_postName | UserProvider | "P01" / "工程师" |
BUSINESS_NO | 业务方传入 args | "BIZ-123" |
submitType | 操作时传入 | 0/1/2/3/4/5/6/20 |
为什么 key 必须和 mldong 框架一致：决策表达式（u_deptId == 'D01'）是流程定义的一部分，如果 jeeflow 用别的 key，同一份流程定义在 mldong 框架和 jeeflow 上行为不同——契约就是"同一份 JSON 双端可移植"。
6. Demo 接口层（参考实现，非引擎契约）
⚠️ 这不是"通用约定"。以下接口是四版 demo 为对齐 mldong 快速开发框架的接口规范而提供的参考实现，路径、响应结构、submitType 行为均与 mldong 框架完全一致（见 6.2 剩余差异）。业务方接入时以自家接口规范为准，引擎层契约只到 2~5 节为止。
6.1 端点清单（四版 demo 一致）
| 端点 | 方法 | 说明 |
|---|---|---|
/wf/processDefine/page | POST | 流程定义分页 |
/wf/processDefine/detail | POST | 流程定义详情（jsonObject 供前端设计器） |
/wf/processDefine/startAndExecute | POST | 启动流程实例（mldong 框架主入口） |
/wf/processInstance/startAndExecute | POST | 启动并自动完成申请节点（兼容路径） |
/wf/processInstance/page | POST | 我的流程实例 |
/wf/processInstance/detail | POST | 实例详情（Entity 字段 + jsonObject + activeTaskList） |
/wf/processInstance/highLight | POST | 高亮数据（独立端点） |
/wf/processInstance/approvalRecord | POST | 审批记录（独立端点） |
/wf/processTask/todoList | POST | 我的待办 |
/wf/processTask/doneList | POST | 我的已办 |
/wf/processTask/execute | POST | 执行任务（submitType 全枚举 0/1/2/3/4/5/6/20） |
/wf/processTask/jumpAbleTaskNameList | POST | 可跳转的任务节点列表 |
/api/stats | GET | 仪表盘统计（UI 用，非 mldong 端点） |
6.2 与 mldong 框架的差异（如实声明）
| 点 | mldong 框架 | jeeflow demo | 说明 |
|---|---|---|---|
| 当前用户 | LoginUserHolder（Sa-Token 登录态） | 请求 body 显式传 operator | demo 无登录体系，便于演示站切换人员 |
| 抄送 | execute 内处理 CC_ACTORS | 无（SPI 预留） | |
| 鉴权 | @SaCheckPermission | 无 |
提交类型（submitType 0/1/2/3/4/5/6/20）的行为、响应结构（
code=0/msg）均与 mldong 框架一致，见 §3、§4。
6.3 已对齐的部分
- 路径前缀（
/wf/*）与 mldong 框架一致，highLight / approvalRecord 为独立端点 submitType枚举取值与行为与 mldong 框架一致（0/1/2/3/4/5/6/20，含countersignDisagreeFlag）- 响应结构与 mldong 框架的
CommonResult一致（code=0成功 /99999999失败，字段code/msg/data）+CommonPage（{pageNum, pageSize, rows, recordCount, totalPage}） jsonObject/highLight/activeTaskList/taskActorIdList结构与 mldong 框架的 VO 一致，可直接喂 mldong 生态前端的设计器组件
6.4 服务地址
四版 demo（Python :8100 / Java :8080 / Go :8081 / Node :8082）均提供上述端点，jeeflow-ui 右上角可切换后端直连（CORS 已配置）。
7. 契约变更的影响
契约变更 = 流程定义变更 + 调用方变更 + 前端变更，三者必须同步。因此：
- 契约条文进 SPEC.md（唯一事实来源）
- 四版 demo 是契约的参考实现（也是合规测试的验证对象）
- 新增契约（如"会签完成条件"）需先在 SPEC 定稿，再实现
设计原理系列完。下一篇进入：用户指南