开发指南组织级基础能力
组织、成员与角色
从当前工作区组织目录定位成员、部门和用户组，按 Runtime 查询有效角色及角色成员。
业务流程先确定“由谁处理”，再决定通知和事项的去向。人员和组织关系应从工作区目录读取，业务代码保存稳定引用，不能维护一份靠姓名匹配的成员白名单。
可查询的能力
在目标 Runtime 中定位提供下列方法的工作区管理模块，并按调用约定读取其当前定义：
| 方法 | 用途 |
|---|---|
listWorkspaceMembers | 查询当前工作区成员；当前合同无业务参数，传 {}。 |
getWorkspaceOrganizationOverview | 查询成员、部门、用户组及成员组织关系；当前合同无业务参数。 |
listWorkspaceRoles | 分页查询指定 Runtime 的工作区自建角色。 |
listBundleAuthorizationResources | 按 Runtime、来源环境、单个 Bundle 和资源类型查询角色或权限定义。 |
getEffectiveUserRoles | 查询用户通过个人、部门和用户组获得的有效角色。 |
listEffectiveRoleMembers | 分页查询某个完整业务角色身份对应的平台用户。 |
按姓名找同事
- 调用
listWorkspaceMembers({})，读取成员的真实用户 ID、名称和用于辨认的组织信息。 - 根据用户给出的姓名、部门等信息定位。重名时继续确认；没有匹配时停止发送，不选择列表第一人。
- 保存所选成员的稳定用户 ID，并在调用时遵循各方法的类型要求。
- 查询该成员的联系方式，或把其身份交给人工事项。
成员存在只说明其属于工作区，不代表其拥有某个应用权限，也不代表已绑定企业微信。
按角色找处理人
角色查询需要明确工作区与 Application Runtime。当前角色方法的 scope 包含合同版本、工作区、Runtime 和用户域；字段及版本必须读取当前方法定义，不从另一环境复制。
先从已安装 Bundle 目录取得来源身份，再查询目标 ROLE；工作区自建角色使用独立的工作区角色目录。
- Bundle 角色用完整资源身份区分，两个 Bundle 的同名角色不是同一个角色。
- 工作区角色使用该工作区的角色身份，不能构造一个虚假的 Bundle 资源地址。
- 查询有效成员时使用完整角色对象，并处理分页；不要仅查直接用户绑定而遗漏部门和用户组授权。
- 角色成员名单用于选择业务接收人；服务端仍须校验实际操作权限。
角色和权限的作者定义、版本与安装流程分别见角色开发及权限开发。 客户成员、部门、用户组与角色之间的实际分配属于目标工作区，不随业务 Bundle 打包。
验证
测试至少覆盖一个重名或多候选场景、一个没有联系方式的成员，以及一个通过部门或用户组取得角色的成员。 对名单零匹配、多匹配和权限不足分别处理，不把任何一种情况替换成默认管理员。