目录与群数据同步

阅读指引：本篇说明两类可靠同步：组织目录同步（部门与成员）与群应用同步（应用的群与群成员）。两者的共同原则是：Webhook 只负责加速发现变化，接口返回的同步水位才是判断是否需要同步的可靠依据。接口细节见《组织目录同步》《群应用与群数据同步》。

组织目录同步

组织接口使用应用 Token，需要 contact:organization:read，并始终受发布范围约束。组织变更事件是尽量推送（可能丢失），应用必须用同步状态接口弥补事件丢失，不能每次调用都直接做全量同步。

核心接口

完整同步算法

sync-state → 建立临时快照 → departments 全量读取
  → 逐部门分页读 department-users → 按需读 user-detail
  → sync-complete → 原子替换正式快照

1. 调用 sync-state，need_sync=true 时记录响应 Token 为「进行中 Token」，不要立刻覆盖「上次完成 Token」。
2. 创建新的临时表或带批次号的临时快照，不要边同步边删线上旧数据。
3. 不带 id 调用 departments 一次获取全量组织（响应已含完整可见子树，不要再按返回 ID 逐层递归调用）；全量读取期间请求带 X-Matrix-Directory-Sync-Token 头。
4. 对每个部门分页读取直接任职用户，按业务需要补充 user-detail。
5. 任一读取返回 HTTP 409 / 170703，说明同步过程中目录或发布范围又变化：丢弃整个临时批次，重新从 sync-state 开始。
6. 全部读取成功后调用 sync-complete，仅当返回 completed=true 才在本地事务中用临时快照替换正式快照，并保存该 Token。

sync_token 是经过认证的不透明字符串，只保存并原样回传（sync-state 支持 If-None-Match 传上次 Token，无变化返回 304 无 body）。sync-complete 不锁定后续目录变化，完成同步后仍须继续轮询。

群应用同步

群主或管理员把应用添加进群后，应用获得 group:app 能力对应的群数据访问，可以同步该群与成员，并以应用身份向该群发消息。

核心接口

要点：

• groups/changes 使用 cursor/limit 游标分页（limit 默认 50、最大 200）：首次省略 cursor，之后原样使用响应中的不透明游标；游标不能解析、修改、跨应用或跨群复用。
• 群成员读取同样用不透明游标做全量或增量获取；推荐先 groups/changes 发现变化，再对有变化的群刷新基本信息与成员。
• 群关系被移除（应用被移出群、应用下架等）后，立即停止对该群的读取和发送；应用被重新添加不会自动恢复旧的同步游标。
• sign_key 重置会使原群同步游标失效，需要重新全量同步群与成员。
• 群资料的读取以 group:app 与有效群绑定为授权依据，返回的是绑定群的成员，不按用户或组织发布范围逐个裁剪。

Webhook 事件的配合

组织目录与群应用的变化事件（organization.*、group.*）通过 Webhook 推送，用于加速发现变化：

• 收到事件后，把同步任务落库并异步执行，不要把 Webhook 当作最终状态；
• 同步时始终以 sync-state（组织）和 groups/changes（群）的返回为准；
• 事件可能丢失或重复，幂等与水位校验不可省略。