自建好友 / 群业务接入 Server Core

本文说明：如果你要自己实现好友、群、组织、黑名单、禁言等业务系统，应该如何与 flare-im-core 服务端集成。

结论

flare-im-core 不负责好友关系和群目录的业务规则。它负责 IM 主干：长连接、消息、会话、成员投影、seq、有序同步和事件。

自建业务系统推荐通过一个 Business Bridge 接入 IM Core：

App / Client SDK
      │
      ├── 好友、群资料、申请、角色、组织关系 ──► 你的业务 API
      │
      └── 消息、会话、同步、已读 ───────────────► flare-im-core SDK

你的业务服务 ──► Business Bridge ──► flare-im-core 管理 / 命令面
                   │
                   ├── PreSend Hook：发消息前做好友/群权限校验
                   ├── PostSend Hook：发信事实回流业务系统
                   └── Conversation/Member Hook：同步会话与成员变化

责任边界

接入点 1：登录与租户身份

客户端登录 IM 时携带业务系统签发的 Token。Token 至少应能解析出：

客户端侧只需要把 Token 交给 SDK：

await client.login({
  userId: currentUser.id,
  token: accessToken,
})

生产环境中，Token 由你的账号系统签发；IM 网关只验证身份和租户，不把好友/群权限写死在 Token 里。

接入点 2：发消息前校验

好友、群成员、禁言、黑名单等会影响“能不能发消息”的规则，应接 PreSend Hook。

Hook operation：

flare.hook.v1.pre_send

推荐校验：

返回策略：

allow = true   -> Core 继续分配 seq 并进入消息主链
allow = false  -> 业务拒绝，返回稳定 deny_reason_code
Hook 超时      -> 权限类建议 fail-fast；纯审计类不要放在 PreSend

注意：PreSend Hook 不应写消息表、不应分配 seq，也不应执行长耗时外部调用。

接入点 3：会话与成员映射

好友或群创建成功后，你的业务服务需要把业务关系映射到 IM 会话。

推荐由 Business Bridge 暴露自己的业务接口，例如：

POST /im-bridge/conversations/ensure

请求示例：

{
  "tenantId": "0",
  "businessType": "group",
  "businessId": "group_123",
  "conversationType": "group",
  "operatorUserId": "u_001",
  "participantUserIds": ["u_001", "u_002", "u_003"],
  "idempotencyKey": "group_123:init"
}

Bridge 内部再调用 flare-im-core 的管理面或命令面完成：

1. 确保会话存在：businessType + businessId -> conversation_id
2. 同步参与者投影：成员列表、角色、禁言状态、participant_version
3. 发布或触发会话成员变更事件
4. 将 conversation_id 回写到你的业务库映射表

映射表建议：

接入点 4：客户端读模型

客户端页面不要只靠 IM 会话列表展示好友/群完整资料。

推荐组合：

客户端拿到会话里的 conversation_id 或业务映射字段后，再向你的业务 API 查询展示资料。这样 IM Core 保持业务中立，业务系统保持资料权威。

常见流程

单聊发消息

1. App 从你的好友服务选择好友。
2. 业务服务或 Bridge 确保单聊会话存在。
3. Client SDK 使用 conversation_id 发消息。
4. PreSend Hook 校验好友关系和黑名单。
5. Core 分配 seq、落库、下发并支持离线同步。
6. PostSend Hook 将发信事实回流给审计、风控或业务统计。

创建群并发消息

1. 你的群服务创建群，写入群成员和角色。
2. 群服务调用 Business Bridge ensure conversation。
3. Bridge 同步 IM 会话参与者投影。
4. Client SDK 拉取会话或收到会话变更事件。
5. 用户发消息时，PreSend Hook 校验群成员、禁言和群状态。

幂等与失败策略

不要这样做

• 不要把好友、群、组织规则写进 flare-im-core。
• 不要用 metadata 承载稳定业务语义，例如“群主”“好友状态”。这些应在你的业务系统或明确类型字段中维护。
• 不要让客户端直接相信本地群成员缓存来决定能不能发消息；最终门禁在服务端 Hook。
• 不要绕过 Core 直接写消息表或手工分配 seq。
• 不要把群目录塞进 IM 同步 payload；群资料应由业务 API 或独立业务 SDK 管理。

最小落地清单

1. 业务账号系统签发 IM 登录 Token。
2. 建一个 Business Bridge，维护 business_id -> conversation_id 映射。
3. 实现 flare.hook.v1.pre_send，校验好友/群权限。
4. 群/好友变化时，通过 Bridge 同步会话参与者投影。
5. 客户端用 IM SDK 收发消息，用业务 API 拉好友/群资料。
6. 用 post_send / 会话成员事件做审计、统计和业务 read model 回流。

相关文档

• 服务端架构总览
• 客户端接入
• 业务扩展 Hook
• ExtensionPlugin 接入