07 — flare-im-core 业务扩展点与 API 接入

1. 结论

flare-im-core 的业务扩展必须走显式扩展面，不允许核心服务直接依赖业务 crate。生产推荐按能力类型选择接入方式：

核心约束：

• request_id 负责幂等和追踪，不等于 message_id。
• message_id 是消息全局标识，不等于会话内 seq。
• seq 只由 IM Core 在会话维度分配，业务服务不得生成或回退。
• cursor 用于读模型同步，不得替代消息 seq。
• 所有服务间调用必须透传 Ctx：x-trace-id、x-request-id、x-tenant-id、x-user-id。

2. 扩展点清单

3. HookPlugin API

服务定义：

GenericRequest 约定：

常用 operation：

pre_send 的业务语义：

1. Orchestrator 已完成基础消息校验。
2. 尚未分配最终 seq，业务不能依赖 seq。
3. Hook 可以返回 allow = false 拒绝发送。
4. Hook 可以回写 draft.metadata 或 annotations，但必须由宿主决定哪些字段进入持久化事实。
5. 业务拒绝应返回机器可读 deny_reason_code，例如 SOCIAL_PRESEND_DENIED。

4. Capability / Extension API

CapabilityService 面向能力目录、授权和命令分发：

ExtensionPlugin.Call 面向通用 operation：

使用原则：

• 能力调用必须带 tenant_id、user_id、conversation_id、request_id。
• 大 payload 不应塞进 payload_json；应先落对象存储或业务存储，再传引用。
• operation 必须版本化或保持向后兼容。
• 长耗时任务应返回 accepted / task_id，不阻塞 IM 主链。

5. 服务间 gRPC API

6. 扩展接入决策

更完整的消息/会话接入点、群体变更和 Core 独立运行策略见 docs/integration/09-message-conversation-access-points.md（内部稿，未在站点发布）。 业务接入埋点模型见 10-business-instrumentation.md。

7. 生产要求

• 幂等：所有写操作使用 request_id 或业务事件 ID 去重。
• 顺序：业务不得生成或覆盖消息 seq；会话内顺序只认 Core 分配结果。
• 超时：主链 Hook 超时必须短，pre_send 建议 100-500ms。
• 降级：强一致门禁 fail-fast；审计、指标、通知 fail-open。
• 观测：Hook/Extension 必须输出 trace_id、request_id、tenant_id、operation、耗时、结果。
• 安全：Hook body 里的用户字段不能替代认证；服务端必须从 metadata / token 还原可信身份。