unis-oa/docs/complex-process-design.md

18 KiB
Raw Permalink Blame History

烤机流程「采购付款联合审批(全能力验收)」设计说明

这份流程的目的不是"业务上合理",而是一次性把平台所有能力都踩一遍:所有字段类型、 所有分支条件写法、所有自动带出字段、所有审批人来源、所有环节类型、所有协作开关与协同动作。 配套的自动化验收脚本是 backend/tests/mega_flow.py, 跑法 python3 backend/tests/mega_flow.py,跑完自己把流程、表单、实例清干净。

0. 用真实同步组织,不新建任何人

烤机直接跑在统一身份同步过来的那棵组织树上(紫光汇智 + 8 个部门 + 100 名同步人员), 不新建用户、部门、角色、分组,脚本结尾会拿组织数据指纹复核确实一点没动过。

夹具是从组织里"挑"出来的,挑不齐就直接退出,不拿半套夹具跑出假结论:

夹具 现在命中谁 为什么需要它
根部门(无负责人、无上级) 紫光汇智 让"部门负责人 / 上级部门负责人 / 直属上级"一定解析为空
中层部门(有负责人、上级没有) 软件开发部 → 袁云熙 本级能解析到人、上一级解析为空
底层部门(另一个负责人) 定制 → 丁睿 两级负责人都能解析到不同的人
在职岗位角色 总经理(成员是内置超管) 唯一能在运行时派出去活的角色
成员全失效的角色 / 分组 财务、部门负责人 / 研发全员 证明失效成员不会变成幽灵审批人

运行时只有一个身份能登录:同步账号的口令归统一身份平台托管,本地设不了, PUT /org/persons 对 source=hub 也明确拒绝设密码。所以:

  • 每个环节的审批人都写成"解析后确实落到内置超管"的形式——要么是本人 (发起人 / 上一环节处理人 / 指定人员 / 指定身份 / 在职角色 / 表单字段 / 找人脚本), 要么故意选一个当前解析不出人的来源,靠"解析不到时交给发起人"兜底。
  • 18 种来源的真实解析口径交给审批人预览接口逐条核对:拿真实部门、真实负责人、 真实人员的 asIdentity 去试算,一个不落(见第 4 节)。
  • 全程只有内置超管拿到过待办:脚本结束前会核对这批实例上出现过的处理人身份集合, 必须恰好等于内置超管一个人。真实员工的待办箱一条都没进。

1. 表单:26 种字段类型全覆盖

类型 字段 用途
text title 标题,兼作工作标题来源
textarea reason 申请事由,用于验证"提交时补丁写回"
number days 分支条件(数字比较)
number / money amount budget 分支条件(金额比较)+ money 类型
date applyDate 分支条件(days_between 取它和今天的差)
datetime / time planDate applyTime 日期时间、时刻
daterange tripRange 分支条件(区间长度)
mobile / email / idcard / url / address phone mail idcard homepage address 格式类录入
select category 一级分支(下拉值)
radio urgency 一级分支(单选值)
checkbox skills 二级分支(多选包含)
switch vip 一级分支(布尔)
rate score 二级分支(评分阈值,max=5)
dept dept 二级分支(部门路径 contains)
user owner 审批人来源「表单字段」的数据源
attachment / image files photos 随单上传、按对象数组落库
hidden items 明细数组,split 环节按它逐条派发
auto f_creator … f_handler 12 个系统值全用
divider / description sep tip 排版(不可必填)

12 个系统值里 8 个在发起时落库并被断言;activityName / handler 随环节变化,不落库, 由前端按当前环节现算。另有明细表单(含 2 个系统值)与子流程表单,一共 3 张表单。

2. 流程图:12 种环节类型全覆盖

flowchart LR
  B([开始]) --> A1[填写申请<br/>发起人]
  A1 --> C1{一级分支<br/>VIP/金额/类别}
  C1 -->|VIP| A2[A2 脚本找人]
  C1 -->|≥1万| A3[A3 全部会签 all]
  C1 -->|货物+紧急| A4[A4 部门与上级]
  C1 -->|其他类别| A5[A5 分组与身份]
  C1 -->|默认| A6[A6 指定部门负责人]
  A2 --> P1
  A3 --> P1
  A4 --> P1
  A5 --> P1
  A6 --> P1
  P1{{并行}} --> B1[B1 上级审批<br/>prevLeader]
  P1 --> B2[B2 上一部门<br/>prevunit]
  P1 --> B5[B5 公司负责人<br/>creatorParentUnitManager]
  B1 --> C2
  B2 --> C2
  B5 --> C2
  C2{二级分支<br/>8 种写法} -->|高分| B3[B3 连续上级]
  C2 -->|默认| B4[B4 表单字段找人]
  B3 --> M1((并行汇总))
  B4 --> M1
  M1 --> C4{有明细?}
  C4 -->|有| SP[/拆分 items/]
  SP --> A7[A7 逐条办理<br/>明细表单]
  C4 -->|无| C3{金额分流}
  C3 -->|<5000| B6[B6 部门直属]
  C3 -->|默认| M2
  A7 --> M2((分流汇总))
  B6 --> M2
  M2 --> SC[脚本计算]
  SC --> IV[接口调用]
  IV --> DL[延时缓冲]
  DL --> SC2[脚本回写]
  SC2 --> EM[法务核验子流程]
  EM --> C5{终止判定}
  C5 -->|forceStop| CX([作废])
  C5 -->|默认| E([结束<br/>办结抄送])

子流程「烤机流程-法务核验子流程」独立发布,embed 环节发起它并挂起父流程, 把主表单数据一并带过去(子流程的分支就是靠主表单里的 risk 走不同支线), 办结后自动回主流程继续。

3. 覆盖矩阵

  • 环节类型(12/12):begin、manual、choice、parallel、merge、split、script、invoke、delay、embed、end、cancel。
  • 一级分支(5/5 全部跑到):bool(vip)、float(amount) >= 10000、 category == 'goods' and urgency in ('urgent','flash')、category == 'other'、默认路由。
  • 二级分支(8/8 全部跑到):评分阈值、部门路径 contains、标题 startswith、 区间长度 len(...)、日期差 days_between(applyDate, today())、多选包含、 数字比较 days > 30、默认路由。同一条支线只认第一条命中的路由, 所以"归口复核"命中后"专项复核"被遮蔽本身就是对分支顺序的验证。
  • 审批人来源(18/18 全部出现在设计里,解析口径逐条核对):identity、person、role、 group、unit(含 containsSub 两种口径)、post、creator、prev、prevunit、form、 creatorLeader、creatorLeaderChain、creatorUnitManager、creatorParentUnitManager、 creatorTeamLeader、prevLeader、prevUnitManager、unitManager,外加环节上的 taskScript。
  • 会签模式:mode=any(或签,一人办结其余自动通过)、mode=all(全部会签, 一人办完流程停在原地等非)——用并行加签在同一环节上补出第二份待办来验证。
  • 协作开关:allowGoBack / allowAddTask / allowTransfer / allowPress / allowCc / allowShare / allowComment 各自在某个环节上被关闭一次,逐个验证接口确实拒绝。
  • 自动抄送:arrive(本环节在办的人不重复抄)、complete(办结后抄给经办人并要求处理)、 结束环节的办结抄送,三种时机都跑到。
  • 协同动作:抄送(需处理 / 无需处理 / 驼峰与下划线两种请求体)、分享、退回(step / jump 两种配置 + 路由级 goBack)、加签(before×serial 回转、after×together 并签)、 转办(保留来源身份)、催办(计数 + 独立通知)、撤回已办、终止。
  • 实例设计:R-A 标准通道走完全程(含撤回/催办/转办/加签回转/无明细/子流程/办结抄送); R-B 战略通道 + jump 退回 + 明细分派 + 子流程上级确认支线;R-C 作废支线 + 协作开关全关; R-D 全部会签 + 路由级退回 + 终止;R-E 明细被写成字符串时拆分环节必须报错; R-F 补齐剩下的分支条件;R-G 终止父单时必须把还活着的嵌入子流程一起带走。 六种结局办结 / 作废 / 终止都出现。

4. 审批人预览矩阵(设计期就能看出会派给谁)

运行时只能派给内置超管,"解析口径"这件事就全靠 POST /process/approvers/preview 配真实 asIdentity 来核对。脚本里逐条断言了 33 条,口径包括:

  • 认人只认登录账号(工号就是账号;person 来源额外还认姓名);存进去的也是一律登录账号,见 person-reference-design.md。
  • unit 在 containsSub=false 时只出直属成员,勾上才带子部门的人。
  • 成员全失效的角色与分组不造假审批人(历史上这里会把对不上账号的串当活人发出去, 流程静默卡在环节上);认不出的部门与岗位原样报 unknown。
  • 上级类来源在同步组织里的真实表现:leader_id 全为空时按"所在部门负责人"兜底; 本级没设负责人时"组长"来源不向上兜底;上级部门没负责人时解析为空并给出原因。
  • form / creator / prev / prevunit 明确标为"待运行时确定";不传试算身份时要求先选一个。
  • 找人脚本(taskScript)现在也能预览:脚本返回的登录账号能解析到人, 查无此人时报 unknown 并提示运行时会走兜底。

5. 这轮烤机改掉的与留下的

烤机过程中改掉的引擎问题(都补了断言):

  1. 全部会签 mode=all 不生效:任何一个人办结都会把同环节其他人的待办一起结掉,流程直接推进。 现在只有或签(any)才清扫同级待办,会签要等所有人各自表态。
  2. "办结后"的自动抄送永远发不出去:判断"本环节在手处理人"时把已经办完的人也算了进去, 于是给刚办结的人补意见那条规则一条也发不出来。现在只算在途待办。
  3. 随单附件撞主键报 500:发起页先上传拿到附件对象、再随单带上,引擎又按同一个 id 插一条。 现在改成认领那条已存在的记录。
  4. 审批人预览不算找人脚本:taskScript 传进去被丢掉,设计器里写脚本找人只能等流程跑起来 才知道找不找得到人。现在预览会执行脚本并把解析结果与原因一起返回。
  5. 工作详情接口整条 500:GET /job/{job} 组装响应时引用了一个没定义的 forms 变量, 待办点开、待阅点开、我发起的点开全部报错。现在把表单定义补回去,并加了断言 (工作详情必须带回流程用到的表单)。
  6. 流程定义删掉之后历史单据被锁死:以前删流程只删定义与表单占用,归档单、已办记录、 待阅还留在库里,点开就是 500——等于把人的历史删了。现在 GET /job 遇到"定义已不存在 的归档单"照样返回单据、流转历史与审批记录,只是没有环节图与表单可用。
  7. 同一条延时能唤起多次,一次派生出好几个子流程:调度器 wake_delays 把整张在途表扫完才提交, 认领窗口等于整个扫描周期。多起一个后端进程(或者多开一个 worker)就会有两个调度器同时看到 同一条到期 token,各派发一遍——实测一张单子被同一条延时唤起 3 次、开出 3 个嵌入子流程。 现在改成按单加锁认领(FOR UPDATE SKIP LOCKED)+ 一张单一个事务,锁不到就跳过。 单独复现脚本:python3 backend/tests/delay_race.py(8 路并发打调度器,改回旧写法它就是 8 份)。
  8. 父单走了,嵌入子流程留在原地等人办:终止/作废/办结父单时只处理父单自己的待办, 子流程实例照旧在途,界面上就是一堆"父单已归档、子单还在"的孤儿待办。 现在父单收尾时把还活着的嵌入子流程一并终止(递归到孙流程),验收脚本 R-G 专盯这一点。
  9. 撤回已办会再多派出一条支线:撤回只把本人那个环节的任务拉回来,它当时已经自动带出去的 下游环节(脚本 / 接口 / 延时 / 嵌入子流程)还挂在令牌上。重办一次就等于把那段路又走一遍, 表现为"一条主线开出两个嵌入子流程"。现在撤回按环节图的可达范围把自己带出去的支线整段收回 (并行里的兄弟分支不动),并把已经开出的子流程一并终止;R-A 里"先办结再撤回"那段专门盯它。
  10. 实例归档之后待办还留在列表里:待办行是跟着实例走的,但走到终态时只结了"当前环节"那份, 并行支线 / 加签回转留下的待办会变成指向已消失实例的幽灵行——列表里看得到、点开没内容、 永远清不掉。现在实例归档时把它名下残留的待办一并清掉。
  11. 挂在子流程上的父单显示停在上一个自动环节:调用子流程时只登记了挂起令牌,没刷当前环节, 在途列表里父单看着像卡在"延时缓冲"那一步。现在挂起即把当前环节刷成调用环节。

顺带说明一个故意没做的点:删除流程定义不级联删除归档实例与待阅。历史单据是审计凭据, 静默连带删除比留下孤儿更危险;库里现在就有 52 个已删流程的 170 张归档单,全部照常可查可打开。 平台也没有对外提供删归档实例的接口,管理员能做的到"终止"为止。

还没修的,留在这里备查:

  • 表单校验只在浏览器里做:必填、手机号/邮箱/证件号格式这些规则只存在于前端, POST /job 与 POST /task/{id}/execute 会把缺必填、格式不对的数据直接写库。
  • 活动脚本可以写死循环:while True: pass、for i in range(10**18) 都能通过校验, 并且是在请求线程里 exec,一旦写上就把这个 worker 占死。建议要么禁掉 while 与 range, 要么给脚本执行加步数上限。
  • "提交时指定下一步处理人"不生效:next_identities 一路传到 work.variables["next:<环节id>"] 就没人再读了,环节派发只看环节自己的配置。前端目前也没有放这个选择器,等于半成品接口。
  • 环节与路由的主键是全局的:两个流程里的环节/路由只要 id 相同就会撞上,设计器复制流程时 必须换 id。烤机脚本靠每次跑换一个 6 位命名空间来绕开这一点。
  • 单号只在自己流程里唯一:计数器按「流程 + 周期」递增(oa_serial_number), 所以主单和它派生的子流程实例可能拿到同一个单号,混合列表里靠单号认单会认错。 要全局唯一得改计数口径,属于产品口径问题,这里只记录。
  • 内置超管还挂在已删除的旧演示组织下,所以"发起人部门"这类系统值会带出一个 组织树里已经查不到的部门名。数据卫生问题,不影响流转。
  • 6 套老回归(form_design / e2e_flow / permissions / collab_flow / approver_targets / field_types) 现在整套跑不起来,两处卡点叠在一起:它们还按 admin/admin123 登录(内置超管已改名 localadmin,账号名记在数据库 system.admin_account 里),而 Hub 登录开着之后非应急账号一律要先过 Hub 验证码; 就算登进来,它们依赖的优尼森演示组织(zhangsan 等人)也已经被删掉,demo_data 只在库内 一个用户都没有时才重建。要恢复它们,得先把这批脚本改成拿真实同步组织或自建沙箱组织当夹具。

6. 想在前端自己点一遍:--keep 留下的演示数据

验收用的 R-A..R-F 最后都走到终态,看的是引擎;想在界面上点按钮,就跑:

python3 backend/tests/mega_flow.py --keep

它跑完不收尾,把一批停在半路的实例留在库里。用内置超管登录(账号名以数据库里的 system.admin_account 为准,本机是 localadmin),待办 / 待阅 / 草稿箱里就是这些现场:

单标题 停在 点开能点什么
前端演示-待提交(26 种字段全填) 填写申请 26 种字段的真实渲染(含真实上传的附件与图片)、改单、存草稿、提交
前端演示-战略通道(可退回/可抄送) A2脚本找人 同意、退回到填写申请、手动抄送;另有一条到达抄送待阅
前端演示-全部会签(两份待办) A3全部会签 两份在途待办,只办一份流程不动;办理时限
前端演示-协作开关全关 A5分组与身份 加签/转办/抄送/分享/批注/催办按钮全部应为禁用
前端演示-并行会审(三条支线) B1 / B2 / B5 三条支线各一份待办,只到齐一条不推进
前端演示-按明细分派(三条明细) A7逐条办理 三份明细待办,各带独立分支令牌与明细专属表单
前端演示-催办/待阅/前置加签 A6指定部门负责人 已催办一次的痕迹 + 一条「需处理」待阅
前端演示-法务核验子流程 法务核验 父单挂在调用环节等子流程,父子单互跳
前端演示-草稿(未发起) 草稿箱 草稿直接打开发起页

另外还留着:嵌入子流程独立实例(停在核验环节,父单挂在调用环节上)、按到达 / 办结 / 提交后 三种时机铺出来的抄送待阅(其中一部分标了「需处理」,必须填意见才算办完)、满页的已办与我发起的。

再生的口径:

  • 再跑一次 --keep = 重建(先 reap_leftovers 把上次的烤机流程、表单、演示草稿清掉,再铺新的)。
  • 跑不带 --keep = 全清(烤机流程与子流程、烤机专用表单、演示草稿一起删掉,在途实例先终止)。
  • 演示数据的识别标记:流程与表单名以 烤机 开头,实例标题以 前端演示 / R- 开头, 手删也按这三个前缀找就行。
  • 演示单据只挂在内置超管一个身份上:待办、待阅、草稿全在 localadmin 名下, 同步过来的真实员工一条都收不到。
  • 只想留烤机、把别的设计数据(别人的流程 / 表单 / 草稿 / 悬空快照)清掉,用 backend/scripts/prune_design.py:默认干跑列清单, 加 --apply 才真删,--keep 前缀 换保留标记(可重复)。被删流程的在途实例走正常终止归档, 不硬删;历史归档单据(oa_work_completed)不属于设计数据,这个脚本一概不动。