Appearance
规范 06 · 统一门面(JeeflowFacade)完整接口文档
面向"接口即 POST + JSON body"的框架风格:集成方只实现一个转发 controller, 把 body JSON 转成 Map 传入门面,所有流程能力通过
action路由。本文档是前端接入的唯一依据:不管后端是 mldong 系列(boot2/boot3/boot4)、 FastAPI、NestJS、GoFrame,还是任意其他框架(如若依),只要实现了统一门面转发层, 前端即可按本文档的
action+ 参数 + 返回结构直接对接。 设计动机(为什么需要门面、与 boot2/boot3 端点的关系)见 设计原理 07 · 管理扩展与门面。
1. 入口契约
text
Map<String,Object> flow(String action, Map<String,Object> args)action:boot2/boot3 端点路径的短名(见第 3 节 action 清单)args:业务参数 Map(含分页、过滤、表单数据、operator 等)- 返回统一结构(对齐 mldong
CommonResult):
json
{ "code": 0, "msg": "成功", "data": { ... } }code=0成功;code!=0失败,msg为失败原因(引擎内统一99999999)- 门面内部异常会被捕获、不会向上抛。但捕获到 ≠ 原文外透:引擎自己写的中文契约文案逐字透出, 运行时/驱动/JSON 解析器写的原文属内部实现细节 ⇒ 对外一律只给固定文案
流程处理失败, 原文只进日志与错误对象(判别式五条见下文 §2.12) - 未知 action 返回
{code: 99999999, msg: "未知 action: xxx"}
HTTP 约定
- 所有 action 均走 POST,路径形如
/wf/{action}(各集成框架示例见集成指南) - body 为 JSON 对象(
Content-Type: application/json) - 登录鉴权由集成方框架层完成(token/会话),门面本身不感知登录态
2. 全局约定
2.1 统一响应
| code | 含义 |
|---|---|
| 0 | 成功 |
| 99999999 | 业务失败(msg 为原因) |
| 其他 | 集成方框架层错误(未登录 401、无权限 403 等,由框架自身返回) |
- 出口键一律 camelCase(issues/204 · 2026-10-14 owner 拍):门面出口 JSON 的对象键一律 camelCase (
createTime/processDesignId…);仓储层列名是蛇形时由门面出口归一,不允许以蛇形同义键 (create_time)出现在出口(先例=PHPdesignRowToMap的双读+归一件,issues/98 同构)。 整键缺失仍按 §2.4 的 A3 裁定合法——本条禁的是"投了但拼成蛇形"。门禁 L2-25 的 SNAKE 档 (camel 键整列不投而蛇形同义键在场)按本条判红(R84 先修后红)。
2.2 分页结构(page 类 action 的 data)
json
{
"pageNum": 1,
"pageSize": 10,
"recordCount": 25,
"totalPage": 3,
"rows": [ ... ]
}pageNum从 1 起;pageSize默认 10- 查询参数:
pageNum/pageSize/orderBy(如"t.create_time desc") - 过滤参数:
m_前缀三段式m_{别名}_{操作符}_{列名},别名省略时默认主表t, 列名 camelCase 自动转 snake_case,操作符大写:
| 形式 | 示例 | 含义 |
|---|---|---|
m_{op}_{column} | m_EQ_taskName=leaveApply | 主表 t.task_name = 'leaveApply' |
m_{alias}_{op}_{column} | m_t_LIKE_displayName=请假 | t.display_name LIKE '%请假%' |
m_pd_{op}_{column} | m_pd_LIKE_name=simple | 实例列表按流程定义搜:pd.name LIKE '%simple%'(别名 pd → 关联的流程定义表,白名单列 pd.name / pd.display_name / pd.version) |
| 操作符 | EQ LIKE GT LT GE LE IN … | 标准 SQL 语义 |
实例列表(
processInstance/page)支持m_pd_*别名按流程定义维度过滤(前端"编码"搜索走m_pd_LIKE_name,"名称"搜索走m_pd_LIKE_displayName);任务列表走m_t_*(t= 任务表)。 六语言内存/持久仓储都须解析pd./t.别名到对应行键(PHP 内存仓储此前只剥别名按裸键取、 与 camelCase 行键失配,已补齐对齐 Java in-memory 的pd.*/t.*白名单映射;Rust 在 facadeparse_m_params解析m_{alias}_{op}_{col})。
2.3 id 字符串契约(重要)
- 引擎 id(流程定义/实例/任务/设计 id)为雪花算法 64 位整数,JS 中超过
2^53会丢精度 - 六语言出口一律保证 id 为字符串:Java 集成层
ToStringSerializer、Node 全链路 string、 Go/Python 出口stringifyIDs、PHP 出口字符串化 转换、Rust facade 出口stringify_ids(递归处理嵌套对象/数组) - 嵌套对象同样适用:列表/嵌套行(
processDesign/detail的his[]、processInstance/detail的tasks[]/activeTaskList[]等)的id/*Id键 与顶层同契约(教训:Python dataclass 列表曾绕过出口 hook 以 int 外泄) - 前端一律把 id 当字符串处理(不做数值运算、不 parseInt);提交时传字符串或数字均可 (引擎统一 toLong 容错)
- Java 宿主集成硬要求:jeeflow-java starter 只向引擎内部 JSON(bizData/ext 存储)注入
Long→ToStringSerializer,不向宿主 Web 层注入。宿主必须自行配置全局Long.class/long字符串序列化(mldong-boot2/3/4 的WebMvcConfig已配; 其他宿主如裸 Spring Boot 需自查,否则雪花 id 以 JSON number 下发丢精度)
2.4 时间格式
- 一律
yyyy-MM-dd HH:mm:ss(如2026-08-06 10:30:00) - 空值返回
null;但"整键缺失"同样是合法出口形状(issues/133 · 2026-09-29 owner 拍:不改实现)。 唯一违规形状是空串''——门禁格 L2-25 判红只看'',null与"键不存在"两档只进分布不进判据。 ⇒ 前端读可空时间列必须双判(键存在性 + 值非空),把"缺键"当"没有这一列"处理即可, 不要假设它一定以null出现(实测 java 三栈与 c# 在processInstance/detail.tasks上整列不投, laravel 少expireTime/finishTime、salvo 少expireTime,其余七栈出null——这不再算跨栈分叉)。 - 基准由宿主注入的时钟决定,引擎不自取(issues/120):集成方(框架壳)必须注入宿主本地时钟, 写库审计列、转办留痕、
NOW()占位符、委托生效窗判据共用同一出口;未注入时各栈默认基准 不作跨栈承诺(Rust / MoonBit 引擎默认 UTC,其余六栈取宿主系统时间)
2.5 operator 约定(操作人)
门面不感知登录态,
args.operator显式传入;空串与缺键同档——传""或全空白串视同未传, 一并回落到 demo 风格缺省user1(issues/129 · 2026-09-28 补:这一档以前没写,于是八栈对{"operator":""}给出三种答案——五栈丢掉条件读全库、php/moon 当真实值过滤出空页、rust 归缺省)归属过滤是双层的,两层都要有:门面做归一化(空串=缺键 → 缺省),仓储做兜底 (归属列
operator/actor_id拿到空值 ⇒ 返回空页,绝不允许"这条条件不加",issues/117 §3.2)。 只修门面那一层不算修完:仓储仍可被别的调用方(或下一版门面改动)绕过。 ⚠️ 收的是归属谓词,不是PageQuery对可选过滤空值的通用放行(m_LIKE_*传空串按"没填"处理是对的)。抄送分页同一条尺子(issues/141 G1 · 2026-09-29 owner 拍):
pageCcInstances这类"抄送我"取数入口, 归属条件(cc.actor_id)必填——条件缺失或为空值时返回空页,不得退化成"这条不加"而返回全部实例。 现读反面教材:php 的 PDO 仓FROM wf_process_instance t LEFT JOIN wf_process_cc_instance cc不带条件时返全部, 而 java 的内存仓只放"有 cc 行的实例"——同一栈两个仓储两个答案,与 issues/117 场景 27(双仓必须同答案)同类, 所以这条义务要同时钉在 SQL 仓与内存仓上,只修一边不算修完。集成方必须覆盖:从登录上下文注入当前用户 id(如
body["operator"] = current_user.id)涉及"我的"语义的 action(
processInstance/page、todoList、doneList、ccList) 依赖 operator 过滤,字段口径已写死(对齐 javaJeeflowFacade,各语言仓储按此实现,不许偏宽/偏窄):action 过滤列 语义 processInstance/paget.operator EQ operator我发起的实例(实例 operator 即发起人) processTask/todoListactor_ids contains operator 我参与(未办结) processTask/doneListt.operator EQ operatorANDt.task_state <> 10我办理的——不含发起人 create_user,"我发起但非我办理"不算我的已办。
状态集合口径(owner 2026-09-21 拍板,此前 Rust/MoonBit 用= 20与另六栈分叉):认"经手过且不再是我待办",故含撤回(30)/终止(40)/废弃(99),不是只认已完成(20)。选它的理由是撤回单不会两头消失(只认=20时,撤回单既不在待办也不在已办,用户查不到自己撤过的单)。
operator 为空 → 返回空页,不得返回全库(本行不做"硬必填"收紧,见 issues/117 §7)processInstance/ccListcc.actor_id EQ operator抄送给我的(抄送行接收人) processSurrogate/paget.operator EQ operator我授出的委托(授权人=操作人)。issues/152 ② 起列入本表——此前这里是契约空白,"只看自己授出的委托"全靠集成壳注入 operator,换宿主/直调 SPI 就退化成全库台账
2.6 鉴权与权限码
- 引擎不依赖任何鉴权框架,只通过
IActionPermissionProviderSPI 提供 「action → 权限码」映射元数据,校验由集成方框架层完成(如StpUtil.checkPermissionOr) - 默认映射规则:
wf:{action.replace('/', ':')},例如processDefine/page→wf:processDefine:page - 部分 action 为 OR 语义(任一持有即可):
processDefine/detail→wf:processDefine:detail或wf:processDesign:listByType;processTask/candidatePage→wf:processTask:execute或wf:processTask:candidatePage - 纯复用型 OR(只挂 execute,不另建权限码):
processTask/jumpAbleTaskNameList、processTask/recall、processTask/revokeDynamicCountersign→ 一律wf:processTask:execute。 后两枚是 owner 2026-11-04 拍的 B 案:判据上撤回/撤会签的主体本来就必然是该行参与者 (=有办理权的人),拆独立码给不出去;且本项目的sys_menu惯例不是"每个 action 一枚按钮行" (transfer/removeTaskActor/latest都没有种子行),走 A 案要额外背一次存量库补 INSERT 的迁移。 落点(甲案终局,2026-11 轮八栈统一):八栈一律在引擎内置默认件——java 自1.8.60起就在DefaultActionPermissionProvider.orRules,go/python/node/php/rust/moon/csharp 于本轮补齐 (rust 原本只有默认派生一条、csharp 缺这两枚,四栈原本连 SPI 形状都没有)。集成壳不再自备权限表, 一律消费引擎 SPI;曾存在于十壳的副本(goframe/gin/hertzwf_permission.go、fastapi/flask/djangowf_permission.py、laravelWfPermission.php、nestjswf-permission.ts、salvowf_permission.rs、 csharpWfEndpoints.cs)随本批去重。 - 两张表是跨栈契约,不是各家配置:条目数在八栈测试里各自钉死(OR 7 条/放行 11 条), 加一条规则或加一枚放行 action 必须八栈同批改、各自发下一版——只改一栈就是制造"同一份配置跨栈读出两套码"。
- 无注解的只读/轻量 action 登录即可访问(放行):
processInstance/detail、highLight、approvalRecord、bizData、processTask/detail、addCandidate、latest、getAssigneeTextData、processInstance/stats/overview、stats/trend、stats/group(统计只读,全部登录用户可访问)等 - 集成方惯例:超级管理员(如 mldong
superAdmin)放行一切权限 - 集成方校验示例:
java
private void checkPermission(String action) {
LoginUser loginUser = LoginUserHolder.me();
if (loginUser != null && loginUser.isSuperAdmin()) return; // 超管万能
IActionPermissionProvider provider = ServiceContext.find(IActionPermissionProvider.class);
String[] codes = provider == null ? null : provider.permissionCodes(action);
if (codes != null && codes.length > 0) {
StpUtil.checkPermissionOr(codes);
}
}2.7 表单数据约定
| 前缀 | 位置 | 含义 |
|---|---|---|
f_ | 发起参数 / 实例变量 | 发起表单字段(f_amount、f_reason…) |
tf_ | 任务执行参数 / 任务变量 | 任务表单字段(tf_approvalComment 审批意见、tf_approvalAttachment 审批附件、tf_nextNodeOperator 下一节点执行人、tf_ccActors 抄送人) |
- 实例/任务行中
ext字段 = 对应变量 JSON 对象;taskFormData= 带tf_前缀的字段 (同时输出带前缀 + 去前缀两个副本,前端可直接取值) - 发起时
f_nextNodeOperator:发起人预指派的下一节点执行人(执行时自动转tf_nextNodeOperator)
后加签(可重复)协议键(节点开关见 规范 02 §4.3;引擎裁决见 规范 04 · 后加签(可重复)):
tf_addSignOperators:办理(processTask/execute)时指定的本节点后继办理人,可多选。 逗号串与数组两形同判据,复用 §2.11 既有参与者归一单点——逐元素 trim、空串/纯空白/null丢弃、 丢完为空=没传、落库与比较取 trim 后的值。- 与
tf_nextNodeOperator互斥:同传 ⇒ 报错(可诊断报错,不得静默择一)。理由是参数生命周期而非语义矛盾 (一个管本节点再来一轮、一个管流出后下一节点交给谁,逻辑可共存):tf_*键只在当次请求的执行参数与 已完成任务行变量里可读;加签使 token 停留本节点,流出发生在后续请求,届时先传的tf_nextNodeOperator已不可读——同传时它是死参数,静默处理=用户选的"下一节点处理人"无声消失, 报错是把死参数变响话。前端可对两组控件做互斥包装,服务端报错仍是权威兜底(集成壳、App、直连接口都能绕过前端)。 - 节点未开启
allowAddSign却传tf_addSignOperators⇒ 报错,不静默忽略。 tf_addSignHistory:引擎维护的追加式账本,List<Map>,每圈加签 append 一条{round, fromActor, toActors, time, operator}(轮次号、办理人、该轮加签人集合、时间、提交操作人), 只追加不覆盖。形状照tf_transferHistory那族(见 §processTask/transfer 留痕条): 五键固定 camelCase,time一律"yyyy-MM-dd HH:mm:ss"字符串(§2.4 全生态时间格式,账本跨栈同形)。tf_前缀使「退回上一步」复活血缘腿天然剔掉它(见 规范 04 · 退回上一步), 账本只留在已完成的历史行上、不污染新待办。- 不新增 action、不新增 submitType 档:办理动作仍是同意(1)/不同意(2),加签是参数携带的附属效果; §2.6 权限映射与 §3 action 清单因此不变。
动态会签(征询模式)协议键(节点开关见 规范 02 §4.4;引擎裁决见 规范 04 · 动态会签;issues/247,2026-11-03 立法):
- 复用
tf_addSignOperators(两形归一与互斥判据同上)——行为由节点属性分流:allowAddSign节点=办结主办行+接力;dynamicCountersign节点=不办结主办行、按人建成员行收意见; tf_addSignReason(选填,字符串):发起该轮会签的原因说明,随账本条目落库并盖到每条成员行 (单行出证自足,不回查主办行);- 账本沿用
tf_addSignHistory(形状与追加纪律同上),征询模式每条含reason; - 投影
ext.dynamicCountersign:processTask/detail对主办行输出{active, round, total, submitted, actors:[{actor, taskId, state}]}——从task_parent_id现算,不落新存储; 前端据此置灰执行按钮(未收齐时全部 submitType 置灰,唯一出口=撤回接口); - 新增 action
processTask/revokeDynamicCountersign:撤回未答成员=置灰态唯一恢复出口 (详见 §processTask/revokeDynamicCountersign);权限码复用wf:processTask:execute(OR 规则,见 §2.6;owner 2026-11-04 拍 B); - 不新增 submitType 档:成员行提交仍是既有枚举(仅记录、无表决语义)。
动态协办协议键(无节点开关;引擎裁决见 规范 04 · 动态协办;issues/253,2026-11-13 立法):
- 新增 action
processTask/aidant:入参processTaskId/actorIds/reason(选填)/waitCompletion(选填 bool,缺省false=不等协办办结)/operator;权限码复用wf:processTask:execute(OR 规则,见 §2.6;照 246/247 B 案惯例,不建按钮种子行); tf_aidantHistory:引擎维护的追加式账本(落主办行变量),每次派生 append{round, fromActor, toActors, reason, time, operator}(time§2.4 字符串),只追加不覆盖; 离开节点清场未办结协办行时再 append 一条同六键+abandoned:true的清场账(toActors=被废弃的人、reason空串、清场不消耗轮次)⇒ 主办办结后条数=派生跳数+清场条数;实例撤回(withdraw)置 WITHDRAW(30)、 不追加清场账(无协办特例,见 §processInstance/withdraw 与规范 04 · 动态协办);tf_aidantReason(选填,字符串):派生原因,盖每条协办行(单行出证自足);不占tf_approvalComment;- 投影
ext.aidant:processTask/detail对主办行输出{active, round, total, submitted, actors, wait}——从task_parent_id+task_type=1现算,不落新存储; - 不新增 submitType 档、不新增事件码;节点级
taskType=1解析期禁配(issues/252,协办档只由运行期派生)。
已办撤回协议键(节点开关见 规范 02 §4.4;引擎裁决见 规范 04 · 已办撤回;issues/246,2026-11-03 立法):
tf_recallHistory:引擎维护的追加式账本,每条撤回 append{operator, time, recalledTaskId}(时间 §2.4 字符串),只追加不覆盖;原 FINISHED 行一律不改写(历史即任务行);- 新增 action
processTask/recall:详见 §processTask/recall;权限码复用wf:processTask:execute(OR 规则,见 §2.6;owner 2026-11-04 拍 B)。
2.8 submitType(执行类型,processTask/execute 用)
| code | 枚举 | 语义 | 引擎方法 |
|---|---|---|---|
| 0 | APPLY | 发起申请 | executeProcessTask |
| 1 | AGREE | 同意 | executeProcessTask |
| 2 | REJECT | 拒绝(流程直接结束) | executeAndJumpToEnd |
| 3 | ROLLBACK | 退回上一步(血缘版:回到本实例真实走过的上一步任务行并复活它) | executeAndJumpTask(target=null),解析规则见 引擎操作 04 · 退回上一步 |
| 4 | JUMP | 跳转到指定节点(需 taskName) | executeAndJumpTask(target=taskName) |
| 5 | RE_APPLY | 重新提交(业务方语义,透传) | executeProcessTask |
| 6 | ROLLBACK_TO_OPERATOR | 退回发起人 | executeAndJumpToFirstTaskNode(start 直接后继 + assignee 强制为实例发起人;实现不得复用 3 的解析) |
| 7 | TRANSFER | 转办(processTask/transfer 写留痕用,不走 execute) | removeTaskActor + addTaskActor |
| 20 | COUNTERSIGN_DISAGREE | 会签拒绝:门面自动置 countersignDisagreeFlag=1。默认软拒绝(该成员任务正常完成、flag 记录为流程变量供下游参考、流程不阻断);仅当节点 countersignCompletionCondition=ONE_VOTE_VETO 时才一票否决直接推进整单 | executeProcessTask |
后加签(可重复)不加档:办理时在同意的同时指定本节点后继办理人,是
execute参数tf_addSignOperators的附属效果(键契约见 §2.7,引擎裁决见 规范 04 · 后加签(可重复)), 不新增 submitType 档,本表枚举不变。
2.9 状态枚举
任务状态 taskState
| code | 含义 |
|---|---|
| 10 | DOING 进行中 |
| 20 | FINISHED 已完成 |
| 30 | WITHDRAW 已撤回 |
| 40 | INTERRUPT 强行终止 |
| 50 | PENDING 挂起 |
| 99 | ABANDON 已废弃 |
实例状态 state(同上枚举,30 撤回 / 40 终止)
参与方式 performType
| code | 含义 |
|---|---|
| 0 | NORMAL 普通参与(多人任一完成即可) |
| 1 | COUNTERSIGN 会签(每人独立任务,全部完成才驱动下一步) |
兼容性:Java
codeOf语义接受字符串'1'/'ALL'/'COUNTERSIGN'表示会签, 前端提交字符串或数字均可。
定义状态 state(processDefine):1 启用 / 0 停用(upAndDown 切换)
设计部署状态 isDeployed(processDesign):1 已部署 / 0 未部署
2.10 抄送(CC)
- 发起抄送:
startAndExecute参数带f_ccActors(用户 id 数组)→ 自动创建抄送实例 - 任务中抄送:
execute参数带tf_ccActors(用户 id 数组) - 手动抄送:
processInstance/createCCInstance(抄送人可在ccList查看) - 空抄送人不建 cc 行(issues/141 G10 · 2026-09-29 owner 拍:「空不创建行」): 三条入口(
f_ccActors/tf_ccActors/手动createCCInstance)解析抄送人集合时, 空串、纯空白、数组里的空元素一律丢弃;丢完为空 ⇒ 不建任何 cc 行、也不 fire 码 4。 ⚠️ java 旧形状("".split(",")得到一个空元素 ⇒ 建一条actor_id=""的 cc 行)按本条更正—— 空归属值正是 issues/129 那族"空 operator 读全库"的病根,不能从抄送侧继续往里灌。 逗号串与数组两种形态在这条上必须同判据,别只修一条腿。 - 本条的四点实现要求(基准=java
5fbd5ac,其余七栈照此对齐,别只做其中一层): ① 两层都挡——漏斗层(解析集合时归一)+ 写侧层(createCcInstance自己也丢), 只修漏斗则绕过门面/引擎直连仓储的调用方照样能灌空值; ② 落库与比较一律取 trim 后的值," 123 "与123是同一个人(不 trim 就会与 §4 的 写侧判重错开,同一人落两行); ③ 手动腿createCCInstance丢完为空时与该仓既有的"空集合"档同判(java=actorIds 缺失错误信封),不新造错误码或文案; ④ 反向哨兵必须写进测试:"0"这类"看起来像空"的正常 id 不得被判成空值丢掉。
2.11 归属值写侧归一(actor_id 与 task id)——§2.10 的同一条尺子换到任务侧
(issues/142 B 批 · 2026-09-30 owner 拍「八栈一起收:两形同判据+写侧兜底+trim+哨兵」)
wf_process_task_actor.actor_id 是归属列(§2.5 口径表里那一族),空串/纯空白/null 元素 一旦落进去,就是 §2.5 与 issues/129 那族"空归属值读全库"的进水口。普查实读:八栈的 addCandidate/surrogate/transfer/nextNodeOperator 四条腿逗号串与数组两形没有一栈同判, null 在五栈分别被串化成 "null"/"None"/"<nil>"/.NET 类型名;两仓 addTaskActor 普遍判重不判空(rust 的 sqlx 仓连判重都没有,而同栈内存仓判重=两仓两个答案)。
⇒ 本条把 §2.10 的四点实现要求逐字搬到任务侧,覆盖这些写点:
| 写点 | 归一义务 |
|---|---|
processTask/addCandidate、processTask/surrogate(多数栈同体) | 集合解析:逐元素 trim、空串/纯空白/null/undefined 丢弃、同次调用折叠、落库与比较取 trim 后的值 |
processTask/transfer 的 fromActor/toActor | 同上(现在各栈只 isBlank 判必填、存的是未 trim 的原值) |
f_nextNodeOperator/tf_nextNodeOperator(发起人指定的下一节点参与者) | 逗号串与数组两形同判据(java 现状:串腿 trim+丢空、数组腿 String.valueOf(null)→"null" 照落,就是反面);数组元素不得被静默丢弃或串化成类型名 |
processInstance/updateCCStatus 的 operator | 入参归一后再比(否则空 operator 会把 state=1 打到历史 actor_id='' 的脏行上) |
两仓 addTaskActor(含 createCcInstance 同款写侧兜底) | 仓储写侧自己再挡一次——只修门面腿则绕过门面直连仓储的调用方照样灌空值 |
两仓 removeTaskActor(删除腿) | 只丢空值 + 非空值取「原值 ∪ trim 值」两形并集——与上面五条写点的"取 trim 后的值"不同:删除腿多带一份原值,才删得掉修复前落下的未 trim 历史脏行;trim 形仍要在并集里,才删得掉规范行。判据本体见 §processTask/removeTaskActor 语义 6 |
四条硬要求(与 §2.10 同构,不重复解释):① 两层都挡;② 落库与比较取 trim 后的值 (删除腿例外:removeTaskActor 取「原值 ∪ trim 值」两形并集,见上表末行); ③ 空入参档沿用各栈既有的"缺参数"错误信封,不新造错误码/文案—— ⚠️ 现读 php 在 actorIds 为空时返回 code=0 成功(八栈里独一份)属违反本条,要跟改成与 其余七栈同档的报错;④ 反向哨兵进测试:"0" 这类"看起来像空"的正常 id 不得被丢掉, 且严禁用语言自带的假值判据做判空(php 无回调 array_filter、python if not x、 js filter(Boolean) 都会吃掉 '0')——判空一律 trim(...) == ''。
主键类参数另判一档:processTaskId 缺失或空串必须响亮报错, 不得拿 ''/0 当 id 往下落库(现读 php JeeflowFacade.php:546 不校验 taskId, addTaskActor('' , …) 照跑)。这条与"归属值为空 ⇒ 丢弃"是两件事:归属值可有可无, 主键没有就是调用方写错了,静默接受会把脏数据钉进表里。
SPI 注释义务:各栈现在把空值义务只写在 create_cc_instance 的接口注释上, add_task_actor 的声明是裸的 ⇒ 第三方照注释实现必然漏任务侧。本条要求把同样的义务 补到 addTaskActor(以及 updateCcStatus)的接口注释上。
各栈的归一判据请复用 §2.10 已落地的那一枚单点(java
StringUtils.normalizeCcActors/ gospi.NormalizeCcActors/nodespi.normalizeCcActors/pyspi.normalize_cc_actors/ phpCcActorUtil::normalize/rsmodel::normalize_cc_actors/moon@model.normalize_cc_actors/ c#PageQuery.NormalizeCcActors),必要时改名成通用的normalizeActors—— 不要再抄第二份,两份判据迟早分叉(php 本轮就实测到"归一函数内部严格比较、 仓储写侧却用松散in_array⇒'0' == '00'把第二个人静默丢掉"这种两把尺子)。
2.12 门面内部异常出口 —— 固定文案 流程处理失败 +「谁写的这段文案」判别式
(issues/137 §3-1 · owner 2026-10-02 第 3 问拍 A:措辞就用 流程处理失败,进第八条逐字契约文本; 第 4 问拍 A:判别式推其余七栈,含 moon 那 5 条 Internal("mysql query: " ++ 驱动原文))
门面顶层 catch 捕获到的异常,不是都能把 message 原样放进 msg。判据是「这段文案是谁写的」: 引擎自己写的中文契约文案(八栈、十三个集成壳与前端 toast 都按原文逐字对齐)必须照旧透出; JVM/运行时/驱动/JSON 解析器/集成方 provider 写的原文属内部实现细节,透出去就是泄漏 (NullPointerException、For input string: "x"、'0xE8' is an invalid start of a property …、 java.lang.IllegalStateException: 内部驱动细节 12345、mysql query: … 一类), 对外一律只给固定文案 流程处理失败;原文只进日志与错误对象 (java log.log(Level.SEVERE, …, e) 带 cause/.NET InnerException/rust 的 cause/ moon ParseErrorWithCause + detail()/stderr 一类),不得拼进 msg, 也不得拼进任何其它对外字段(data、警告文本、unknown_node_warning 那族同理)。
判别式五条(逐条同实现,顺序即优先级;返回 true ⇒ 属内部信息 ⇒ 出口只给固定文案):
| # | 判据 | 理由 |
|---|---|---|
| 1 | message 为 null/缺失 | 兜底会吐类名(java.lang.NullPointerException 一类),必是内部 |
| 2 | 属契约异常族(java JeeflowException 及其子类;各栈对应件) | 引擎自己写的契约文案 ⇒ 逐字透出(本条返回 false) |
| 3 | message 恰等于 String.valueOf(cause)(即"裸包装") | new RuntimeException(e) 这类只是搬运下层原文,引擎没写过它(典型是 JeeflowEngineImpl.runInTx 那两处) |
| 4 | 异常类型属运行时/反射/IO/驱动自己抛的族 | 见下方族清单 |
| 5 | 抛出点不在引擎主包(JDK、集成方 provider、测试桩) | 引擎没写过的文案一律不外透 |
第 4 条的族清单(java 逐字,其余栈按本栈等价类型对齐):NullPointerException、 NumberFormatException、ClassCastException、IndexOutOfBoundsException、ArithmeticException、 StackOverflowError、VirtualMachineError、LinkageError、ReflectiveOperationException、 UndeclaredThrowableException、IOException、SQLException。 ⚠️ 引擎拿来当契约文案载体的 RuntimeException/IllegalArgumentException/IllegalStateException不在这一族里(ModelParser 的「未注册 IJsonProvider…」/「读取流程定义 JSON 失败」、 ProcessTask/ProcessInstance/CustomModel 的若干处、门面自己的扩展仓/精度档都是这个形状)。
⚠️ 因此不能简单收窄成「只透契约异常族」:引擎另有约十处直接用 RuntimeException/ISE/IAE 携带中文契约文案,其余七栈、十三个集成壳与前端 toast 都按这些原文逐字对齐,而 java 测试一处都没钉 ⇒ 收窄会静默改写契约面且没人报警。所以判据必须按「谁写的这段文案」判,不是按「什么异常类型」判。
覆盖面(每栈至少两处):① 门面顶层 catch;② bizData/JSON 解析那一族 (processInstance/bizData、流程定义 JSON 解析、任何把解析器原文拼进对外字段的地方)。 各栈还要 grep 一遍把原文拼进对外出口的写法再逐栈列清单:getMessage()/e.message/ format!("{:?}", e)/e.Message ?? e.ToString()/Internal("… " ++ 驱动原文) 一类。
判据形状(八栈同):文案判据与副作用(日志)各自可测——抽成纯函数, java 参考实现=JeeflowFacade.isForeignDetail(type, message, cause, trace)(rust parse_error_message/ moon ParseErrorWithCause + detail() 同姿势),测试 FacadeInternalErrorNoLeakTest。 每栈必须有改前红样:还原成旧拼接 ⇒ 断言当场红,不许只做"看起来对齐"。
⚠️ 集成方自己写的 handler/provider 抛的原文,同样属内部信息(owner 2026-10-02 就 python test_i142_62_custom_handler_own_exception_still_propagates 那一格裁定):判据是「谁写的这段文案」, ICustomHandler/IUserProvider/DB 驱动都是集成方或第三方写的,不是引擎写的 ⇒ 出口只给 流程处理失败,原文进日志与错误对象。不给豁免的理由是边界划不出来:同一个 handler 抛的 RuntimeError("handler-boom") 与 RuntimeError("mysql 连不上 password=xxx") 在类型上无法区分, 开豁免就等于给第三方原文开一条常通道。 ⇒ 既有测试若把"原文外透"钉成了期望值,改的是读法不是判据:保留 code != 0 ("处理器自身炸不得被吞成成功"才是那类格的真实意图)与引擎直用腿的原文断言 (引擎 API 不是门面出口,不受本条约束),只把门面出口那半的 msg 断言换成逐字 流程处理失败。
3. action 清单(40+ 个)
| 分组 | action | 需要扩展仓储 |
|---|---|---|
| 流程定义 | processDefine/page detail startAndExecute deploy redeploy remove upAndDown | 否 |
| 流程实例 | processInstance/page detail startAndExecute withdraw bizData | bizData 需 persist |
| 流程任务 | processTask/todoList doneList execute detail jumpAbleTaskNameList candidatePage surrogate addCandidate transfer aidant latest recall revokeDynamicCountersign | 否 |
| 流程设计 | processDesign/page detail save update updateDefine remove deploy redeploy listByType | 是(IProcessExtRepository) |
| 委托代理 | processSurrogate/page save update detail remove | 是 |
| 视图端点 | processDefine/getLastByName processInstance/highLight approvalRecord getAssigneeTextData createCCInstance updateCCStatus ccList | createCCInstance/updateCCStatus/ccList 需抄送表 |
| 统计 | processInstance/stats/overview stats/trend stats/group | 否(纯查询,全语言同批) |
未配置
IProcessExtRepository时,processDesign/*、processSurrogate/*报错; 未注册metaTableReader(jeeflow-persist)时bizData明确报错。
4. action 详解
通用:每个 action 的 body 均可带
operator(见 2.5);所有返回包在{code, msg, data}内。左侧菜单已按接口名列出全部 action(4.1~4.6 分组),点击直达。
4.1 流程定义 processDefine/*
processDefine/page — 流程定义分页
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| pageNum/pageSize/orderBy/m_* | 否 | - | 分页与过滤(2.2) |
data → 分页结构,rows 行字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 定义 id |
| name | string | 流程标识名(唯一,deploy 版本管理键) |
| displayName | string | 显示名 |
| type | string | 流程类型(如 approval/leave) |
| state | int | 1 启用 / 0 停用 |
| version | int | 版本号(同 name 从 0 递增) |
| createTime/createUser/updateTime/updateUser | - | 审计字段 |
processDefine/detail — 定义详情
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 定义 id |
data:
| 字段 | 类型 | 说明 |
|---|---|---|
| id/name/displayName/type/state/version | - | 同 page 行 |
| jsonObject | object | 流程 JSON 图(LogicFlow 模型,前端渲染流程图/表单依赖) |
processDefine/startAndExecute — 发起并执行(自动完成申请节点)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processDefineId | 是 | string | 定义 id |
| operator | 是 | string | 发起人 |
| f_* | 否 | any | 发起表单数据(业务字段) |
| f_nextNodeOperator | 否 | string | 预指派的下一步执行人 |
| f_ccActors | 否 | string[] | 发起抄送人 |
语义:启动实例 → 自动完成申请节点(assignee=applicant 映射为发起人)→ 流转到第一个审批节点。 data → { "processInstanceId": "..." }
无 apply 节点流程的自办腿(issues/167 · 2026-10-11 owner 拍 A 定案):流程没有申请节点时, 自动完成的对象退为首个任务节点——参与者由节点自身机制(assignee 字面量 / assignmentHandler / 候选集)解析,解析出零参与者时即建零参与者 DOING 行(spec/02 §6.1 表第一行)。此档的自办腿义务: 先把发起人写进该任务的参与者(addTaskActor)→ 再按发起人办理,即首任务自办对 「参与者不含发起人」放行——放行的依据是参与者表真实含发起人,不是权限豁免:引擎
isAllowed的判定形状(参与者表/水合后的 actorIds 含 operator ⇒ 可办)不变, 零参与者 DOING 行照旧谁也办不动。java 基准即此形状(门面 addTaskActor 后 execute,findTaskById从参与者表水合 actorIds);go 引擎在 isAllowed 里带仓储兜底同判; rust 1.0.29 起内存仓读路径水合task_actors对齐(sqlx 仓此前已水合)。 判据测试:rusttest_start_and_execute_no_apply_handler_first_task_self_handle(修前红:PermissionDenied: Operator leader not allowed on task N);活栈对照=共享种子 I13(define=14 assignment-handler),八栈读数见base-verify/reports/2026-10-11-i167-rust-i13-noapply.md。f_nextNodeOperator透传等其余义务不变。
processDefine/deploy — 发布流程定义
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| (流程 JSON 顶层展开) | 是 | object | 流程 JSON 字段直接平铺请求体(name/displayName/type/nodes/edges…)——vben5 前端约定 |
| content | 兼容 | string|object | 引擎兼容写法:整体塞进 content 字段(字符串或对象均可) |
语义:入参 JSON → ModelParser 解析出 name/displayName/type → 按 name 查最新 define: 存在则 version+1 插新记录,不存在则新记录(version 从 0 起)。 data → { "processDefineId": "..." }
processDefine/redeploy — 重新发布(原地替换内容)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processDefineId | 是 | string | 定义 id |
| (流程 JSON 顶层展开) | 是 | object | 同 deploy:流程 JSON 平铺请求体 |
| content | 兼容 | string|object | 引擎兼容写法 |
语义:按 processDefineId 原地替换该条定义(name/displayName/type/content 取自流程 JSON): version 不变、state 不变(不递增、不回落;停用中的定义 redeploy 后仍停用),create 时间/创建人保留。 data → null(成功空)
processDefine/remove — 删除定义
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 二选一 | string | 单删 |
| ids | 二选一 | string[] | 批量删 |
data → null
实例存在守卫(audit8 R110 立法,2026-10-17 owner 拍):删除前必须校验该 defineId 下是否存在实例(任何状态,含已办结/已撤回);存在任一即拒——对外 code=99999999,msg 逐字 存在正在未完成的流程实例,不允许删除!,内部码 20010005(不进 msg)。批量 {ids} 必须先对整批校验再删:任一 id 有实例即整批拒绝、不得部分删除;全部无实例才执行删除。仓储侧查询能力由各栈 hasInstancesByDefineId/has_instances_by_define_id 提供(JDBC/内存双实现);第三方仓储须实现同等能力,不能绕过守卫。八引擎落地见 audit8 R110(各引擎 commit 与测试读数在 jeeflow-hub/docs/audit8-2026-10/notes/R110.md)。
processDefine/upAndDown — 启停定义
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 二选一 | string | 单个启停 |
| ids | 二选一 | string[] | 批量启停 |
| state | 是 | int | 1 启用 / 0 停用 |
| opType | 是 | int | 与 state 同义(boot3 前端惯例,二者取一) |
data → null
4.2 流程实例 processInstance/*
processInstance/page — 我发起的实例分页
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| operator | 是 | string | 过滤"我发起"(t.operator = operator,实例发起人;见 §2.5 口径表) |
| pageNum/pageSize/orderBy/m_* | 否 | - | 分页与过滤 |
data → 分页结构,rows 行字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 实例 id |
| parentId | string|null | 子流程的父实例 id |
| processDefineId | string | 定义 id |
| state | int | 实例状态(2.9) |
| businessNo | string | 业务编号 |
| operator | string | 发起人 id |
| processDefineName/processDefineDisplayName/processDefineVersion | - | 定义冗余 |
| displayName/version | - | 定义显示名/版本(简写冗余) |
| ext | object | 实例变量(含 f_* 表单数据)。issues/124:变量唯一对外出口,variable 原串已从出口下线 |
| createTime/createUser/updateTime/updateUser/expireTime | - | 审计/到期 |
processInstance/detail — 实例详情
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 实例 id |
data:
| 字段 | 类型 | 说明 |
|---|---|---|
| id/parentId/processDefineId/state/parentNodeName/businessNo/operator | - | 同 page 行 |
| ext | object | 实例变量全量(键形态与 page 行 ext 逐字一致) |
| formData | object | f_* 表单字段(带前缀+去前缀副本) |
| displayName/name/version | - | 定义信息 |
| jsonObject | object | 流程 JSON 图 |
| tasks | task[] | 全量任务列表,每行含 ext(含 isFirstTaskNode:进行中且为申请节点 → 前端可"重新提交") |
| activeTaskList | task[] | 仅 DOING 的任务(tasks 的子集) |
变量出口立法(issues/124,终态一次写定):变量唯一对外出口是
ext(实例侧)与instanceExt(任务行侧);variable原串与variables全集不是契约字段,任何门面出口不得出现(持久层variable列不受此限——那是存储,不是出口)。 变量为空时ext出空对象{},不出缺键/null。
task 行结构(详情/列表通用,见 4.3 taskVo)。
processInstance/startAndExecute — 同 processDefine/startAndExecute
processInstance/withdraw — 撤回
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 实例 id |
| operator | 是 | string | 撤回人(不接受缺省,见下) |
operator 硬必填:缺失或空串 → code=99999999(msg 含 operator 必填)。 严禁缺省回落为 user1 等固定账号——那会把撤回人静默记成别人,审计链失真且不报错。
归属判据(命中任一即放行,全不命中则拒绝):
operator= 实例发起人(wf_process_instance.operator);operator是该实例任一进行中任务的参与者(wf_process_task_actor.actor_id);operator∈ {flow.auto,flow.admin}(沿用isAllowed的既有放行约定)。
⚠️ 判据 3 的边界(owner 2026-09-21 定):
flow.auto/flow.admin是字面量哨兵 (JavaFlowConst.AUTO_ID/ADMIN_ID),只有调用方真的把operator传成这两个字符串才命中。 生效场景因此只有两类:系统代执行(引擎/监听器以flow.auto身份推进)与裸引擎演示。 集成壳统一用登录人 id 覆写operator(雪花 id),所以经壳登录的真实超级管理员不命中判据 3—— 这是设计不是缺陷:超管能做什么由集成层的权限码(wf:processInstance:withdraw)决定, 引擎只判归属。当前 wf 前端没有超管代撤的场景,列表按人过滤后人人只见自己的单。 将来要加,引擎不新增能力:集成层在注入时把operator换成flow.admin(或等价地以系统身份调用)即可,八栈零改动。
拒绝 → code=99999999 + msg(如 无权限撤回该流程实例)。引擎侧只发明 99999999 一个失败码 (见 2.2),细粒度原因由 msg 承载;框架层的 401/403 不在此列。
⚠️ 判据 1 不可复用
isAllowed实现:各语言引擎的isAllowed只判"operator 在不在该任务 actorIds"+ auto/admin 放行,不判发起人,撤回路径需显式补这一支。
实例状态守卫(issues/134,v1.8.34 起八栈同构):归属判据通过之后、任何改写之前,实例 state != 10(进行中) ⇒ 拒:code=99999999,msg 逐字 流程实例非进行中,无法撤回 (内部码 20010009 只存在于引擎错误枚举,不进 msg——issues/121 口径);被拒时实例与任务行 零改写、不落库。本案病灶即此前对已办结(20)实例撤回会被静默改写 state=30 且返回 code=0。 该守卫排在下面"已完成(20)/已终止(40) 任务行不得被改写"那条任务行粒度保护之前,两条并存。
语义:判据通过后,实例与全部进行中任务置为 WITHDRAW(30)(级联持久化;任务态是 30 不是 99, 99 保留给"废弃"语义,两码不得混用,见 03-state-machine);实例 update_user 回写为撤回人, 进行中任务的 update_user 同样回写。已完成(20)/已终止(40) 的任务行不得被撤回改写。 撤回作用于整单(同实例全部进行中任务),不是只撤操作人自己那一条。 data → null
processInstance/bizData — 业务数据回显(需 jeeflow-persist)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processInstanceId | 是 | string | 实例 id(id 亦可) |
语义:按流程定义顶层 relTableName(缺省回落 name)定位业务表, MetaTableReader.readByProcessInstance 读取该实例的业务数据。 data → 业务行对象(结构由业务表决定)。
processInstance/stats/overview — 指标卡统计
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| start / end | 否 | string | yyyy-MM-dd HH:mm:ss,按实例 create_time 限定;空 = 不限该边界 |
| stateIn | 否 | int[] | 限定统计的实例状态;缺省 [10,20,30,40,45,50](剔除 99 废弃) |
权限:登录即可(2.6 放行清单),不配权限码。
data(全局口径,不带 operator 过滤;个人视角数字仍走 todoList/doneList 等分页接口的 recordCount):
| 字段 | 类型 | 口径 |
|---|---|---|
| total / inProgress / completed / rejected / withdrawn / suspended | int | 实例按 state 计数(10/20/45/30/50) |
| todayNew | int | create_time 在服务器当日的实例数(恒按当天,不受 start/end 影响) |
| avgDurationSeconds | int | 已完成(state=20)实例平均时长(秒):MAX(task.finish_time) - instance.create_time |
| rejectRate | float | rejected / max(1, completed + rejected) |
| pendingTaskCount | int | 全系统进行中任务数(task_state=10,不受 stateIn 影响) |
| overdueTaskCount | int | 逾期未办任务数(task_state=10 AND expire_time IS NOT NULL AND expire_time < now) |
| countersignRate | float | 会签占比:perform_type=1 的已完成任务 / 全部已完成任务 |
| onTimeRate | float | 及时办结率:finish_time <= expire_time 的已完成任务 / expire_time 非空的已完成任务 |
expire_time未填充的数据源:overdueTaskCount=0、onTimeRate=0(非错误,前端隐藏对应卡)。 全部指标只用纯列,不读variableJSON(v1.1 决策:不做 JSON 提取,六语言零方言分叉)。
processInstance/stats/trend — 时间趋势
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| start / end | 是 | string | yyyy-MM-dd HH:mm:ss |
| granularity | 是 | string | hour / day / week / month |
data → 数组(连续桶,无数据桶补 0,按 start→end 枚举;hour 建议跨度 ≤31 天,超限不报错):
jsonc
[{ "bucket": "2026-08-01", "started": 12, "finished": 8 }]started:实例create_time落在该桶(发起量);finished:任务finish_time落在该桶且task_state=20(办结量)bucket格式:hour=yyyy-MM-dd HH:00、day=yyyy-MM-dd、week=yyyy-'W'ww(ISO 周)、month=yyyy-MM- 两序列来源不同表,各自分桶后按 bucket 对齐合并(非 join)
processInstance/stats/group — 维度分组
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| dimension | 是 | string | 枚举见下表(9 个,全纯列) |
| start / end | 否 | string | 按创建/完成时间限定;stuckNode/stuckApprover 为实时快照,忽略 start/end |
| limit | 否 | int | 默认 10,按 count 降序取 Top N |
data → 数组(按 count 降序):
jsonc
[{ "key": "leaveApply", "label": "请假流程", "count": 42, "avgDurationSeconds": 57600 }]| dimension | 分组键 | 说明 |
|---|---|---|
state | instance.state | 状态分布;label 可空,前端走字典 wf_process_instance_state |
define | join define(key=编码 name,label=display_name) | 流程 Top N;含 avgDurationSeconds |
category | define.type | 流程分类分布 |
approver | task.operator(task_state=20) | 审批人历史办结量;key=用户 id,label 可空(前端查用户表) |
applicant | instance.operator | 发起人分布 |
node | task.display_name(task_state=20) | 节点平均耗时(avg=finish_time - create_time 均值) |
stuckNode | task.display_name(task_state=10) | 当前积压节点(实时快照,count=在办任务数) |
stuckApprover | task_actor.actor_id(join task_state=10 任务) | 当前积压人(实时快照;进行中任务 operator 无值,必须走 actor 表;会签每 actor 一行,count=该人在办任务数) |
durationBucket | 完成实例时长分桶 | key 固定 sameDay / 1to3d / 3to7d / over7d 四桶(无数据补 0) |
- 不支持的
dimension值返回code!=0明确错误(不静默空数组) - 语义区分:
approver(历史办结)vsstuckApprover(当前在办);node(历史耗时)vsstuckNode(当前在办) - 出参中一切 id 为字符串(2.3)
4.3 流程任务 processTask/*
taskVo(任务详情/列表通用行)字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 任务 id |
| processInstanceId | string | 实例 id |
| taskName | string | 节点名(模型节点 id) |
| displayName | string | 节点显示名 |
| taskType | string | 任务类型(task/start 等) |
| performType | int | 0 普通 / 1 会签 |
| taskState | int | 状态(2.9) |
| operator | string | 当前操作人 id |
| formKey | string | 表单 key |
| taskParentId | string | 上一步任务 id——血缘版「退回上一步」的前驱指针,引擎建单时必写,发起 execution 无当前任务时写 0(口径同 01 · 数据模型 的 task_parent_id 列注释)。⚠️ 出口的类型与"无上游"的表意各栈现况不一(0 / '0' / null 都有),尚待统一,见 issues/121 |
| taskActorIdList | string[] | 参与人列表 |
| taskFormData | object | tf_* 任务表单数据(带前缀+去前缀副本) |
processTask/todoList — 我的待办
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| operator | 是 | string | 过滤"我的待办" |
| pageNum/pageSize/m_* | 否 | - | 分页过滤 |
data → 分页结构,rows = taskRow(在 taskVo 基础上增加): finishTime/expireTime/createTime/createUser/updateTime/updateUser、 processDefineName/processDefineDisplayName/version、 instanceCreateTime、instanceState、instanceExt(实例变量)、 ext(任务变量,为空时回退实例变量)、taskFormData、allowRecall(issues/251,见下)。
instanceState(int,issues/250)=该行所属流程实例的状态,取 wf_process_instance.state (枚举见 03 · 状态机)。列表查询本来就关联实例表,此字段只是把已有 join 的 一列投出来,不引入新关联、不解析流程定义。用途:前端据此把「实例已非进行中」的已办行撤回按钮置灰 (引擎侧判据不变,仍是六条全排前、报错即零写入;置灰只是省一次白点,不是安全边界)。 待办与已办共用同一投影,故两个列表都带该字段。
allowRecall(bool,issues/251)=该行办理时刻节点 allowRecall 开关的快照,供前端把 「实例进行中但节点未开撤回」的已办行也置灰。来源=办理时引擎从 TaskModel 盖进本行变量的 tf_allowRecall(tf_ 前缀不进实例变量、不传播),查询出口只把它从行变量搬运成顶层字段, 不解析流程定义。只投已办行(非 DOING);行上无键(存量行/待办行)⇒ 字段缺失,前端退回可点。 快照仅供预判:撤回校验仍以现读定义为权威(办理后改定义,行上快照不变、校验按新定义判, 二者分歧属设计内,报错文案兜底)。与 instanceState 合起来构成前端置灰的两个静态判据; 窗口判据(下游已办结)仍由引擎兜底,前端不算。
processTask/doneList — 我已办
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| operator | 是 | string | 过滤"我已办"(t.operator = operator,任务办理人;不含发起人 create_user,"我发起但非我办理"不算我的已办;见 §2.5 口径表) |
| pageNum/pageSize/m_* | 否 | - | 分页过滤 |
data → 分页结构,rows 同 todoList。
processTask/execute — 执行任务(核心)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processTaskId | 是 | string | 任务 id |
| operator | 是 | string | 执行人 |
| submitType | 是 | int | 2.8 执行类型(默认 1 AGREE) |
| taskName | 条件必填 | string | submitType=4 JUMP 时目标节点名(jumpAbleTaskNameList 获取) |
| tf_* | 否 | any | 任务表单数据(审批意见 tf_approvalComment、附件 tf_approvalAttachment、抄送 tf_ccActors、预指派 tf_nextNodeOperator、后加签指定人 tf_addSignOperators——后两键互斥、末键需节点开 allowAddSign,判据见 §2.7) |
| countersignDisagreeFlag | 否 | int | 会签拒绝(submitType=20)时 1 = 已记录该成员反对(门面自动注入;仅当节点 countersignCompletionCondition=ONE_VOTE_VETO 才直接推进整单,否则软拒绝不阻断) |
分发逻辑见 2.8 表。data → null
processTask/detail — 任务详情
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 任务 id |
| operator | 是 | string | 判断 executable |
data = taskVo 基础上增加:
| 字段 | 类型 | 说明 |
|---|---|---|
| executable | boolean | 当前 operator 是否可执行 |
| ext | object | 任务变量对象(为空时回退实例变量),必含 isFirstTaskNode |
| jsonObject | object | 流程 JSON 图(前端渲染表单) |
| taskModel | object | {name, displayName, type, form?, ext?} 节点模型信息;ext = 节点 properties.field 原样透传(含 PERMISSION_* 字段权限,前端 initPermission 依据,与 boot2 setTaskModel 一致);form = 节点表单 key |
ext.isFirstTaskNode(六语言必出):当且仅当该任务taskName为流程 JSON 中第一个snaker:task节点 id(首任务节点)且任务处于 DOING 时为true,否则false。语义与processInstance/detail的tasks[]/activeTaskList[]行的ext.isFirstTaskNode一致——前端process-task/detail.vue:61双兜底record.isFirstTaskNode || record.ext?.isFirstTaskNode,据此在详情抽屉对首任务节点 DOING 时开放"重新提交"。task detail 与 instance detail 两条出口都须提供(此前仅 instance detail 提供,task detail 缺,已补齐对齐)。
processTask/jumpAbleTaskNameList — 可跳转节点列表
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processInstanceId | 是 | string | 实例 id |
data → [{ "label": "节点显示名", "value": "节点名" }](已走过的非会签节点)
processTask/candidatePage — 候选处理人
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processTaskId | 是 | string | 任务 id(id 亦可) |
模型候选命中(节点配置
candidateUsers等)→ 分页 rows,行契约(六语言统一):键 必有 说明 id是 行主键,取 src. id→ src.userId→ actorId(字符串化),供前端valueField:'id'取值realName是 显示名,取 src. realName,缺省回落iduserId兼容 src 含 userId时保留(对齐旧消费方)userName可选 src 含时透传 deptName可选 src 含时透传(IUserProvider.getUser 子路径可得) 用户信息映射优先级:IUserSearchProvider.findById → IUserProvider.getUser(realName/deptName 可得时透传)→ 兜底
{id: actorId, realName: actorId}。无模型候选 → 走 IUserSearchProvider 用户分页搜索(需集成方注入,query 透传 m_* 条件); 未注入明确报错
processTask/surrogate — 加签(追加参与人)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processTaskId | 是 | string | 任务 id |
| actorIds | 是 | string[]|string | 新增参与人(数组或逗号分隔字符串) |
语义:只追加不清空——原参与人全部保留可办(普通任务追加后任一完成即可;会签任务追加为额外会签任务)。
本 action 不是"转办"。摘走原办理人的语义在
processTask/transfer(见下)。 历史标题写作"转办/加人"属措辞缺陷,已更正(issues/115)。 data →null
processTask/addCandidate — 同 surrogate
processTask/transfer — 转办(摘原人 + 换新人)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processTaskId | 是 | string | 任务 id |
| fromActor | 是 | string | 被摘走的原参与人 |
| toActor | 是 | string | 接手的新参与人 |
| reason | 否 | string | 转办原因(进审批记录留痕) |
| operator | 是 | string | 操作人(不接受缺省) |
归属判据:operator == fromActor,或 operator ∈ {flow.auto, flow.admin};否则 code=99999999 + msg(如 无权限转办该任务)。即只能转自己那一条待办,管理员/系统除外。 (flow.auto/flow.admin 同样是字面量哨兵,生效边界见上文 §processInstance/withdraw 「判据 3 的边界」那条注——经壳登录的真实超管不命中,超管可操作性归集成层权限码 wf:processTask:transfer。)
语义(七条,逐栈必须同实现):
- 摘原人:仅删
fromActor在该任务的wf_process_task_actor行,不动其他参与人 (会签节点上转的是"自己那一票",其余成员不受影响)。 - 加新人:
toActor追加为该任务参与人,与普通/会签的既有办理规则一致(普通任务任一可办; 转给多人时用processTask/surrogate加签,不用本 action 循环)。 - 任务不新建:沿用同一
processTaskId,待办从 A 的列表挪到 B 的列表,高亮图/节点进度不变。 - 留痕(三件,缺一不可):
- 任务行
submitType置 7 TRANSFER。approvalRecord取的是该实例全部任务行(不按状态过滤), 所以转办后、B 办结前,这条记录在审批历史里直接读作"转办";B 办结后该槽位由 B 的办理动作覆盖(1/2/20),属预期。⚠️ 严禁覆写任务的
actor_id/operator列:进行中任务该列恒无值是既有不变量(见 4.3 taskVo 与 §2.4), 而pageDoneTasks按state <> 10 AND operator = ?过滤——转办时把被摘走的人写进这一列, 该单一旦撤回/终止(离开 DOING 但保留该列值),会凭空出现在他从没办过的「我已办」列表里(Node 实测)。 "办理人记谁"由update_user= 转办操作人 +tf_transferHistory[].operator承载,不占actor_id。 - 任务变量追加式列表
tf_transferHistory:每一跳append一条{submitType:7, fromActor, toActor, reason, time, operator},只追加不覆盖。 它是跨跳的持久账本——B 再转给 C 时 A→B 那条仍在,B 办结后仍在(变量是合并语义,见下条)。 六键固定 camelCase;reason无值写""不写 null;time一律"yyyy-MM-dd HH:mm:ss"字符串 (§2.4 全生态时间格式,不得各栈用本地 ISO 方言或时刻对象——账本要跨栈同形)。 单跳便捷键tf_transferTo/tf_transferReason一并写(前端可省一次遍历)。 - 末跳可读文案写
tf_approvalComment(值形如A 转办给 B(原因…))——前端审批意见的既有读取位 (issues/15+124:approvalRecord的ext透出,ext.tf_approvalComment)。转办发生在该任务办结前, 此槽位此前无主,不覆盖既有数据;多跳时它只留末跳,全量账本以tf_transferHistory为准。 引擎不新增响应字段、不新造历史表。
- 任务行
- 办理提交的变量合并序(转办留痕的前置条件,八栈必须同构):
实例变量为底 ← 任务既有变量 ← 本次提交参数,本次提交参数优先级最高; 既不得整体替换任务变量(会抹掉tf_transferHistory),也不得让任务既有变量压过本次提交参数 (Go 曾如此:转办的submitType=7会反噬 B 提交的 1/2/20,导致记录失真且会签一票否决判据失效)。 - 去重:
toActor已是该任务参与者 →code=99999999+ msg(明确报错,不静默成功)。fromActor不在参与者里 → 同样明确报错。 - 前置态:任务非进行中(
taskState != 10)→code=99999999+ msg。 data →null
失败 msg 跨栈统一文案(引擎侧失败码一律 99999999,细粒度原因只由 msg 承载):
| 场景 | msg(逐字) |
|---|---|
撤回/转办/加签等缺 operator | operator 必填 |
fromActor 参数缺失或空 | fromActor 必填 |
toActor 参数缺失或空 | toActor 必填 |
| 撤回人不在归属判据内 | 无权限撤回该流程实例 |
| 转办操作人非 fromActor 且非 auto/admin | 无权限转办该任务 |
| 摘人操作人非被摘本人且非 auto/admin | 无权限摘除该任务参与人 |
按 processTaskId 查不到任务(摘人) | 任务不存在 |
fromActor 不在该任务参与者里 | 原办理人不是该任务参与人 |
toActor 已是该任务参与者 | 目标人已是该任务参与人 |
| 任务非进行中(转办) | 任务非进行中,不可转办 |
协办·缺 actorIds 或空 | actorIds 必填 |
| 协办·操作人非主办行名册且非 auto/admin | 无权限派生协办任务 |
| 协办·主办行非进行中 | 任务非进行中,不可派生协办 |
| 协办·该人已有未办结协办行 | 该人已有未办结的协办任务 |
| 协办·协办行再派生协办 | 协办任务不能再派生协办 |
协办·等待闸未齐(waitCompletion=true) | 节点[{节点名}]协办未办结(已办结 {m}/{n}),不能办理 |
| 任务非进行中(摘人) | 任务非进行中,不可摘除参与人 |
| 摘人后该任务再无参与人 | 至少需保留一名参与人 |
退回上一步·无血缘(task_parent_id 为 NULL 或 0) | 上一步任务ID为空,无法驳回至上一步处理 |
退回上一步·canRejected 守卫不过 | 无法驳回至上一步处理,请确认上一步骤并非fork、join、suprocess以及会签任务 |
后加签·与 tf_nextNodeOperator 同传 | tf_addSignOperators 与 tf_nextNodeOperator 互斥,不能同时提交 |
后加签·节点未开 allowAddSign 却传键 | 节点[{节点名}]未开启 allowAddSign,不接受 tf_addSignOperators |
| 后加签·加签给自己 | 不能把任务加签给自己 |
后加签·超 addSignMaxRounds | 节点[{节点名}]的加签轮次已达上限 {N},本次提交被拒绝 |
| 门面捕获到非引擎契约异常(运行时/驱动/解析器的内部细节,判别式见 §2.12) | 流程处理失败 |
码不进文案:
20010007/20010008(引擎层WfErrEnum内部码,见引擎操作 04 · 退回上一步)只留在引擎内部,对外msg一律用上表的逐字文案、不带码数字前缀;响应体也永不透传业务码(恒99999999)。
processTask/aidant — 动态协办(派生不驱动的协办行)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processTaskId | 是 | string | 主办行任务 id |
| actorIds | 是 | string[]|string | 协办人(每人一行子任务) |
| reason | 否 | string | 派生原因(进账本+协办行戳) |
| waitCompletion | 否 | bool | 缺省 false=主办不等协办办结即可推进;true=等待闸 |
| operator | 是 | string | 操作人(不接受缺省) |
归属判据:operator 在主办行参与者名册内,或 ∈ {flow.auto, flow.admin};否则 code=99999999 + 无权限派生协办任务。哨兵生效边界同 transfer 那条注。
语义(六条,逐栈必须同实现;建单/闸/留痕细节见 规范 04 · 动态协办):
- 派生不驱动:按人建
task_type=1子行(task_parent_id=主办行 id、同节点同名), 协办行办结不产生执行对象;executeTask/executeAndJumpTask两路同闸;主办行保留、办结才推进。 - 等待可配:
waitCompletion=true时主办办结前判"无 DOING 协办行"(计数跳过 99), 未齐报错零写入;缺省false时主办可随时推进,未办结协办行随离开节点废弃清场。 - 禁递归:协办行携带派生参数 ⇒ 报错;协办行可加/摘参与人、可被转办(owner 拍,偏离 snaker 禁令)。
- 不计入会签合并:会签合并判据显式排除
task_type=1行(snaker 同名全算会误挡)。 - 与征询并存:两族子行靠
task_type分辨(协办=1/征询成员=0),两道闸各数各的行。 - 留痕:
tf_aidantHistory追加账本+tf_aidantReason行戳+ext.aidant投影; 不占tf_approvalComment、不新增 submitType 档与事件码。 data →null
失败 msg 见上文跨栈统一文案表(协办六行)。
processTask/recall — 已办撤回(新行复活重办,issues/246)
办理人撤回自己刚办结的那一手,同实例内复活重办。节点开关 allowRecall(缺省关;会签/申请节点禁配, 规范 02 §4.4);窗口判据与动作三件详见 规范 04 · 已办撤回。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processTaskId | 是 | string | 要撤回的任务行 id(必须 FINISHED) |
| operator | 是 | string | 操作人(硬必填,与 transfer/withdraw 同口径) |
语义(逐栈必须同实现,判据全排前、报错即零写入):
- 窗口(宽口径,owner 2026-11-03 拍):目标行沿
task_parent_id链产出的全部下游任务行中 不存在任何 FINISHED ⇒ 可撤;任一已办结 ⇒ 报错(逐字文案见下表)。 - 动作三件(同一聚合变更):下游全部 DOING 行废弃(含后加签/征询成员行,账本记撤回废弃); 原 FINISHED 行不改写、
tf_recallHistory追加{operator, time, recalledTaskId}; 同节点新建一行 DOING(参与者=原行名册+当时生效委托并入、不摘原人;parent=原行 parent、expire_time同尺重算、fire 码 3)。 - 事件:fire
TASK_RECALL(10)(规范 11),撤回动作落库之后一次。 - 权限:目标行参与者含
operator,或flow.auto/flow.admin(转办/摘人同口径)。 - 不回滚业务数据:f_ 已进实例变量、persist 已写业务表——撤回只撤推进(承诺边界,规范 04)。
失败 msg 跨栈统一文案(引擎侧失败码一律 99999999,逐字钉死):
| 条件 | msg |
|---|---|
| 下游存在已办结行 | 任务[{节点名}]的后续节点已办理,不能撤回 |
节点未开 allowRecall | 节点[{节点名}]未开启 allowRecall,不能撤回 |
| operator 非目标行参与者 | 无权限撤回该任务 |
| 目标行非 FINISHED | 任务非已完成状态,不可撤回 |
| 实例非 DOING | 流程实例非进行中状态,不可撤回 |
码不进文案:内部错误码只留引擎内部,对外
msg用上表逐字文案(同 §processTask/transfer 那条纪律)。
processTask/revokeDynamicCountersign — 撤回动态会签(issues/247)
主办行撤回未提交意见的动态会签成员,是征询模式置灰态的唯一恢复出口(收齐后本 action 报错)。 节点开关 dynamicCountersign;引擎裁决详见 规范 04 · 动态会签。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processTaskId | 是 | string | 主办任务行 id(DOING) |
| operator | 是 | string | 操作人(硬必填) |
| reason | 否 | string | 撤回原因(进账本条目) |
语义(逐栈必须同实现):
- 废弃:本主办行下全部未答成员行废弃(复用废弃腿);账本
tf_addSignHistory追加撤回条目 (round、被撤人、reason 选填、时间、操作人);已提交意见行原样保留(审计凭证不动)。 - 闸门自然恢复:闸门判据是"还有无 DOING 成员行",撤完即无;轮次不消耗(再拉 round 照常 +1)。
- 权限:主办行参与者含
operator,或flow.auto/flow.admin。
失败 msg 跨栈统一文案(99999999,逐字钉死):
| 条件 | msg |
|---|---|
| 无待答成员行 | 节点[{节点名}]没有进行中的动态会签 |
| operator 非主办行参与者 | 无权限撤回该动态会签 |
processTask/removeTaskActor — 摘除参与人(只摘不加、不留痕)
第 47 个 action(现 46 个,八栈分派集合逐字相同)。SPI 侧 removeTaskActor 早已是必选方法 (SPI 05 的类型表与「必选」那条注),八栈两仓都实现;本 action 只是把它上到门面(issues/115 的残留)。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processTaskId | 是 | string | 任务 id |
| actorIds | 是 | string[]|string | 被摘除的参与人(数组或逗号串两形同判据,一律过各栈既有归一单点) |
| operator | 是 | string | 操作人(不接受缺省、严禁回落 user1,与 transfer/withdraw 同口径) |
语义(逐栈必须同实现):
只摘不加:删
actorIds在该任务的wf_process_task_actor行,不动其他参与人、不新建任务、 不写任何任务变量。加人与换人各有自己的 action(processTask/surrogate追加、processTask/transfer换人)。不留痕、不 fire 事件:
submitType不置 7、不写tf_transferHistory/tf_approvalComment、 不覆写任务行actor_id/operator列,也不发流程事件。留痕属"转办"这一事实, 单纯摘人没有"换人"这个事实可记(要留痕请用transfer);issues/132 §11.3 定稿的 事件集里没有"摘除参与人"这一码,码 7TASK_TRANSFER的语义是"参与者被替换", 只摘不加却发码 7 会把没发生的"转办"写进事件流——本 action 一律不发(要立法先开 issue)。归属判据同
transfer:operator∈ 被摘集合,或operator∈ {flow.auto,flow.admin}; 否则无权限摘除该任务参与人。即只能摘自己那一票,管理员/系统除外——transfer之所以能"摘 A 加 B" 是因为 A 就是操作人本人,本 action 同理不得借道摘他人。哨兵生效边界同transfer那条注 (真实超管不命中,超管可操作性归集成层权限码)。只作用于进行中任务:非 DOING 一律
任务非进行中,不可摘除参与人。已办结/废弃/撤回的历史行 其参与人行是审批链的取证依据(approvalRecord读全状态任务行),摘它会改写历史。不得摘空:摘完后该任务至少剩一名参与人,否则
至少需保留一名参与人。少了这一条, 一次误操作就会留下永远无人可办、也无法撤回重派的死任务——比"配错表达式落 NULL"严重得多。 判据是集合差(当前参与者 − 归一后的actorIds),不是"入参条数"——actorIds里混着非参与者的 id 也不能绕过这一条。集合差里只有归一后非空的行算"一个人":历史actor_id=''/纯空白脏行 撑不起这条下限(它谁也办不了),否则"摘空"会伪装成成功。匹配取归一值、
DELETE取「原值 ∪ trim 值」两形并集(§2.11 硬要求②的删除腿; owner 2026-10-02 拍「两形并集」,取代此前的"只取行原值"草案): 库里那一行可能是修复前落下的未 trim 原值(' leader '),也可能是写侧归一后落下的规范值(leader) ——两者按 §2.11 是同一个人,删除腿必须两种形态都删得掉。只取一头各有一种假成功:- 只拿归一值去
DELETE⇒ 判成同一人却删不掉历史脏行,门面报成功而被摘的人待办还在(go 栈实测到); - 只拿行原值去
DELETE⇒ 第三方绕过门面直连仓储传" 8601 "时删不掉规范行8601(issues/142 §9.2 那一路)。
⇒ 仓储删除侧的义务是三件事(八栈两仓逐处同实现): ① 空值一律丢弃、不喂
DELETE——null/''/纯空白都不进IN,否则历史actor_id=''脏行会被批量误删(那是替脏数据做掉唯一痕迹); ② 非空值同时以「原值」与「trim 值」两形进IN(去重、保序;两形相同则只一份); ③ 并集为空 ⇒ 一条DELETE都不发(早退,不退化成"清空该任务全部参与者")。判空一律
trim(x) == '',严禁用语言自带假值判据("0"必须留下,且"0"与"00"是两个人)。 各栈复用既有归一单点旁挂的删除腿变体——javaStringUtils.actorDeleteForms/gospi.ActorDeleteForms/ nodespi.actorDeleteForms/pyspi.actor_delete_forms/phpCcActorUtil::deleteForms/ rsmodel::actor_delete_forms/moon@model.actor_delete_forms/c#PageQuery.ActorDeleteForms; trim 与判空的判据本体仍是原单点那一枚,不抄第二份。⚠️ 明文不承诺的一角(别把它当缺陷反复立案):并集只从入参展开,所以 「调用方给的是已 trim 的
9101,而库里躺的是未 trim 的历史脏行' 9101 '」这一种组合删不掉。 门面路径不受影响——语义 6 要求门面交出的是行上的原值,原值形天然命中;受影响的只有 绕过门面直连仓储、且自己凭空构造出 trim 形的第三方调用方撞上修复前落下的历史脏行。 要彻底覆盖就得在 SQL 里比TRIM(actor_id)(吃不掉索引、且各方言TRIM语义不一致)或让仓储 先读出该任务全部行再逐一展开——两者都属过度设计(owner 2026-10-02 第 5 问同一条精神)。 正确做法是清洗历史脏行(写侧归一已保证新行必是 trim 形),不是把删除腿做成全表扫描。 收口记录(2026-10-02,替代此前重复贴了两遍的 ⚠️ 待裁定警告块):本条在 1.8.36 之前 八栈没有一处真成立,且分成相反的两派——phpPdoProcessRepository:380/InMemoryProcessRepository:224、 csharpMemoryRepository:319/MySqlRepository:476、rustmemory.rs:313/repository-sqlx lib.rs:837、 moonmemory.mbt:282/repository.mbt:442(四栈八处,此前 spec 只记了前三栈、漏了 rust) 在删除前把实参再过一遍归一单点 ⇒ 只留 trim 形,门面交出的行原值" 9101 "被削成9101, 真库(NO PAD 排序规则)下那一行删不掉而门面报成功;go 两仓、node 两仓、python 两仓、 java 三处(jdbc+persistMemoryRepo:86+coreMemoryProcessRepository:256)(四栈九处) 则是裸传 ⇒ 未 trim 脏行删得掉,但空值照喂DELETE(误删actor_id=''脏行)。 按「两形并集」统一后,142 §9.2「删除位 trim」的既有测试无需反向改(并集包含 trim 形): rusttest_i142_b_remove_task_actor_trims_and_blank_is_noop(内存+mysql 两格)、 mooni142b_task_actor_write_test.mbt:72「删除位 trim 命中+空档零删除」、moon T1-F119 照绿。- 只拿归一值去
幂等(非参与者静默忽略):
actorIds里不属于该任务参与者的 id 不报错,按集合差落库即可。 本 action 是"清理/收回"用途,重复摘同一个人(前端双点、或集成层重放)第二次应得成功信封; 若要"人不在任务里就报错"请用transfer(它有原办理人不是该任务参与人这条判据)。入参缺失:
processTaskId缺键 / 空串 / 纯空白 / 0 / 负数,或actorIds归一后为空 ⇒ 与surrogate同一逐字文案processTaskId/actorIds 缺失(同族同文案,不另造;0 与负数走这一档而不是任务不存在——"拿 0 当 id 查不到"和"没传 id"是同一种调用方错误,§2.11「主键类参数另判一档」)。 ⚠️ 不统一的一档:processTaskId给了但不是数字 / 超出精度("abc"、9e999)属另一种事实, 各栈既有形状为准、不作跨栈判据(java/node 折进缺参数档,moon/csharp 走本栈既有"非法 id"信封; 把它统一成任一句都会让"传错了类型"排障时看不到真因)。 各栈兄弟 action 的缺参数文案本身也尚未跨栈统一(java=合并档processTaskId/actorIds 缺失; node/php=actorIds 缺失与id 缺失或非法/processTaskId 缺失或非法两档分开的)—— 本轮只把新 action 钉成合并档,不回改兄弟档(改它们的 msg 会破既有门禁格与栈内断言)。
守卫次序(逐栈一致,门禁按此断言 msg,不接受各栈自行排序): operator 必填 → processTaskId/actorIds 缺失 → 任务不存在 → 无权限摘除该任务参与人 → 任务非进行中,不可摘除参与人 → 至少需保留一名参与人 → 落库。 (前两支沿用 transfer 的形状:必填档先判,避免"参数全缺"时先报出主键缺失、把鉴权缺口藏进参数报错里。)
任务不存在是本 action 的逐字判据。pythontransfer那支历史上抛的是task not found: {id}(142 之外的既有分叉,本轮不回改它),但新增 action 一律用任务不存在,八栈不得各写各的。
data → null(前端消费面现状:surrogate/addCandidate 的调用点也不读 data)。
内置版(boot2/3/4)不补同名端点:内置版只有通用 CRUD
/wf/processTaskActor/remove(按行 id 删,语义不同)。因此本 action 是 jeeflow 引擎自有扩展——与processTask/transfer同类(内置版ProcessTaskController同样没有 transfer 端点)。集成壳按权限码wf:processTask:removeTaskActor(规律wf:{action:/→:})动态校验,前端消费与按钮登记另轮随需补。
processTask/latest — 实例当前进行中任务
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processInstanceId | 是 | string | 实例 id |
data → taskVo(第一个 DOING 任务)或 null
4.4 流程设计 processDesign/*(需 IProcessExtRepository)
设计稿(草稿)≠ 定义(发布产物):save/updateDefine 存草稿快照(历史表), deploy 才生成流程定义。设计稿内容变更后 isDeployed 自动置 0(防误用旧定义)。
processDesign/page — 设计分页
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| pageNum/pageSize/m_* | 否 | - | 分页过滤 |
data → 分页结构,rows 行字段:id, name, displayName, type, icon, isDeployed, remark, createTime, createUser, updateTime, updateUser(时间字段格式 yyyy-MM-dd HH:mm:ss,见 §2.4)
processDesign/detail — 设计详情
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 设计 id |
data:id, name, displayName, type, icon, isDeployed, remark + jsonObject(最新设计稿内容,缺失基本信息时从设计表补齐 name/displayName/type/processDesignId)
his(历史快照列表)
processDesign/save — 新建/保存设计(含草稿内容)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 否 | string | 有 = 更新基本信息;无 = 新建 |
| name/displayName | 新建必填 | string | 名称 |
| type | 否 | string | 类型(默认 approval) |
| icon/remark | 否 | string | 图标/备注 |
| content | 否 | string|object | 设计稿 JSON(有则存历史快照,并置未部署) |
data → { "id": "设计 id" }
processDesign/update — 只改基本信息(不写快照)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 设计 id |
| name/displayName/type/icon/remark | 否 | string | 仅传要改的字段 |
data → null
processDesign/updateDefine — 保存设计稿(设计器保存)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processDesignId | 是 | string | 设计 id |
| (设计稿 JSON 顶层展开) | 是 | object | 设计稿 JSON 字段平铺请求体(name/displayName/type/nodes/edges…)——vben5 前端约定 |
| content | 兼容 | string|object | 引擎兼容写法:整体塞进 content 字段 |
语义:快照入库(与最新相同则不重复存)+ 同步 name/displayName/type + 置未部署。 data → null
processDesign/remove — 删除设计
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 二选一 | string | 单删 |
| ids | 二选一 | string[] | 批量删 |
data → null
processDesign/deploy — 设计发布(生成流程定义)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 设计 id |
语义:取最新快照 → 生成流程定义(版本管理同 deploy)→ 设计置已部署。 data → { "processDefineId": "..." }
processDesign/redeploy — 设计重新发布(原地替换定义)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 设计 id |
语义:取最新快照 → 按 name 找最新定义:有则原地替换内容(version 不变、state 不变——停用中的定义 redeploy 后仍停用),无则新建。 data → { "processDefineId": "..." }
processDesign/listByType — 按类型分组(发起申请页数据源)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| - | - | - | 无参数 |
data → { type: [item, ...] },item:
| 字段 | 类型 | 说明 |
|---|---|---|
| processDesignId | string | 设计 id |
| name/displayName/icon/remark | string | 设计信息 |
| processDefineId | string|null | 该 name 最新已发布定义 id(未发布为 null) |
| processDefineState | int|null | 定义状态,六语言必出:取该 name 最新定义的 state(1 启用 / 0 禁用,未发布为 null)。前端"发起申请"卡片以 items[].processDefineState !== 0 控制发起按钮可用性——定义被 upAndDown 禁用(state=0)时不可发起,该键是发起流程的硬依赖 |
| jsonObject | object | 最新设计稿(设计器回显) |
分组序契约(2026-08-31 补)
- map 形态遍历序不作保证:
data为 map({ type: [items] })时,六语言引擎用不同分组容器 (javaLinkedHashMap/ gomap/ pythondict/ nodeobject/ phparray/ rustserde_json::Map=BTreeMap), map 的 key 遍历序由各语言容器与原生序列化行为偶然决定,引擎不作契约保证(六引擎本体各自确定, 但序语义实为四种:id 首现 / 数字升序 / type·字典序 / 种子序)。消费端(集成层)把 map 转有序数组时, 必须按下述契约序自行排序,不得依赖引擎 map 遍历序。 - 有序数组分组序 = type 数值优先升序:type 可解析为整数时按数值升序;不可解析为整数时按字符串升序; 数值型 type 排在前、非数值型 type 排在后。例:
["1","2","6"]→1 > 2 > 6;["1","a","10"]→1 > 10 > a。 该序由集成层 map→array 转换处保证(八套集成层统一实现),前端不再排序(vben 保持不排序、依赖本契约; App 保留既有sortGroupsByType作展示兜底,与本契约一致)。 - 组内 items 序 = 引擎行序,保持现状:除 php(PDO 腿为
create_time DESC)外,各栈 SQL 腿默认ORDER BY id DESC(最新设计在前);内存腿序不作保证,契约保持(八语言现读复核;issues/220 · audit8C5-L3 §10-7更正)。
4.5 委托代理 processSurrogate/*(需 IProcessExtRepository)
运行期语义(引擎必须实现,issues/116)
processSurrogate/* 这五个 action 只是台账 CRUD。真正的能力是任务创建时自动应用生效中的委托, 本节把它定为契约(此前 spec 只写台账、运行期归谁无人规定,各栈默认不注册 ⇒ 用户在「我的委托」里 配好"休假期间张三替我批",单子仍只发给张三本人):
- 时机:任务参与者解析完成后、参与者落库前(即"建单那一刻"),引擎对每个 actor 查一次生效委托。 覆盖范围是全部建任务路径——发起、办理推进、串行会签的每一步推进、跳转(JUMP)、 回退(ROLLBACK);只挂在"发起"一处会漏掉流转中产生的新单(实测易犯)。 每条路径各留一条独立用例:合并成一条"全流程都覆盖"的用例,单条路径失能时不会红。 1.1
processName取值口径:以流程模型的name(流程 JSON /ProcessModel.name)为准, 模型未带时回落wf_process_define.name。 「未带」= 键缺失、null、空串或仅空白——判据一律 先 trim 再判空,命中后传出去的也必须是 trim 后的值(" "不得当流程名去查委托)。 依据是迁移基线:内置版(mldong-wf)的SurrogateInterceptor用的正是execution.getProcessModel().getName(),Java 参考实现与之同构;用户在内置版配的委托, 迁到 jeeflow 后必须命中同一条。 正常情况下两者恒等 —— deploy 执行def.setName(model.getName()), 各栈测试建议保留一条"define.name 与 model.name 不一致"的诱饵行,钉住自己取的到底是哪一个。 回落路径要读定义行(部分栈含contentBLOB),逐次 execution 解析一次后复用,不要逐任务解析。 1.2 不级联:只对建单那一刻的原始参与者快照逐个查一次委托,代理人自身的委托不展开 (A→B 且 B→C 时,C 不因此收到该单——避免环状委托死循环)。实现上必须先取快照再遍历, 不能边遍历边往同一集合追加。 1.3 串行会签:代理人只进当一步任务的参与者,不扩operatorList一类投票名册(否则改票数)。 1.4 多条同时命中取哪条:getSurrogate返回最新一条(按主键 id 最大), 内存仓与 SQL 仓必须同答案(SQL 侧ORDER BY id DESC,内存侧不得"取遍历到的首条")。 ⚠️ 顺序本身是契约的一部分:「取最新一条」= 先在作用域内按 id 取最大的一条,再交条款 3/4 的判据裁决这一条; 不得实现成"先按判据过滤掉不生效的、再从剩下的取 id 最大"。两种写法只在 「旧记录有效 + 新记录无效」这一形状上分叉,而它恰是用户最常见的序列 (先配一条窗内委托,之后改成停用 / 改到未来 / 改成自委托):前者判否 ⇒ 不并入(正确), 后者会把旧的有效记录复活 ⇒ 永久并入(issues/123 里 13 栈恒并入的成因)。 SQL 侧形状:WHERE operator = ? [AND process_name = ?] ORDER BY id DESC LIMIT 1——不带enabled = 1/ 窗口 /surrogate <> operator谓词,判据落在读出之后的单条裁决里。 精确作用域那条判否后仍要看全流程作用域(process_name为空)的最新一条: "精确已过期 → 兜底全流程委托"是既有钉住的行为,不得改成判否即止。 必测形状:同(operator, processName)先建"窗内+enabled=1"、再建一条更"新"的无效记录 (窗外 /enabled=0/enabled脏值 / 自委托 四形)⇒ 断言不并入;只有一条窗内有效记录 ⇒ 断言并入。 (参考实现 jeeflow-java6feeae6。) - 动作:命中则把被委托人(
surrogate)追加为该任务参与人;授权人保留,任一可办 (与processTask/surrogate加签同语义——委托不是转办,不摘原人)。⚠️ 追加要落在参与者集合本身(随后随任务一起落库),不得靠"事后再调一次
addTaskActor补写": Java 首版SurrogateInterceptor正是走补写路,而它在 taskId 分配前触发,那次补写打在空 id 上 是静默无效的——能力看起来实现了,实际一单都没代理出去。挂点若只能在任务落库后触发, 则必须确保 taskId 已分配后再补写,并断言代理人真的出现在wf_process_task_actor里。 - 默认开启、可显式关闭:各语言引擎内置该行为并默认启用;集成方须能通过扩展点关闭 (注册空实现 / 配置开关),关闭后回到"仅台账"行为。
- 未配置
IProcessExtRepository时静默跳过:不得抛"未配置扩展仓储"把建单流程打断—— 委托是增强能力,缺仓储属于正常部署形态。 - 查询判据(四条件,跨栈必须同答案,同一份数据在任一栈都得同一个结论):
- 空
processName= 全部流程兜底:先按当前流程名精确查,未命中再查process_name IS NULL OR process_name = ''; - 时间窗:
start_time <= now <= end_time,start_time/end_time为 NULL 表示该侧不限; - 自委托过滤:
surrogate <> operator(自己委托给自己不生效); enabled读写两侧分别定(issues/116 落地时 C# 指出这两侧被我此前的单条措辞混在一起):- 读侧(判据):只有
enabled == 1生效。0/2/-1/NULL/ 库内脏值一律不生效 ——"只有 1 生效"是白名单式判定,不做"非 0 即真"的宽松解析。 - 写侧(
processSurrogate/save|update入参):键缺失 → 落 1(沿用本节 save 表的"默认 1"); 空串''、"abc"、"1x"等不可解析为整数的脏值 → 落 0(不得当启用), 且不得抛错变 500(Node 首版toInt直接抛「数值缺失或非法」把门面打成 500)。 布尔入参按true→1 / false→0。 - 两侧必须同一套语义:写侧落 0 的行,读侧必须查不到生效委托(跨层对拍用例)。
- 读侧(判据):只有
- 空
- 内存仓与 SQL 仓两条路径都要满足第 5 条——同栈两仓给出不同结论即缺陷(已实测存在,见 issues/116 §5)。
与内置版(mldong-wf)的三条方向差异 · 迁移必读(issues/152)
上表的判据方向与 mldong 基础框架内置工作流模块的 ProcessSurrogateServiceImpl.getSurrogate 相反。 内置版不是引擎的"旧实现",是另一套语义,因此同一份委托数据迁过来会给出不同结论,迁移方必须逐条告知; 代码侧一律以本规范为准(owner 2026-10-08 拍:八栈保持现状,不反向迁就内置版)。
| 判据点 | 内置版 | jeeflow 引擎 | 迁移动作 |
|---|---|---|---|
| 作用域优先级 | 全流程优先:先扫 process_name 为空的行,命中即返回,精确作用域那段代码根本走不到 | 精确优先:精确作用域取最新一条裁决,判否才回落全流程(条款 1.4 末句) | 同一授权人同时配了「全部流程」+「某流程」且都窗内时,接管人会反过来。迁移前普查这种叠加配置;想复刻内置版观感只能删掉精确那条——规范不接受"全局盖精确" |
| 择优顺序 | 先过滤再取最新:SQL 带 enabled=1,ORDER BY id DESC 后窗不合格就 continue 找更旧的一条 ⇒ 停用/改期最新一条后回落到上一条窗内委托 | 先按 id 取最新一条,再交判据裁决(条款 1.4;左列那种写法正是 issues/123 判 13 栈恒并入的病根) | 停用即彻底无委托。这是有意改变的行为,不当回归修 |
| 自委托过滤 | 无 surrogate <> operator,只被建单时的参与者去重掩盖 ⇒ 一条"委托给自己"的行会盖住同作用域更旧的有效委托而静默不出人 | 判据内(条款 5)+ 并入处第二道 | 迁移前清理 surrogate = operator 的历史行,否则两版对同一条待办一个出"更旧那条的人"、一个不出人 |
processSurrogate/page — 委托分页
data → 分页结构,rows 行字段:id, processName, operator(授权人), surrogate(被委托人), startTime, endTime, enabled(1启用/0停用), createTime, createUser, updateTime, updateUser
归属不变式(issues/152 ②):t.operator 是归属列,与 §2.5 那一族同一把尺子,两层都要有——
- 门面层:把 §2.5 归一后的 operator(空串/全空白/缺键 ⇒ demo 缺省
user1)作为t.operator EQ条件下发, 形状与本栈自己的instancePage一致即可——各栈查询 API 不同(java 的条件列表、node 的 filters 结构体、 rust 的PageQuery.operator字段都算同形),判据只看结果:不带 operator 时出的必须是user1的行,不是全库。 集成方注入真实登录用户 id 即可;前端不传operator不算调用方缺陷——归一化本来归引擎管。 - 仓储层:绕过门面直调
pageSurrogates时,落在归属列上的 EQ 条件值为空,或归属条件整条没给, 一律 ⇒ 返回空页(SQL 侧AND 1=0、内存侧判不命中),绝不允许"这条条件不加"退化成全库台账 —— 与 §2.5 抄送侧"归属条件必填,条件缺失或为空值时返回空页"是同一条尺子,缺失档与空值档同判。 只收归属列,不动m_LIKE_*那套"空值当没填"的通用放行。 - 内存仓与 SQL 仓必须同答案(条款 6 同一条规矩)。
立法前这里是契约空白,八栈各给一个答案(下发等值谓词出 0 行/假值不过滤出全量/AND 1=0 出空页/ continue 出全库且被既有测试钉成契约/内存仓整个忽略 conditions)。自本节起统一到"空页"这一档; 被旧答案钉住的既有测试按本节改正,改正时必须逐字交代改了哪条断言、原期望是什么。
processSurrogate/save — 新建委托
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processName | 是 | string | 委托的流程名(空 = 全部流程) |
| surrogate | 是 | string | 被委托人 id |
| startTime/endTime | 是 | string | 生效时间段(yyyy-MM-dd HH:mm:ss) |
| enabled | 否 | int | 1 启用 / 0 停用(默认 1) |
data → { "id": "..." }
新建时授权人(operator)默认取操作人。编辑走独立的
processSurrogate/update。⚠️ "默认取操作人"就是 §2.5 那把尺子:缺键/空串/全空白一律走门面归一(⇒ demo 缺省
user1),不得落空串 (issues/152 ③)。空串行不是"报错行"而是"死行"——getSurrogate的WHERE operator = ?永不命中它, 台账里看得见、待办永远不并人,比报错更难查。rust 曾在这条腿上单独用arg_str_or(..., ""), 而它自己就有operator_arg,属漏用而非语义分叉。
processSurrogate/update — 更新委托
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 委托 id |
| processName | 是 | string | 委托的流程名(空 = 全部流程) |
| surrogate | 是 | string | 被委托人 id |
| startTime/endTime | 是 | string | 生效时间段(yyyy-MM-dd HH:mm:ss) |
| enabled | 否 | int | 1 启用 / 0 停用(默认 1) |
data → { "id": "..." };id 不存在报 99999999(msg 委托记录不存在)。
授权人(operator)在请求缺省时保留原值——前端编辑表单不带 operator,若按 save 语义取操作人会把授权人改掉。
缺键档(issues/236 子题① 立法,2026-10-15 owner 拍 A=钉现状多数派):除上面那条 operator 专例外,上表其余四腿(processName/surrogate/startTime·endTime/enabled)请求里没带=清空该列,不是"保留原值":
processName缺省 → 落空(全流程兜底读侧判process_name IS NULL OR process_name = '',见本节条款 3,null与''等价、不构成第二维分叉);surrogate缺省 → 落空;时间窗缺省 → 两端落空;enabled缺省 → 复位 1(不是保留原启用状态)。- 判据形状="含键即覆写":只有
containsKey为真才用请求值,缺键走上面的默认落值。这条把"只改启停"这类局部请求的后果写明——它会顺带清掉流程名、被委托人与时间窗(精确作用域的委托降级成全流程委托),调用方要改单列必须把其余列一起回填。 - 反面形状(本条打红的两栈,修法入 audit8 行为并批轮):rust 四腿全走
unwrap_or(原值)/or(原值)=全保留;moon 混挂=processName/surrogate保留、时间窗与enabled清空,是第三种形状。合规七栈(含参考实现 javaapplySurrogateFields四腿无条件覆盖)=java/php/csharp/go/python/node 全清空+moon 的窗与 enabled 两腿。
processSurrogate/detail — 委托详情
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 委托 id |
data → 单条委托行:id, processName, operator(授权人), surrogate(被委托人), startTime, endTime, enabled, createTime, createUser, updateTime, updateUser (时间字段格式化 yyyy-MM-dd HH:mm:ss);id 不存在报 99999999(msg 委托记录不存在)。
processSurrogate/remove — 删除委托
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| ids | 二选一 | string[] | 批量删(前端 IdsParam 惯例,行内删除也发长度 1 的数组) |
| id | 二选一 | string | 单删(兼容形态) |
data → null
ids与id均缺失或为空数组时报99999999,不得返回成功(:PHP 曾把空串绑进DELETE ... WHERE id = '',删 0 行仍回code=0,前端提示"删除成功"而记录仍在)。 本条与processDefine/remove、processDesign/remove的批量语义同源,见 §7「批量入参」。
4.6 视图端点
必填参数缺失档(issues/235 子题② 立法,2026-10-15 owner 拍 a):本节各端点参数表里标「必填=是」的参数,未传、传 null、传空串或全空白 ⇒ 必须显式报错——对外 code=99999999,msg 逐字取 缺少<参数名>参数(基准=jeeflow-java JeeflowFacade 各视图方法对 isBlank 的显式分支,如 getLastByName 报「缺少processDefineName参数」;同构先例=主键类参数缺失档)。
严禁把参数缺失当"该条件不生效"通用放行:丢条件会返回别人的定义或整表数据,后果重于报错(本案出处=getLastByName/saveDeployedDefine 缺名时丢 t.name 条件,返回另一条流程的定义且 code=0,见 issues/179)。与 approvalRecord 口径② 不冲突——那条说的是参数给了、库里查不到 ⇒ 出空数组;本条说的是参数根本没给。
错误文案不属契约(audit8 R113 立法,2026-10-17 owner 拍):除条文明文逐字钉死的文案外,各动作失败时的 msg 不承诺跨栈逐字统一;契约只钉 code=99999999、必须拒绝的行为与内部错误码(内部码不进 msg)。因此"守卫失败 msg 八栈四派"(英文/中文、php≠java)按分布差记档,不再作为行为分叉立案;要逐字文案的条目必须在本卷条文里单独钉死(如 withdraw 20010009、decision 20010001)。
processDefine/getLastByName — 按名取最新定义
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processDefineName | 是 | string | 流程名 |
data → {id, name, displayName, type, state, version};不存在报错。
processInstance/highLight — 流程图高亮(含节点成员进度)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 实例 id |
data:
| 字段 | 类型 | 说明 |
|---|---|---|
| activeNodeNames | string[] | 活跃节点(进行中任务节点) |
| historyNodeNames | string[] | 历史节点(已完成 + 模型路径补全) |
| historyEdgeNames | string[] | 历史边(决策分支已求值过滤,未走的分支不高亮)。元素=边的 id,不是边的显示名 text.value——字段名叫 …EdgeNames 是历史遗留,八栈现读一致取边 id(issues/236 子题③ 钉现状,2026-10-15;moon 曾取 label,已由 issues/159 轮修平)。下文义务 2 所说的「边名不收/边名必须收」,判据对象同样是边 id |
| nodeProgress | object | 节点成员进度 {节点名: {members: [...], type?}} |
三条义务(issues/153 立法,2026-10-09 owner 拍;基准=jeeflow-java JeeflowFacade.highLight,与 mldong-boot2/3 内置版 recursionModel 同源)
historyNodeNames必须=「任务行去重」∪「从model.getStart()沿getOutputs()递归的模型可达补全」两条腿,缺任一腿即违反契约——只读任务表会漏掉不产生任务行的网关/结束节点。historyEdgeNames必须=补全路径上求值为 true 的决策出边:决策节点的带表达式出边要先求值,false 边的边名与目标节点都不收。仅当IExpressionEvaluator未注册时才允许整档判 false(降级档,须在实现处注明);「把带 expr 的边整条丢弃」和「不求值全量收集」两种实现都违反本条。 收录位置(issues/157 补,2026-10-10):边名的收录不得绑在"是否继续下钻"上——「遇活跃节点停止深入」只停递归,指向活跃节点那一跳的边名仍必须收(否则流程图上"通向当前待办的那根线"永远不亮,而实例确实走到了那里)。基准形状=javaJeeflowFacade.collectPath:711-718在源节点出边循环里先edges.add再判活跃;把边名当递归实参传(go/python/node 曾三栈同病灶)即违反本条。跨栈门禁L2-39档③ 判这一半,夹具=决策流且停在分支节点上(线性流与"分支已办完"的流都恒真,测不到这一跳)。 求值通道(issues/158 补,2026-10-10):引擎运行时给决策节点定支用的那条求值通道,与门面重算"走过哪些边"用的必须是同一条。宿主未注册IExpressionEvaluator而引擎自带内置求值的栈(csharpDefaultExpressionEvaluator+ExpressionEvaluatorOrDefault;rust 1.0.27 起jeeflow-core::default_evaluator+ServiceContext::expression_evaluator_or_default),内置件由两条腿共用,此时上面那条降级档在这些栈是结构性不可达、不是实现选择。反面形状=只把"未注册"在门面这一腿判 false、运行时却照内置定了支 ⇒ 同一个实例"运行时走了、门面说没走"(活栈读数:salvoL2-3947/1 缺e_dec_yes,同夹具 csharp 48/0,两栈的壳都没注册 SPI,差别只在引擎有没有把内置件做成共用出口)。 零命中档(issues/164 立法,2026-10-11 owner 拍 A,八栈对齐):决策节点遍历完全部出边仍无命中(带 expr 的边全判 false/判定变量缺失/零出边/自定义决策处理器未命中)⇒ 必须显式报错,文案逐字=javaWfErrEnum.NOT_FOUND_NEXT_NODE(20010001,decision节点无法确定下一步执行路线),门面出口99999999+该 msg。严禁静默停住(令牌不前进也不报错=办理人看到 code=0"成功"、实例挂在 state=10 且没有任何人的待办的僵尸实例)。八栈落地:java/php/csharp 一直报错派;python 1.8.42(issues/161 同语义先落);go/node 1.8.42、rust 1.0.28、moon 0.1.37 同批(2026-10-10 前 go/node/rust/moon 四栈是静默停住派)。⚠ "命中边但目标节点缺失"的落穿档不在本条内(基准侧行为各异,另案);判据必须用"两 expr 边全 false"的内联夹具——共享夹具 03 是>1000/<=1000恒有一条真,照不到这一档——并配"改回静默即红"的变异对照。 ⚠ 内置求值器不得靠不代入变量蒙方向:amount > 1000若不代入amount,字符串字典序"amount" > "1000"会返回 true,而同一条比较对amount <= 1000也为 true——两支一起"为真"只是被"先撞上列表里第一条 true 边"掩盖。关系运算(>>=<<=)要求两侧都是数字,非数字操作数判 false。 求值失败留痕(issues/201 立法,2026-10-14 owner 拍 C):IExpressionEvaluator自身抛异常(表达式坏、SPI 内部失败)时,实现必须落一条带原因的可诊断日志,至少含实例号、定义号、表达式、失败原因四件;对外仍code=0、降级面保留。遍历宽度不作契约——「异常穿出补全腿(该边之后的模型补全全丢)」与「该边按 false 处理、其余边继续遍历」两档都许可,八栈不承诺统一(现读 java/python/php/csharp 走前者,go/node/rust/moon 走后者)。禁止的形状是把抛错折成 false 之后一声不吭:它与「这条分支求值为假」在对外读数上完全同形,而 156/160 两个真分叉都曾藏进这一类静默通道。合法判假(求值返回 false、不抛)不得落这条日志——两档分不开,这条日志就变成每次高亮都刷屏。日志面在 HTTP 上不可观测,故不进08-compliance场景条,由各栈引擎级用例+进程 stdout 取证覆盖。 任务行佐证优先(issues/241 立法,2026-11-01):决策节点的带表达式出边先按表达式求值(上条口径);当求值结果非空、且其中没有任何目标有任务行佐证(活跃目标也算)时,以任务行为准——优先只收目标活跃的那条(些)边,其次只收目标已有任务行的边。「退回修改、重提直返」是这条的直接出处:来源节点之前的条件分支按 spec 04 不重算,而重提会把条件字段的新值落进实例变量,按当前值重放会把没走过的分支算进历史(issues/241 红样:historyEdgeNames缺实际走过的 e3、多出未走的 e4/e6)。表达式零命中(issues/164)与求值失败(上条)两档不适用本规则,降级面维持原样;因此"求值失败 ⇒ 数据面折 false + 落日志"的既有判据不变。⚠ 夹具设计:任务行快照实例变量的栈(现读 go/python/node/moon)在「任务行前置」夹具上会被"最老一条前置任务行"的求值入参偶然救活、测不出红;门禁夹具应把决策节点的入边来源放成 join(网关不产任务行),同一病状在八栈都能红。 ⚠ 判据侧同一条提醒:"这一栈本轮 48/0"不等于"这一栈的求值档已对齐",它只等于"这一栈的壳恰好注册了 SPI"(现读 fastapi/flask/django/laravel/goframe/gin/hertz/nestjs 九个壳各自注册,csharp/salvo 两个不注册);跨栈对齐要逐引擎读两条腿在同一配置档下的行为。按这条照出的 python 分叉另立案issues/160。nodeProgress.members[].name必须经IUserProvider解析,只有查不到才允许空串——SPI 未注册与「注册了但这一路没接」是两回事,后者违反契约。
nodeProgress 成员结构:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 用户 id |
| name | string | 用户姓名(IUserProvider SPI 解析,查不到为空串,前端降级显示 id) |
| done | boolean(仅命中) | 该成员已完成 |
| active | boolean(仅命中) | 该成员进行中(当前位) |
type:会签节点带 PARALLEL / SEQUENTIAL;动态参与人(无静态成员)节点不返回。
processInstance/approvalRecord — 审批记录
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 实例 id |
data → rows:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 任务行主键(雪花 id 必须字符串化,不得出 number——19 位会被 JS 截精度,同 issues/75/92 那族坑) |
| taskName/displayName | string | 节点 |
| taskType | int | 任务类型数字 code:0 主办 / 1 协办 / 2 记录(ProcessTaskTypeEnum.getCode(),issues/78 出口数字 code 口径;本行旧标 string 是文档错,issues/154 更正) |
| performType | int | 0 普通 / 1 会签 |
| taskState | int | 任务状态 |
| operator | string | 处理人 id |
| finishTime | string | 完成时间 |
| ext | object | 任务变量(含审批意见等;issues/124:变量唯一对外出口) |
五条口径(①—④=issues/154 立法,2026-10-09 owner 拍;⑤=issues/235 子题① 立法,2026-10-15 owner 拍 A;八引擎与 mldong 内置版同批并齐)
① 排序必须 ORDER BY id ASC——雪花 id 单调,同秒并发插入时比 create_time/update_time 确定; ② 实例 id 不存在时必须返回空数组,不得报「流程实例不存在」——视图端点不因 id 不存在报错; ③ 行内任务变量为空时 ext 必须出空对象 {},不得回落实例变量——回退会让"任务变量"与"实例变量"两种语义共用一个键,前端无法分辨办理人来源; ④ 出口列集合=上表九键,variable 原串不得再出现(issues/124)。 ⑤ 行集合=该实例的全部任务行,不按状态过滤——已办(20)、废弃(99)、进行中(10)一并不滤(issues/235 立法,钉现状:八引擎现读 8/8 全出)。审批记录是"这一单走过哪些人"的完整台账,转办行与废弃行正是使用者要看的;本文 §4.3 的 transfer 语义 4 与 removeTaskActor 语义 4 已各写「全部任务行(不按状态过滤)」,本条把同一口径补进 §4.6 条文——若此处改回"滤三态",会与那两条正面矛盾:转办后、办结前那条行仍是 DOING,恰被 notIn 滤掉,转办记录反而消失。⚠ mldong-boot2/3 内置版此处旧为滤三态(ProcessInstanceServiceImpl 的 notIn),按本条回改,跟改进度挂 audit8 队列 R94。
processInstance/getAssigneeTextData — 当前处理人(发起页"我的待处理"徽标)
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| id | 是 | string | 实例 id |
| includeNodeName | 否 | boolean | label 是否带节点名(默认 true) |
data → [{ "value": "用户id", "label": "节点显示名:用户id" }]
两条义务(issues/155 立法,2026-10-09 owner 拍)
① value 是参与者用户 id,本 action 是给人看的文案出口,不得用作节点定位键——LogicFlow 节点 id 是 taskName,与用户 id 无对应关系。要在画布上按节点回显办理人,唯一路径是 highLight.nodeProgress(按节点名索引,前端两处降级取数也救不了这一路)。 ② label 八栈严格 节点显示名:用户id(includeNodeName=false 时只出用户 id)。PHP 旧实现取 realName ?: actorId 出姓名属异类,并派为其余七栈形状;label 只当文案渲染,消费方不得对其做等值比较或据此反查用户。
processInstance/createCCInstance — 手动抄送
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processInstanceId | 是 | string | 实例 id |
| actorIds | 是 | string[] | 抄送人数组(非空) |
| operator | 是 | string | 操作人 |
data → null
processInstance/updateCCStatus — 抄送已读
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| processInstanceId | 是 | string | 实例 id |
| operator | 是 | string | 抄送人(标记自己已读) |
data → null
processInstance/ccList — 抄送我的
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| operator | 是 | string | 过滤"抄送我的"(cc.actor_id = operator,抄送行接收人;见 §2.5 口径表) |
| pageNum/pageSize/m_* | 否 | - | 分页过滤,默认值统一 pageNum=1 / pageSize=10(不传即此档,与其它分页 action 同口径;rust/moon 旧默认 20 已判分叉,issues/154④) |
data → 分页结构,rows 同 processInstance/page 行结构。
行形状三要件(issues/138 立法,基准=mldong-boot2 内置版,2026-09-29 owner 拍): ccList 的每一行必须来自 wf_process_instance(cc 表只当过滤/关联用), operator 必须是实例的 operator=流程发起人,行主键键名必须是 id(实例 id)。 ⇒ 三个常见错法都算违反契约:① 把 cc.actor_id(被抄送人,恒等于查询者)投成 operator; ② 把 cc.create_user(发起这次抄送的人)投成 operator; ③ 行主键出 processInstanceId 而没有 id。 "这条抄送是谁发给我的"要显示的话,取 cc 行的 create_user,不得占用 operator 这个键名。
写侧判重=幂等空操作(issues/141 G2 · 2026-09-29 owner 拍):同一 (实例, 被抄送人) 已存在 cc 行时, 再次抄送直接跳过、不新增行,并且不重置未读状态、不更新原行时间(owner 明确"不需要重置")—— 即"重复抄送同一个人"在数据面上是 no-op,不产生"再提醒一次"的语义。 ⇒ 判重义务放在写侧(建 cc 腿那三处入口:发起 f_ccActors、办理 tf_ccActors、手动 createCCInstance), 查询侧不引入 DISTINCT、保持各栈现状。 ⚠️ 已如实记账:库里历史遗留的重复 cc 行不做清理,而 rust/moon 两栈的 SQL 本来就带 DISTINCT, 所以同一批历史脏行在这两栈显示 1 行、其余六栈显示 2 行——这条差异 owner 拍为接受既成事实, 写侧判重只保证今后不再新增重复行。
5. 请求/响应示例
发起请假流程
json
// POST /wf/processInstance/startAndExecute
{
"processDefineId": "1864123456789012480",
"operator": "zhangwei",
"f_reason": "年假回乡",
"f_days": 5,
"f_startDate": "2026-08-10",
"f_nextNodeOperator": "lina",
"f_ccActors": ["chenjing"]
}json
// 200
{ "code": 0, "msg": "成功", "data": { "processInstanceId": "1864123456789012999" } }待办列表
json
// POST /wf/processTask/todoList
{ "operator": "lina", "pageNum": 1, "pageSize": 10 }json
// 200
{
"code": 0, "msg": "成功",
"data": {
"pageNum": 1, "pageSize": 10, "recordCount": 1, "totalPage": 1,
"rows": [{
"id": "1864123456789013111",
"processInstanceId": "1864123456789012999",
"taskName": "node_1", "displayName": "部门审批",
"taskType": "task", "performType": 0, "taskState": 10,
"operator": "lina", "formKey": null, "taskParentId": null,
"ext": { "tf_approvalComment": null, "f_reason": "年假回乡" },
"taskFormData": { "tf_approvalComment": null, "approvalComment": null },
"processDefineName": "leave", "processDefineDisplayName": "请假流程", "version": 0,
"createTime": "2026-08-06 09:30:00"
}]
}
}审批
json
// POST /wf/processTask/execute
{
"processTaskId": "1864123456789013111",
"operator": "lina",
"submitType": 1,
"tf_approvalComment": "同意,注意行程安全",
"tf_nextNodeOperator": "wangqiang",
"tf_ccActors": ["zhaomin"]
}json
// 200
{ "code": 0, "msg": "成功", "data": null }跳转(submitType=4)
json
// POST /wf/processTask/jumpAbleTaskNameList
{ "processInstanceId": "1864123456789012999" }
// → data: [{"label":"部门审批","value":"node_1"},{"label":"总经理审批","value":"node_2"}]
// POST /wf/processTask/execute
{ "processTaskId": "1864123456789013111", "operator": "lina", "submitType": 4, "taskName": "node_2" }错误示例
json
// HTTP 200,以 body code 判断业务成败
{ "code": 99999999, "msg": "流程定义不存在", "data": null }6. 集成方需要实现的 SPI
| SPI | 必选 | 说明 |
|---|---|---|
| IProcessRepository | 是 | 流程定义/实例/任务/抄送仓储(引擎提供 JDBC 默认实现) |
| IProcessExtRepository | 设计/委托 action 必选 | 设计稿、委托仓储 |
| IUserProvider | 否(建议) | 用户信息解析(nodeProgress 姓名、候选映射);未注册姓名降级为 id |
| IUserSearchProvider | candidatePage 用户搜索 | 用户分页搜索 + 单用户查询 |
| IActionPermissionProvider | 否(引擎内置默认) | action → 权限码映射 |
| metaTableReader | bizData | 业务数据读取(jeeflow-persist 提供) |
各语言注入位置:Java 构造器/ServiceContext;Go facade.New 参数/字段;Python/Node 构造参数。
7. 六语言行为对齐说明
| 关注点 | 约定 |
|---|---|
| id 出口 | 一律字符串(Node 全链路 string;Go/Python stringifyIDs;Java 集成层 ToStringSerializer;PHP 出口字符串化;Rust facade stringify_ids) |
| performType | 接受数字或字符串 '1'/'ALL'/'COUNTERSIGN' |
| 时间 | yyyy-MM-dd HH:mm:ss 字符串 |
| 分页 | {pageNum, pageSize, recordCount, totalPage, rows} |
| 批量入参 | 删除/启停类 action(processDefine/remove upAndDown、processDesign/remove、processSurrogate/remove)统一 {ids} 数组优先、单 {id} 兼容——前端按 mldong IdsParam 惯例只发 ids;ids/id 缺失或空数组一律报错,禁止静默成功 |
| 响应 | {code, msg, data} |
| 撤回 | 实例 + 全部进行中任务同步置 WITHDRAW(级联持久化) |
| 发起抄送 | f_ccActors;任务抄送 tf_ccActors |
| 动态参与人 | 未配置静态候选时,nodeProgress 不返回该节点(成员未知) |