审批节点「处理人 Value」应改为记录 lookup(现查 metadata 端点→只能手填);附 approver value 语义核实 + queue 未实现

[baozhoutao]

问题

流程设计器里,审批节点(approval)的 Approvers → Value 目前是个 datalist 组合框,数据源接的是
client.list(type) → GET /api/v1/meta/:type(metadata 注册表端点)。

但 user / team / department / queue 这些处理人是数据记录(躺在 sys_user / sys_team /
sys_business_unit 等系统对象里),不在 metadata 注册表里。结果候选恒为空,控件退化成
纯手填——作者只能手动敲 userid / 团队 id,失去了"选择"能力。

设计器本应按 spec 里已声明的 xRef(approval.zod.ts 的 value.meta.xRef,把每个 type 映射到
user/position/team/… picker)出记录选择器,现实现图省事接到了 metadata 端点。

实测证据(console preview-gallery,无后端)

在 flow 设计器加一个 approval 节点,把 Type 切成 User:

• Value <input> 实测 list = null、候选数 = 0 → 就是个纯文本框;
• 抓到它发的请求:GET /api/v1/meta/user(注册表端点,列不出用户记录)。

Type=Team / Department / Queue 同理(都查 /meta/:type,恒空)。

---

三点核实结论(以引擎为准,不是 zod 描述)

数据来源:packages/plugins/plugin-approvals/src/approval-service.ts 的
resolveApproverSpec() + 各 expand*Users()。

1. 是否全单选 —— 是

引擎里每个 approver 行的 value 一律是单个标量(全程 String(a.value),没有哪种类型在一行里吃
数组)。多个审批人 = approvers 数组里多行。所以设计器控件应为「每行单选」。

注:field 类型运行时能展开成多人,但那是记录字段里存了多个 id(csvSplit(record[value])),
不是设计器里在一行里多选出来的。

2. Value 各类型到底存什么(引擎确认)

Type	引擎如何使用 value	存值
user	applyOooDelegation(String(value))(L442)	sys_user id
team	find('sys_team_member', { team_id: value })(L486)	sys_team id
department	find('sys_business_unit', { id: value })(L502)	sys_business_unit id(注意不是 sys_department)
position	find('sys_user_position', { position: value })(L550)	sys_position name(机器名),非 id
org_membership_level	展开 owner/admin/member 三档	枚举串,非记录
manager	record[value] ?? record.owner_id(L470)	字段名(可选,通常留空)
field	record[value] 取用户 id/ids	触发对象字段名
queue	引擎里没有 queue 分支 → 落到 ['queue:'+value] 死值	运行时未实现

3. 是否只有 position 存 name —— 不完全是

• 在「要查记录」的类型里:user/team/department 存 id,只有 position 存 name —— 这句成立。
• 但「非 id 值」不止 position:org_membership_level 是枚举、field/manager 是字段名 ——
  它们根本不是记录,不该套记录 lookup。
• 另有 queue 在引擎里未实现(resolveApproverSpec 无 queue 分支,只有 BFS 里一个同名局部变量),
  选了也不会解析到任何人。

---

建议修复

A. 设计器(objectui packages/app-shell)—— 主体改动

复用 @object-ui/fields 的 LookupField(单选,useAdapter() 提供 DataSource),按类型分组渲染
Approvers 的 Value:

• 记录 lookup(单选):
  • user → sys_user,存 id
  • team → sys_team,存 id
  • department → sys_business_unit,存 id
  • position → sys_position,存 name(非 id)
• 不做记录 lookup:
  • org_membership_level → 严格 Select(owner/admin/member 闭合枚举,顺手防 sales_manager 这类脏值)
  • field → 维持对象字段选择器(现状可用)
  • manager → Value 框禁用 + 提示「由提交人上级自动解析」(或作为可选字段名)
  • queue → 暂保留手填 + 提示「运行时未支持」(见 B)

涉及:

• packages/app-shell/src/views/metadata-admin/inspectors/FlowReferenceField.tsx
  (KIND_TO_META_TYPE / useMetadataListOptions 现在把这些类型接到 /meta/:type)
• packages/app-shell/src/views/metadata-admin/inspectors/flow-node-config.ts(approvers 列定义)

B. 引擎(framework plugin-approvals)—— queue 决策

resolveApproverSpec 缺 queue 分支。要么补上 queue 展开逻辑,要么把 queue 从
approval.zod.ts 的 approver type 枚举里移除/标注 deprecated,别让设计器提供一个运行时不生效的选项。

---

风险 / 待确认

• 设计器过去是纯 metadata、不查数据;接 lookup 后要在设计器里查 sys_user 等记录(需当前用户有读权限)。
• 预览画廊无后端,这几类仍会退化成手填(可接受,离线态)。
• position 存 name、department→sys_business_unit 这两处映射需重点测。

验收

• 设计器审批节点:User/Team/Department 能弹记录选择器并选中,提交后 value 是对应 id;
• Position 选中后 value 是 sys_position.name;
• org_membership_level 为严格三选一;manager 无输入框;queue 处理见 B;
• 每种类型改动后在真机(带后端)逐一验证解析到正确的人。

[os-zhuang]

已按建议开发完成,两个 PR(均为 draft,CI 进行中):

• 框架侧 feat(spec+approvals+lint): approver value bindings, retire queue authoring (#3508) #3536 —— spec 契约 + 引擎告警 + lint 门禁
• 设计器侧 feat(app-shell): approver values become record lookups (framework #3508) objectui#2834 —— 记录 lookup 主体改动

关于「审批流是元数据、只能开发商开发」这个前提

调研后确认:该前提在本平台已不成立,不存在架构矛盾。flow 在元数据注册表里就声明了 allowOrgOverride: true, allowRuntimeCreate: true(packages/spec/src/kernel/metadata-plugin.zod.ts:638),sys_metadata 是 DB 后备的覆盖层,LayeredRepository 让文件层(开发商源码)与 DB 层(管理员定制)叠加,REST 有完整写路径 PUT /api/v1/meta/:type/:name?mode=draft + publish/rollback/history(ADR-0005 / ADR-0027 / objectui ADR-0034)。Studio 就是给管理员用的。

这与 Salesforce 一致:Approval Process 是 Metadata(可版本化、可打包部署),但管理员在 Setup 里运行时全量编辑。「元数据」定义的是生命周期,不是编辑者身份。 所以本 issue 要补的只是「绑人员的最后一公里 UX」,不需要放开任何权限模型。

A. 设计器(objectui#2834)

按类型分流,KIND_TO_RECORD_LOOKUP 镜像 spec 新增的 APPROVER_VALUE_BINDINGS:

Type	控件	存值
user	记录 lookup(sys_user,PeoplePicker)	id
team	记录 lookup(sys_team)	id
department	记录 lookup(sys_business_unit)	id
position	记录 lookup(sys_position)	name
org_membership_level	严格 Select	枚举
manager	禁用 + 自动解析提示	—
field	对象字段选择器(现状)	字段名
queue	下拉移除,存量行保留 + 警告	—

保留「永不困住作者」:记录 lookup 带手工输入逃生口,无 adapter(离线预览)整体退回文本框。

顺带修了 LookupField 的一个既有缺陷:id_field 非主键时(正是 position 存 name 的情形)回填走 findOne(主键) 永远查不到,已存值显示为空 —— 改为按该列 $filter 回填。

另外把 Type 下拉调成间接绑定优先(manager/position/department/team 在前,user 垫底):绑定具体某个人在跨环境迁移和人员离职时最脆弱,这是主流平台的一致引导。

B. queue —— 选择「深度弃用」而非补实现

理由三条:

1. 平台没有 ownership-queue 实体(无 sys_queue、无成员表),补展开逻辑无所依附;
2. plugin-sharing 已有先例:sys-sharing-rule.object.ts:145 明确「queue was removed: declared-but-unenforced」,共享侧已退役,审批侧照做才口径一致;
3. queue-as-approver 的正确语义是「组内任一成员认领后处理」(参照 Salesforce queue approver / ServiceNow group approval),需要 queue 实体 + 成员表 + claim 动作 + 审批槽位改造,应与 sharing 的 queue 需求一起立项设计,不宜在审批里单造。

落地方式(不破坏存量):queue 仍可 parse、存量 flow 照常加载渲染 → 经 xEnumDeprecated 发布使设计器不再提供 → 引擎解析到 queue 时 logger.warn → 新增 lint 规则 approval-approver-type-unsupported 在发布时点名。与 role 的弃用机制完全一致。

顺带核实的语义(已写入 spec 常量并被测试锁定)

issue 里那张表全部属实,现在它们不再只是注释,而是 APPROVER_VALUE_BINDINGS 里可被编译器与测试保护的契约 —— satisfies 保证新增 ApproverType 成员却不声明 value 来源会编译失败,设计器契约再也不会悄悄落后于枚举。这也是这次错接 /meta 端点的根因所在:原来 xRef 只说了 picker 名字,没说数据源。

（合并 main 时与 #3447 的 expression approver 有重叠,已解冲突并把 expression 纳入绑定表,两边行为均保留。）

待办

• 真机(带后端)逐类型验证解析到正确的人 —— 尤其 position 存 name、department→sys_business_unit 两处映射
• 后续可考虑:把数据源标注(source: 'data' | 'meta' + 目标对象 + valueField)直接进 xRef,让设计器完全数据驱动而非维护镜像常量;以及部署时校验 flow 内嵌的 sys_user id 在目标环境是否存在

---

Generated by Claude Code