第3章 埋点状态定义与数据结构设计

3.1 设计原理与目标

埋点状态的数据结构是埋点系统的数据骨架，直接决定采集的准确性和可扩展性。本章围绕三个核心层次展开设计：事件模型（描述“发生了什么”）、状态字段（描述“当前应用状态是什么”）、用户行为上下文（描述“在什么环境下由谁触发”）。设计目标包括：

• 自描述性：每条埋点数据无需额外元信息即可独立解析；
• 兼容性：版本演进时字段可追加但不可破坏旧数据；
• 低冗余：公共上下文通过引用合并，避免重复存储。

3.2 埋点事件模型定义

事件模型是埋点的最小记录单元。每个事件对象必须包含以下必选字段，可选字段因事件类型而异：

对应Kotlin数据类定义示例（API示例）：

data class TrackingEvent(
    val eventId: String = UUID.randomUUID().toString(),
    val eventName: String,
    val timestamp: Long = System.currentTimeMillis(),
    val eventType: EventType,
    val stateSnapshot: Map<String, Any?> = emptyMap(),
    val contextRef: String? = null
)

enum class EventType {
    CLICK, VIEW, SCROLL, INPUT, CUSTOM
}

3.3 状态字段定义

状态字段描述埋点触发时应用层面的可度量属性。遵循扁平化+分组前缀策略，避免深层嵌套导致序列化开销。标准字段表：

状态快照采集代码片段（实现流程）：

fun captureStateSnapshot(): Map<String, Any?> {
    return mapOf(
        "screen.name" to currentScreenName,
        "screen.route" to currentRoute,
        "user.id" to userId,
        "user.is_logged" to isLoggedIn,
        "session.id" to sessionId,
        "session.length" to sessionDurationMs,
        "device.model" to Build.MODEL,
        "device.os" to Build.VERSION.SDK_INT,
        "app.version" to BuildConfig.VERSION_NAME,
        "app.build" to BuildConfig.VERSION_CODE
    )
}

3.4 用户行为上下文数据封装

上下文数据封装了触发事件时的环境信息——包括页面来源、交互组件路径、网络状态、用户手势等。目的是支持归因分析和用户行为路径重建。上下文对象结构：

上下文对象一旦构造完成，通过SHA256生成不变引用（context_ref），使其可被多个事件共享，减少存储冗余：

data class UserContext(
    val pageFlow: List<String>,
    val interactionPath: String,
    val network: NetworkType,
    val gesture: GestureType,
    val appState: AppState
) {
    val ref: String by lazy {
        val json = Json.encodeToString(this)
        MessageDigest.getInstance("SHA-256").digest(json.toByteArray())
            .joinToString("") { "%02x".format(it) }.take(16)
    }
}

enum class NetworkType { WIFI, MOBILE, NONE }
enum class GestureType { TAP, SWIPE, LONG_PRESS, SCROLL }
enum class AppState { FOREGROUND, BACKGROUND }

3.5 数据模型整体结构图

3.6 调试与验证方法

在Compose预览或单元测试中，可通过工具函数验证数据结构的完整性和字段覆盖：

// 调试辅助：检查事件所有必需字段是否存在
fun TrackingEvent.validate(): List<String> {
    val missing = mutableListOf<String>()
    if (eventId.isBlank()) missing.add("eventId")
    if (eventName.isBlank()) missing.add("eventName")
    if (stateSnapshot.isEmpty()) missing.add("stateSnapshot")
    // 上下文引用可为空，但如果有值则必须为16字符hex
    if (contextRef != null && contextRef.length != 16) missing.add("contextRef")
    return missing
}

单元测试示例（部署前验证）：

@Test
fun `event should have all required fields`() {
    val event = TrackingEvent(
        eventName = "test_event",
        eventType = EventType.CUSTOM,
        stateSnapshot = captureStateSnapshot()
    )
    assertThat(event.validate()).isEmpty()
}

3.7 常见错误与性能优化

性能优化建议：

• 使用 mutableStateMapOf 仅追踪变化字段，快照采集时只提取差异部分（增量快照）；
• 上下文对象构造后立即调用 ref 惰性计算，且缓存到内存LRU中，同一上下文重复出现只存引用；
• 状态字段全部扁平化为单层Map，避免递归序列化，Compose中可预测性能更好。

// 增量快照示例：只记录变化的字段
class StateCollector {
    private val previous = mutableMapOf<String, Any?>()

    fun collectDelta(snapshot: Map<String, Any?>): Map<String, Any?> {
        val delta = snapshot.filter { it.value != previous[it.key] }
        previous.putAll(delta)
        return delta
    }
}

3.8 部署配置建议

在 build.gradle.kts 中启用数据对象序列化（若使用kotlinx.serialization）：

plugins {
    kotlin("plugin.serialization") version "1.9.22"
}
dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.2")
}

同时建议在运行时开启debug日志记录埋点原始JSON，方便在Staging环境校验数据完整性。