组织机构

组织机构插件使用文档

本文面向系统管理员，介绍如何使用组织机构插件维护集团组织树、员工岗位与人员身份，并将组织关系用于业务数据归属和角色数据权限。

文中的系统截图使用英文界面。应用菜单名称、业务字段名称和示例数据由应用自行配置，因此截图中可能保留少量中文业务内容。

1. 插件用途

组织机构插件用于解决以下管理场景：

建立集团、公司、项目部、部门等多级组织结构。
将员工关联到一个或多个组织节点，并为每个任职关系分配岗位。
允许员工在多个人员身份之间切换，使当前机构、部门和岗位随身份变化。
在业务记录创建时自动写入所属机构和所属部门。
按本机构、本机构及下级、本部门、本部门及下级控制业务数据范围。

2. 使用前准备

先启用数据字典插件，再启用组织机构插件。
确认当前管理员可以访问应用的 Data sources 和 Users & Permissions 设置页面。
确认数据字典中存在 OrganizationType。插件会提供以下内置类型：

分类	编码	显示名称
机构	`Organization`	机构
机构子类型	`Group`	集团
机构子类型	`Company`	公司
机构子类型	`Project`	项目部
部门	`Department`	部门
其他	`Collaboration`	外协队伍

Department 类型的节点会向上查找所属机构；其他类型的节点作为机构节点处理。不要随意修改内置编码，显示名称可以按业务语言维护。

3. 核心概念

概念	说明
组织机构	树形节点，可以表示集团、公司、项目部、部门或外协队伍。
员工	人员主数据，可关联平台用户，并保存工号、联系方式等资料。
岗位	基于角色数据的岗位角色，通过岗位标记进入岗位选择范围。
身份	员工、组织节点、所属机构、岗位和用户之间的一条任职关系。
当前身份	当前请求使用的身份，决定当前机构、当前部门和岗位上下文。
所属机构/部门字段	自动记录业务数据创建时所在机构和部门的系统信息字段。

一个员工可以拥有多个身份，但同一时间只有一个当前身份；第一个身份会自动成为主身份。将某身份设为负责人时，该组织节点的负责人会同步更新。

4. 创建组织结构

示例应用的入口为 管理人员 > 组织机构。实际入口取决于应用菜单配置。

组织机构树形列表

4.1 创建顶级机构

进入组织机构页面。
点击 Add new。
填写以下必填项：
- name：机构名称。
- organizationType：机构类型，例如集团或公司。
- code：同级范围内使用的机构编码。
按需设置：
- enabled：是否启用，默认启用。
- owner：负责人。
- order：同级节点排序。
点击 Submit。

新增顶级机构

系统会根据父子关系自动计算 fullCode、level 和所属机构，不需要管理员手工维护这些值。

4.2 创建下级机构或部门

在父节点的操作列点击 新建下级。
填写名称、机构类型和编码。
如果创建部门，选择编码为 Department 的机构类型。
点击 Submit。

新增下级机构

继续对下级节点执行相同操作，即可形成集团、公司、项目、部门等多级组织树。

4.3 日常维护

View/查看：查看节点详情和关联信息。
Edit/编辑：修改名称、类型、负责人、排序或启用状态。
新建下级：在当前节点下创建子节点。
Delete/删除：仅在确认下级节点和业务引用均已处理后使用。

5. 维护员工

示例应用的入口为 管理人员 > 员工信息。

在左侧组织树中选择员工所属的组织节点。
点击员工列表上方的新增操作。示例应用显示为 添加管理人员，其他应用可能显示 Add new。
选择 organizations，并填写 Name、phone、idCard 等必填信息。
按需补充工号、人员状态、入职日期、邮箱、职务、职级、职称、学历、专业和附件。
关联平台 user。只有关联用户后，该员工才能在登录请求中获得组织身份上下文。
点击 Submit。

新增员工

员工与多个组织节点建立关系时，系统会为每个关系保存一条身份记录。第一条身份自动成为主身份。

6. 分配岗位并形成身份

岗位来自平台角色集合，并通过岗位标记参与身份的岗位选择。开始分配前，请确认系统中已经存在可选岗位角色；岗位角色的维护入口以当前应用的管理员页面配置为准。

进入员工信息页面，并选择员工所在的组织节点。
在目标员工行点击 设置岗位。
在 post 中选择岗位。
点击 Submit。

为员工分配岗位

身份包含以下关键信息：

当前选择的组织节点作为部门。
该节点向上解析得到的机构作为所属机构。
员工关联用户作为身份用户。
选中的岗位角色作为身份岗位。
主身份、负责人、启用状态和当前身份等控制标记。

7. 切换当前身份

当一个用户关联的员工拥有两个及以上身份，并且系统不是“仅使用合并角色”模式时，用户中心会显示 Switch identity。

点击页面右上角的用户图标。
打开 Switch identity。
从组织路径列表中选择目标身份。
页面自动刷新后，新的机构、部门和岗位上下文立即生效。

身份名称按组织祖先路径显示，例如“集团/公司/项目部/部门”，便于同一员工区分多个任职关系。

8. 为业务表添加记录归属字段

组织数据范围依赖业务表中的 Owned organization 和 Owned department。需要进行组织权限控制的业务表应同时添加这两个字段。

进入 Data sources。
找到 Main 数据源，点击 Configure。
找到目标业务表，点击 Configure fields。
点击 Add field。
在 System info 分组中依次添加：
- Owned organization
- Owned department

添加后，字段列表中会出现 ownedOrg 和 ownedDept，字段类型均为 belongsTo。

业务表中的组织和部门字段

新建业务记录时，插件会按照当前身份自动写入：

Owned organization：当前身份所属的机构节点。
Owned department：当前身份选择的组织节点，即当前部门。

这两个字段默认按只读关联字段使用。为了确保权限结果完整，应先添加字段，再开始录入需要组织隔离的业务数据。

9. 配置角色数据范围

进入 Users & Permissions > Roles & Permissions。
选择需要配置的角色。
打开 Permissions > Data sources。
在 Main 数据源行点击 Configure。
在 General action permissions 或 Action permissions 中启用所需操作。
为 View、Edit、Delete、Export 等已有记录操作选择数据范围。

配置组织数据范围

插件提供四种组织数据范围：

英文选项	中文含义	匹配规则
`Own organization records`	本机构数据	所属机构与当前机构完全一致。
`Own organization and sub records`	本机构及下级数据	所属机构完整编码以当前机构完整编码开头。
`Own department records`	本部门数据	所属部门与当前部门完全一致。
`Own department and sub records`	本部门及下级数据	所属部门完整编码以当前部门完整编码开头。

“及下级”范围包含当前节点本身。数据范围应分别按操作配置，例如可以允许查看本机构及下级数据，但只允许编辑本部门数据。

10. 使用当前机构和当前部门变量

插件会在支持变量表达式的筛选器和数据范围配置中提供：

Current organization：当前身份所属机构的完整编码。
Current department：当前身份所选组织节点的完整编码。

标准的四种组织数据范围已经封装了常用匹配规则。只有需要组合其他业务条件时，才在自定义筛选条件中选择当前机构或当前部门变量。

11. 验证配置结果

建议管理员按以下顺序验收：

为测试员工关联平台用户，并在两个不同组织节点下建立身份。
为两个身份分别分配岗位，确认其中一个为当前身份。
使用该用户登录，在用户中心切换到第一个身份。
新建一条带 Owned organization、Owned department 字段的业务记录。
查看记录详情，确认两个归属字段与当前身份一致。
切换到第二个身份并刷新页面。
分别验证本机构、本机构及下级、本部门、本部门及下级的数据可见范围。
验证 View、Edit、Delete、Export 等操作是否遵循各自配置的数据范围。

12. 管理员检查清单

数据字典插件已经先于组织机构插件启用。
OrganizationType 的内置编码保持有效。
组织树中的部门节点使用 Department 类型。
员工已经关联平台用户。
员工至少拥有一个组织身份，岗位角色可正常选择。
需要权限隔离的业务表同时包含 ownedOrg 和 ownedDept。
角色的每项操作都按业务要求设置数据范围。
多身份用户已经验证身份切换和页面刷新后的权限结果。

13. 工作流节点 - 组织用户查找

“组织用户查找”是工作流中的一个处理节点，用于根据某个人员的组织身份，自动找到后续流程所需的用户。常见用途包括：

查找发起人的直属上级作为审批人；
查找距离业务人员最近的、具有指定角色的用户；
查找距离业务人员最近的、具有指定岗位的用户；
在正常查找不到人员时，将流程交给预先设置的兜底用户。

节点支持“直属上级”和“角色查找”两种方式。两种方式都会先确定查找基准人员及其组织身份，再从该身份所在的部门开始，按照组织层级逐级向上查找。

查找基准

“查找基准”决定从谁的组织身份开始查找，支持以下三类选择。

查找基准	适用场景	身份确定方式
当前身份	按工作流触发人的当前组织身份查找	使用工作流触发时记录的当前身份
员工/员工ID	按某位员工查找	使用该员工的默认身份
用户/用户ID	按某个用户查找	先找到该用户对应的员工，再使用员工的默认身份

当前身份

“当前身份”适合“查找发起人的上级”“按当前操作人的部门查找审批人”等场景。

当前身份只有在工作流由用户操作触发，并且触发用户具有有效组织身份时才可用。例如，由表单提交、人工操作或审批动作触发的工作流，通常可以取得当前身份；没有明确触发用户的定时任务或后台任务，无法取得当前身份。

工作流开始时会记录触发人的当前身份。即使触发人在流程运行期间切换了身份，本次流程仍按开始时记录的身份查找，避免同一次流程的组织起点发生变化。

员工和用户

员工和用户适合按业务记录中的人员查找，例如：

按请假单中的“申请员工”查找上级；
按客户记录中的“负责人用户”查找所在部门的指定岗位人员；
按上一节点得到的员工或用户继续查找。

员工或用户可能具有多个组织身份。此时节点使用其默认身份：优先使用已启用的主身份；如果没有主身份，则按身份的排序选择第一条启用身份。不会使用该人员最近一次登录时切换到的身份。

查找基准一次只能选择一名员工或一个用户。多选结果、空值或不完整的人员数据不能作为有效查找基准。

共同的组织层级规则

无论选择哪种查找方式，都遵循以下组织层级规则：

从查找基准身份实际所在的部门开始。
先在当前部门查找；当前部门未命中时，再查找父级组织。
按“当前部门 → 父级 → 更高层级”的顺序逐级向上。
到达根组织仍未命中时，使用兜底用户。
已禁用的组织不参与当前层的组织负责人或角色候选匹配，但查找仍可继续进入其父级组织。
如果组织层级关系缺失、形成循环或存在其他无法继续判断的异常，节点会直接失败，不使用兜底用户掩盖组织结构问题。

直属上级查找

“直属上级”方式最多返回一名用户，适合单人审批、逐级上报等场景。

查找顺序

直属上级按以下优先级查找：

身份中指定的直属上级：如果查找基准身份已经维护了直属上级，优先使用该人员。
当前部门负责人：身份未指定直属上级，或直属上级误指向本人时，查找当前部门的负责人。
上级组织负责人：当前部门未设置负责人，或负责人就是查找基准本人时，沿父级组织继续向上查找。
兜底用户：到达根组织仍未找到时，使用兜底用户。

可以将其理解为：

身份直属上级 → 本部门负责人 → 上级组织负责人 → 兜底用户

排除本人

正常查找不会把查找基准本人作为其自己的直属上级：

身份中的直属上级误指向本人时，忽略该设置，继续查找组织负责人；
当前部门负责人就是本人时，跳过本人，继续查找父级组织；
更高层级的负责人仍是本人时，继续向上查找。

该排除规则只适用于正常查找。若流程设计者明确把本人配置为兜底用户，节点仍会按兜底配置返回本人。

已配置的负责人不可用时

身份直属上级或组织负责人一旦明确指向了其他人员，该配置就代表业务上已经指定了处理人。如果该人员出现以下情况，节点会立即使用兜底用户，而不会绕过此人继续向更高层级查找：

员工记录不存在或已失效；
员工没有绑定系统用户；
已绑定的系统用户不存在。

这样可以避免在人员数据异常时，把流程错误地提交给更高层级的负责人。

角色查找

“角色查找”用于查找最近组织层级中，具有指定角色或岗位的全部有效用户。适合会签、多人审批、通知群体等场景。

角色类别

配置角色查找时，需要先选择角色类别：

角色：选择系统中的普通角色；
岗位：选择被归类为岗位的角色。

选择类别后，“角色选择”只显示该类别下的选项。切换角色类别时，需要重新选择角色或岗位。

排除基准人

“排除基准人”仅在角色查找中显示，默认开启。

开启：不会把查找基准本人作为正常查找结果；当前层排除后无人命中时继续向上。
关闭：如果查找基准本人具有目标角色或岗位，可以出现在结果中。

兜底用户不受该选项限制。

兜底用户

兜底用户用于在正常查找无法得到用户时承接流程。可以配置固定用户，也可以使用工作流变量或用户筛选条件；允许设置一个或多个来源。

以下情况会进入兜底：

无法取得当前身份；
员工或用户为空、无效或不符合单人输入要求；
指定员工或用户不存在；
查找基准人员没有启用的组织身份；
已指定的直属上级或组织负责人已失效、未绑定用户或用户不存在；
遍历到根组织仍未找到负责人；
遍历到根组织仍未找到具有目标角色或岗位的用户。

使用兜底时不再应用“排除基准人”规则，因此兜底用户可以是查找基准本人。

如果多个兜底配置得到同一个用户，结果会自动去重。如果所有兜底配置最终仍得不到有效用户，节点执行失败，后续节点不会继续执行。

查找结果的使用

节点完成后提供以下结果：

结果	含义	常见用途
用户 ID	查找到的一个或多个系统用户标识	作为审批人、抄送人或通知接收人
用户	查找到的用户信息	在消息内容、条件判断或后续处理中使用
命中组织机构	正常查找最终命中的组织	用于审计、流程记录或通知说明；使用兜底时为空
命中方式	身份直属上级、组织负责人、角色/岗位匹配、兜底	用于判断本次结果的来源
兜底原因	触发兜底的原因	用于异常分支、流程审计和数据排查；正常命中时为空

后续节点如果需要选择人员，通常使用“用户 ID”。例如，在审批节点的审批人配置中选择：

组织用户查找节点 → 用户 ID

角色查找可能返回多名用户，因此还需要在审批节点中设置合适的多人审批方式。直属上级查找正常情况下只返回一名用户。

兜底原因对照表

code	解释
`SOURCE_CURRENT_IDENTITY_MISSING`	当前身份缺失。工作流没有明确的触发用户，或触发用户没有可用的当前组织身份。
`SOURCE_VALUE_INVALID`	基准变量值无效。员工或用户变量为空、返回多条记录、缺少有效标识，或变量类型不符合要求。
`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`	基准用户对应的员工没有启用的组织身份。
`IDENTITY_SUPERVISOR_EMPLOYEE_NOT_FOUND`	基准身份中配置的直属上级员工不存在。
`IDENTITY_SUPERVISOR_EMPLOYEE_INVALID`	基准身份中配置的直属上级员工已失效。
`IDENTITY_SUPERVISOR_USER_UNBOUND`	直属上级员工未绑定系统用户，无法参与工作流。
`IDENTITY_SUPERVISOR_USER_NOT_FOUND`	直属上级员工绑定的系统用户不存在。
`OWNER_EMPLOYEE_NOT_FOUND`	组织机构中配置的负责人员工不存在。
`OWNER_EMPLOYEE_INVALID`	组织机构中配置的负责人员工已失效。
`OWNER_USER_UNBOUND`	组织负责人员工未绑定系统用户，无法参与工作流。
`OWNER_USER_NOT_FOUND`	组织负责人员工绑定的系统用户不存在。
`MANAGER_NOT_FOUND`	沿组织层级查找到根节点后，仍未找到可用的直属上级或组织负责人。
`ROLE_USER_NOT_FOUND`	沿组织层级查找到根节点后，仍未找到具有指定角色或岗位的有效用户。

失败原因对照表

code	解释
`ORG_USER_LOOKUP_INVALID_CONFIG`	节点配置无效。查找方式或查找基准类型不受支持。
`ORG_USER_LOOKUP_INVALID_ROLE`	角色查找配置无效。未选择角色或岗位，或已选择的角色或岗位不存在。
`ORG_USER_LOOKUP_INVALID_TREE`	组织层级数据异常。基准身份所在组织不存在，或组织关系存在父级缺失、循环、层级过深等问题。
`ORG_USER_LOOKUP_EMPTY`	节点已进入兜底处理，但兜底配置最终没有得到任何有效用户。