组织用户查找（工作流节点）功能设计文档

1. 功能目标

在审批、通知等工作流中，根据某个业务人员的组织身份，动态查找：

1. 最近的直属上级；
2. 最近组织层级中拥有指定系统角色的用户。

节点支持多种查找基准、身份直属上级、组织逐级向上查找和兜底用户，并输出可直接用于审批人的用户列表。

2. 关键术语

术语	说明
用户	可登录系统并作为审批人或通知接收人的系统账号。
员工	组织中的人员，可以绑定系统用户，也可能暂未绑定。
身份	员工在某个组织中的任职关系。同一员工可以有多个身份。
基准人	本次查找以谁为组织起点，最终必须解析为一条身份。
默认身份	员工或用户优先使用的主身份；没有主身份时使用排序最前的启用身份。
身份直属上级	在身份上直接指定的系统用户，优先级高于组织负责人。
组织负责人	组织机构上指定的负责人员工。
兜底用户	正常查找不能得到结果时使用的最终处理人。

3. 身份直属上级

身份增加可选字段“直属上级”，用于选择一个系统用户。

规则如下：

• 每条身份最多指定一个直属上级。
• 不允许把本人设置为直属上级。
• 被选用户删除后，该字段自动变为空。
• 有效的身份直属上级优先级最高，命中后不再查找组织负责人。

直属上级查找的固定优先级为：身份直属上级 → 组织负责人 → 兜底用户。

4. 节点配置

节点名称为“组织用户查找”。

配置项	必填规则	说明
查找方式	必填	直属上级或角色查找。
查找基准	必填	决定从谁的组织身份开始查找，可以选择当前身份、员工、用户。
角色类别	角色模式必填	角色/岗位/群组等。
角色选择	角色模式必填	选择类别后，“角色选择”只显示该类别下的选项。
排除基准人	仅角色模式显示	默认开启。
兜底用户	可选	支持固定用户、用户变量和用户筛选条件，可组合多个。

5. 基准身份解析

基准类型	解析规则
当前身份	使用工作流启动时保存的当前身份，运行期间切换身份不改变本次起点。
员工	使用员工的默认身份。
用户	先找到用户对应的员工，再使用员工的默认身份。

默认身份规则：

1. 优先选择启用的主身份。
2. 没有主身份时，选择排序最前的启用身份。
3. 没有启用身份时，基准无效并进入兜底。

基准值只接受单个记录或单个主键。空值、数组、多值、缺少主键或类型不匹配均视为基准无效，直接进入兜底并记录原因。

6. 通用查找流程

1. 校验节点配置。未选择查找方式、或者角色模式未选择角色、所选角色已不存在时，节点直接失败，不使用兜底。
2. 解析基准身份。若无法从基准中确定一条存在且启用的身份，则不进行组织查找，直接进入兜底并记录具体原因。
3. 从基准身份直接所属的本级组织开始查找，不从根机构开始。
4. 当前层命中有效用户后立即停止；未命中时进入直接上级组织。
5. 禁用组织不参与人员匹配，但仍可沿上级关系继续向上。
6. 到达根组织仍未命中时进入兜底。
7. 组织不存在、组织关系循环或向上查找超过 100 层时直接失败，不使用兜底。

7. 直属上级查找规则

7.1 身份直属上级

• 有效用户：立即返回。
• 未配置、配置本人或用户不存在：继续查找组织负责人。

直属上级模式最多返回一个用户。

7.2 组织负责人

身份直属上级未命中时，从本级组织逐级向上查找。

组织负责人以组织机构上的“负责人”字段为准。

当前组织的负责人状态	处理方式
未配置负责人	继续查找上级组织。
负责人就是基准人	跳过当前层，继续查找上级组织。
负责人对应员工不存在或已失效	停止向上，立即进入兜底。
负责人员工未绑定系统用户	停止向上，立即进入兜底。
负责人绑定的系统用户不存在	停止向上，立即进入兜底。
负责人对应有效系统用户	返回该用户并停止查找。

只有“未配置负责人”或“负责人就是基准人”可以继续向上。已经配置了另一名负责人但该负责人不可用时，不得绕过该负责人选择更高层负责人。

8. 角色查找规则

节点从基准人所在的本级组织开始，逐级向上寻找拥有目标角色的人员。每一级只查找直接属于该组织的成员，不包含其下级组织人员。候选人必须满足以下条件：

• 身份处于启用状态；
• 员工状态有效；
• 已绑定有效的系统用户；
• 该用户拥有所选系统角色。

“排除基准人”默认开启。开启后，基准人不会出现在查找结果中；关闭后，基准人也可以作为目标角色人员返回。

如果当前组织层级存在符合条件的人员，则返回人员并结束查找，不再查找或合并更高层级人员。如果当前层没有符合条件的人员，则继续查找上级组织。同一用户只返回一次（去重）。

到达根组织仍未命中时，以“未找到角色用户”进入兜底。角色结果采用或签、会签、投票还是顺序审批，由下游审批节点决定。

9. 兜底规则

以下情况进入兜底：

• 基准身份无效；
• 组织负责人无法转换为有效系统用户；
• 到达根组织仍未找到直属负责人或角色用户。

兜底用户支持固定用户、用户变量和筛选条件。系统自动去除空值、重复用户和不存在的用户，但不排除基准人。

• 兜底得到有效用户：节点成功。
• 兜底仍为空：节点失败并阻止下游执行，同时保留最初的兜底原因。

9.1 兜底原因

使用兜底成功和兜底为空失败时都必须记录原因。原因码设计如下：

原因码	含义
SOURCE_CURRENT_IDENTITY_MISSING	没有可用的当前身份快照。
SOURCE_IDENTITY_NOT_FOUND	指定身份不存在。
SOURCE_IDENTITY_DISABLED	指定身份已禁用。
SOURCE_EMPLOYEE_NOT_FOUND	指定员工不存在。
SOURCE_EMPLOYEE_IDENTITY_NOT_FOUND	指定员工没有启用身份。
SOURCE_USER_NOT_FOUND	指定用户不存在。
SOURCE_USER_EMPLOYEE_NOT_FOUND	指定用户没有对应员工。
SOURCE_USER_IDENTITY_NOT_FOUND	用户对应员工没有启用身份。
OWNER_EMPLOYEE_NOT_FOUND	组织负责人指向的员工不存在。
OWNER_EMPLOYEE_INVALID	组织负责人对应员工已失效。
OWNER_USER_UNBOUND	组织负责人对应员工未绑定系统用户。
OWNER_USER_NOT_FOUND	组织负责人绑定的系统用户不存在。
MANAGER_NOT_FOUND	到达根组织仍未找到直属负责人。
ROLE_USER_NOT_FOUND	到达根组织仍未找到目标角色用户。

10. 节点输出

节点成功时固定返回以下全部输出：

输出字段	内容
userIds	命中用户的系统主键列表，可直接用于审批人或通知接收人。
users	命中用户记录列表，至少包含用户主键和昵称。
matchedOrganization	正常查找命中的组织；使用兜底时为空。
matchedBy	命中方式。
fallbackReason	兜底原因；正常命中时为空。

matchedBy 可取：

值	含义
identitySupervisor	身份直属上级。
organizationOwner	组织负责人。
role	系统角色用户。
fallback	兜底用户。

输出约束：

• 正常命中时，fallbackReason 必须为空。
• 使用兜底时，matchedOrganization 必须为空，fallbackReason 必须有值。
• 是否使用兜底通过 matchedBy 是否为 fallback 判断。

11. 失败与数据时点

以下情况直接失败且不使用兜底：

• 节点配置校验未通过；
• 组织关系循环或向上查找超过 100 层。

兜底仍为空时也失败，并阻止下游审批或通知节点执行。失败信息必须保留最初的 fallbackReason，以及可获得基准身份、起始组织、查找方式和角色信息。

数据时点规则：

• 当前身份以工作流发起时的快照为准，但节点执行时需要重新确认身份仍存在且启用。
• 组织负责人、员工状态、用户绑定和系统角色按节点执行时的最新数据判断。
• 节点名称、配置、提示、原因和错误信息需要同时支持中文与英文。

12. AI 开发约束

1. 不得改变本文规定的查找优先级、继续向上条件、兜底条件和失败条件。
2. 角色选择器不得增加角色分类过滤，角色判断必须使用系统唯一标识。
3. 兜底用户不得排除基准人。
4. 组织负责人未绑定系统用户时必须立即兜底，不得继续向上。
5. 所有成功结果必须完整提供五个输出字段。
6. 进入兜底时必须使用准确原因码；兜底为空时必须保留原始原因。
7. 发现本文未覆盖且会改变业务结果的情况时，应先向开发人员确认，不得自行推断。
8. 插件要求：在现有plugin-paas-organization插件内实现