同步用户与业务群

这组接口由客户业务服务签名调用。用户主数据、项目成员和业务权限继续以客户系统为准，IM 维护通信所需的投影与群关系。

用户同步

POST /external/user/sync 新增或更新一个用户。以下只展示请求体，签名 Header 见 Server API 鉴权。

{
  "userId": 90001,
  "account": "demo-user-a",
  "nickname": "测试用户 A",
  "status": "enabled"
}

字段	规则
userId	稳定的 64 位整数用户标识
account	客户账号、工号或登录名称，按业务需要提供
nickname	通信中的展示资料
avatar	可选，使用当前部署允许的头像对象或自有地址
status	新建用户需明确状态；普通资料同步不解除已有封禁

既有用户更新时只传需要修改的资料。批量初始化可使用配套批量同步能力，但应分批处理失败结果，不要把一次请求超时解释为所有用户都没有创建。

服务端还提供用户停用接口。停用会影响后续访问，不等于物理删除用户及聊天历史；业务系统需同步处理登录权限和仍存续的业务凭据。

项目群同步

POST /external/group/project/sync 按调用方与 projectId 建立稳定映射。创建成功后保存返回的群标识与会话标识，后续使用同一项目标识更新，不在每次打开项目时新建群。

{
  "projectId": "project-demo-001",
  "groupName": "项目协作群",
  "ownerUserId": 90001,
  "memberUserIds": [90002, 90003],
  "adminUserIds": [90002],
  "status": "enabled"
}

示例用户需先同步且处于允许使用的状态。成员与管理员数据由客户业务服务根据真实项目权限生成，不能直接接受浏览器随意传入的用户列表。

更新与补偿

建议将用户资料与项目成员变更放入宿主已有的业务事件流程：先提交业务事实，再调用 IM；临时失败保留待重试记录，以同一幂等键重试对应动作。

项目群的目标成员应作为一组确定的快照校验。并发变更时，宿主需要保证变更顺序，避免旧快照晚到覆盖新成员关系。

业务权限与群治理

组织架构与业务角色由客户系统管理，群管理员和后台管理员分别按 IM 管理规则授权。

客户业务服务通过授权接口管理群资料、禁言和管理员，由 IM 服务维护群状态。客户端群操作见群组与成员管理，登录链路见 IM Session。