10 — Core 业务接入埋点

1. 结论

业务接入埋点是 flare-im-contracts 给外部业务系统的非侵入式扩展面。它不把业务逻辑写进 Core，而是把 Core 主链中的关键事实转换为稳定事件，交给业务侧 Hook、Capability、MQ、Webhook 或 Sidecar 消费。

默认状态下，Core 使用 Noop 埋点实现；没有任何业务接入时，Core 仍可独立运行。

2. 埋点与 Hook 的区别

原则：

• 能用埋点解决的，不要写进 Core。
• 需要拒绝主链的，使用 Hook。
• 需要业务命令结果的，使用 Capability / Extension。
• 需要异步观察事实的，使用 Business Probe。

3. Core 标准埋点模型

Rust 公共类型位于 flare-im-core/crates/flare-im-contracts/src/instrumentation/mod.rs：

事件核心字段：

4. 标准事件名

5. 接入方式

5.1 进程内 Sink

适合 Rust 部署或 sidecar 同进程：

use flare_im_contracts::{BusinessProbeEvent, BusinessProbeSink, Ctx};
use flare_server_core::error::Result;

pub struct KafkaProbeSink;

#[async_trait::async_trait]
impl BusinessProbeSink for KafkaProbeSink {
    async fn emit(&self, ctx: &Ctx, event: BusinessProbeEvent) -> Result<()> {
        // 写 Kafka / NATS / 审计库
        Ok(())
    }
}

5.2 HookPlugin

适合跨语言业务系统：

• pre_send 处理好友、群权限、风控等强门禁。
• post_send 消费消息发送后事实。
• delivery / message_read 消费送达和已读行为。
• message_reaction 处理点赞、emoji、业务表态。
• conversation_lifecycle 消费会话状态变化。
• conversation_member 消费参与者变化。

消息和会话 Hook 的接入细节见 02-hook-plugin.md。

5.3 Capability / Extension

适合需要业务命令结果的场景：

• 计费：billing.im.message_usage.record
• 风控特征：risk.feature.im_activity.append
• 推荐特征：rec.relation.interaction.update

5.4 MQ / Webhook

适合批处理、数据平台、增长分析：

• Core 侧投递 BusinessProbeEvent 到 MQ。
• 业务侧按 name、tenant_id、schema 消费。
• Webhook 只用于低 QPS 管理或审计场景。

6. 业务可实现的非侵入能力

7. Hook 观测 payload 建议

Hook 观测事件建议使用 schema = "flare.im.hook_probe.v1"，payload 保持可演进 JSON：

{
  "hook_name": "social-policy-pre-send",
  "operation": "flare.hook.v1.pre_send",
  "decision": "allow",
  "latency_ms": 12,
  "error_policy": "fail_fast",
  "require_success": true,
  "deny_reason_code": "",
  "conversation_type": "group",
  "message_type": "text"
}

字段约定：

8. 投递语义

生产默认：

• 消息、会话、同步埋点使用 reliable_async。
• 指标类使用 best_effort。
• 不要把普通 BI 埋点设置成 blocking_audit。

9. 独立运行保证

Core 独立运行时：

• 使用 NoopBusinessProbeSink。
• Hook 配置为空时跳过 Hook。
• Capability 未部署时不影响消息、会话、同步核心链路。
• 业务 bridge 不部署时，Core 只维护自身会话和参与者投影。

业务接入后：

• 通过配置注入 Sink / Hook / Capability。
• 业务失败按投递语义降级。
• Core 不依赖业务 crate，不因业务不可用而无法启动。

10. 后续落地建议