---
docStatus: current
---

# 组织、成员与角色

从当前工作区组织目录定位成员、部门和用户组，按 Runtime 查询有效角色及角色成员。

业务流程先确定“由谁处理”，再决定通知和事项的去向。人员和组织关系应从工作区目录读取，业务代码保存稳定引用，不能维护一份靠姓名匹配的成员白名单。

## 可查询的能力

在目标 Runtime 中定位提供下列方法的工作区管理模块，并按[调用约定](/development/organization-capabilities/)读取其当前定义：

| 方法                                 | 用途                                       |
| ---------------------------------- | ---------------------------------------- |
| `listWorkspaceMembers`             | 查询当前工作区成员；当前合同无业务参数，传 `{}`。              |
| `getWorkspaceOrganizationOverview` | 查询成员、部门、用户组及成员组织关系；当前合同无业务参数。            |
| `listWorkspaceRoles`               | 分页查询指定 Runtime 的工作区自建角色。                 |
| `listBundleAuthorizationResources` | 按 Runtime、来源环境、单个 Bundle 和资源类型查询角色或权限定义。 |
| `getEffectiveUserRoles`            | 查询用户通过个人、部门和用户组获得的有效角色。                  |
| `listEffectiveRoleMembers`         | 分页查询某个完整业务角色身份对应的平台用户。                   |

## 按姓名找同事

1. 调用 `listWorkspaceMembers({})`，读取成员的真实用户 ID、名称和用于辨认的组织信息。
2. 根据用户给出的姓名、部门等信息定位。重名时继续确认；没有匹配时停止发送，不选择列表第一人。
3. 保存所选成员的稳定用户 ID，并在调用时遵循各方法的类型要求。
4. 查询该成员的[联系方式](/development/organization-capabilities/contacts/)，或把其身份交给[人工事项](/development/organization-capabilities/issues/)。

成员存在只说明其属于工作区，不代表其拥有某个应用权限，也不代表已绑定企业微信。

## 按角色找处理人

角色查询需要明确工作区与 Application Runtime。当前角色方法的 `scope` 包含合同版本、工作区、Runtime 和用户域；字段及版本必须读取当前方法定义，不从另一环境复制。
先从已安装 Bundle 目录取得来源身份，再查询目标 `ROLE`；工作区自建角色使用独立的工作区角色目录。

- Bundle 角色用完整资源身份区分，两个 Bundle 的同名角色不是同一个角色。
- 工作区角色使用该工作区的角色身份，不能构造一个虚假的 Bundle 资源地址。
- 查询有效成员时使用完整角色对象，并处理分页；不要仅查直接用户绑定而遗漏部门和用户组授权。
- 角色成员名单用于选择业务接收人；服务端仍须校验实际操作权限。

角色和权限的作者定义、版本与安装流程分别见[角色开发](/development/bundle-development/role-template-development/)及[权限开发](/development/bundle-development/permission-definition-development/)。
客户成员、部门、用户组与角色之间的实际分配属于目标工作区，不随业务 Bundle 打包。

## 验证

测试至少覆盖一个重名或多候选场景、一个没有联系方式的成员，以及一个通过部门或用户组取得角色的成员。
对名单零匹配、多匹配和权限不足分别处理，不把任何一种情况替换成默认管理员。