发布范围与资源边界
阅读指引：本篇是《开放平台服务端 API 指南》的第 9 部分。接口基础地址、通用约定与各接口请求限制，请先阅读《服务端 API 概览》。
12. 应用发布范围与资源边界
发布范围不是一个新的 OAuth Scope。它是管理员配置的应用级统一边界，同时决定哪些用户能发现、打开和授权应用，以及应用可以读取或触达哪些用户和组织。应用端不能通过请求参数扩大该边界。
12.1 与能力 Scope 的关系
| 模型 | 回答的问题 | 资源 ID | 谁配置 |
|---|---|---|---|
| 能力 Scope | 应用能做什么，例如读取组织或发送用户消息 | 不包含 | 管理员授权；用户授权型能力还需用户同意 |
| 应用发布范围 | 谁能使用应用；应用能读取或触达谁、哪些组织 | 包含用户或组织目标 | 管理员 |
授权范围由平台配置应用不能在业务请求或 OAuth scope 中附加用户、组织资源列表来扩大授权。需要调整范围时请联系平台管理员。群接口另以有效群绑定为授权依据。
12.2 两个范围维度
| 维度 | 全量目标 | 部分目标 | 作用 |
|---|---|---|---|
用户 user |
target_id=0：全体有效 IM 用户 |
一个或多个正整数用户 ID | 用户可见性和应用可触达用户边界 |
组织 org_node |
target_id=0：全部有效组织 |
一个或多个正整数组织节点 ID | 组织读取边界；同时把有效组织成员并入有效用户集合 |
可读组织为管理员选择的组织子树并集（或全部有效组织）；可使用应用的用户为指定有效用户与这些组织的有效成员并集（或全部有效 IM 用户）。两个维度独立配置。
- 用户和组织是两个可同时配置的维度；没有
user:0时，指定用户与组织成员取并集。 - 配置
user:0时所有有效 IM 用户都可使用应用，但组织配置仍独立限制应用能读取的组织节点。 - 一个正数组织目标始终包含节点自身、当前子孙和未来新增子孙。应用请求不能改为仅覆盖当前节点。
- 管理员选择“全部”后，同维度的部分目标被删除；以后取消全部不会恢复旧部分项。
- 管理员同时选择父、子组织时只保留父节点；以后删除父节点不会自动恢复曾被覆盖的子节点。
12.3 对开发者调用的影响
| 场景 | 平台行为 | 应用处理 |
|---|---|---|
| 用户不在有效用户集合 | 客户端不展示应用；打开检查拒绝；OAuth2 authorize、code、用户 Token 及受保护用户接口拒绝 | 提示应用不可用，不循环授权或刷新旧 Token |
| 用户后来被移出范围 | 已有用户 Token 的受保护调用会重新检查并失败 | 清理本地用户会话；不要把 Token 签发成功视为永久授权 |
| 读取范围外组织或用户 | 返回资源不可见/不存在，避免泄露真实存在性 | 停止读取该目标；重新执行目录同步 |
| 批量向用户发消息 | 范围外目标进入无效/失败明细，不导致合法目标一起失败 | 逐项处理 invalid_recipients 和 failed_recipients |
向 all 发送 |
当前只有发布范围包含 user:0 且具备 message:send:all 才允许 |
不能用“部分用户 + 部分组织”模拟或推断 all |
| 发布范围变化 | 组织同步 Token 改变 | 按第 13 节重新构建本地目录快照 |
应用无法直接读取管理员的原始配置外部应用只通过具体接口的授权结果和组织 sync_token 感知有效边界。请以接口返回的可见资源为准，不要推测管理员的原始配置。