1. Compose埋点架构全景：状态层、事件层、上报层

在 Jetpack Compose 的声明式 UI 体系下，埋点数据不再由用户点击事件被动触发，而是由状态驱动自动流转。传统的 Activity/Fragment 埋点方案在 Compose 中面临 状态感知缺失、组合生命周期不可控、上报时机混乱 三大核心问题。本章从架构全景出发，定义 状态层 → 事件层 → 上报层 的三层边界，给出每一层的组件职责与数据流契约。

1.1 三层架构总览

整个埋点流转体系划分为三个彼此独立、通过接口通信的层级。状态层感知 Compose 状态变化并生成原始事件；事件层对原始事件进行校验、增强、缓冲和策略过滤；上报层负责将合规事件序列化、批量压缩并发送到远端服务。三层之间不允许跨层调用，也不允许反向依赖。

1.2 边界与组件职责

三层之间的边界由 不可变事件契约 定义。状态层输出的 RawEvent 只包含状态快照和版本戳；事件层输出的 TrackEvent 携带业务维度、采样标记和路由标签；上报层最终消费 ReportPacket 进行序列化与传输。

• 状态层 — 唯一允许直接依赖 Compose State / SnapshotFlow 的层级。负责将 mutableStateOf 的变化映射为事件流，不对事件做任何业务判断。
• 事件层 — 纯 Kotlin 协程模块，不依赖任何 Android 或 Compose 运行时。负责事件的 去重（Dedup）、采样（Sampling）、上下文增强（Enrich） 和 缓冲（Buffer）。
• 上报层 — 依赖网络框架和本地数据库。负责将事件打包为 JSON/Protobuf，通过 批量合并 降低请求次数，并通过 指数退避重试 保证最终可达。

1.3 数据流与控制流

数据流是单向的：状态 → 事件 → 上报。控制流则通过 策略注入 反向作用于事件层和上报层，例如采样率更新、上报频率调节、事件黑名单等。

// 状态层：通过 SnapshotFlow 感知 Compose 状态变化
@Composable
fun TrackableScreen(viewModel: TrackableViewModel) {
    val uiState by viewModel.uiState.collectAsState()

    // 状态层自动采集
    LaunchedEffect(uiState) {
        viewModel.stateLayer.emitRawEvent(
            RawEvent(
                snapshot = uiState.toSnapshot(),
                version = snapshotFlow { uiState }.first()
            )
        )
    }
}

// 事件层：处理并转发
fun EventProcessor.process(raw: RawEvent): TrackEvent? {
    return when {
        raw.isDuplicate() -> null          // 去重
        !sampler.shouldSample(raw) -> null  // 采样
        else -> raw.enrich(metadataProvider())  // 增强
    }
}

// 上报层：批量调度
suspend fun ReportDispatcher.dispatch(event: TrackEvent) {
    buffer.put(event)
    if (buffer.size >= batchSize) {
        uploader.upload(buffer.flush())
    }
}

1.4 信任链路与版本追踪

数据在层间流转时，必须携带 不可篡改的签名链。每一层在收到前层数据后，会追加自己的校验值再传递给下一层。状态层为每个 RawEvent 生成 snapshotVersion；事件层附加 eventSignature（业务 ID + 时间戳 HMAC）；上报层写入 reportChecksum 后持久化。

1.5 选型权衡

1.6 落地步骤与验收标准

将三层架构落地到现有 Compose 项目中，建议按以下顺序推进：

1. 裁剪状态层 — 在目标 Composable 中注入 StateLayer，定义要追踪的 State 变量列表，验证每次状态变化都能产出 RawEvent。
2. 搭建事件层流水线 — 实现 EventCollector + EventProcessor + EventBuffer，用单元测试验证去重和采样逻辑。
3. 对接上报层 — 接入网络 SDK，配置批量上传参数和重试策略，编写集成测试验证端到端上报。
4. 注入控制流 — 通过 ViewModel 或配置中心下发采样率、黑名单等策略，观察事件层是否按预期过滤。
5. 全链路压测 — 在 200+ 状态变化/秒的极限场景下，验证事件层不 OOM、上报层不丢数据。