2. 埋点数据模型设计：事件结构、序列化、时间戳与优先级字段

埋点数据模型是上报系统的核心骨架。一个设计合理的数据模型应当同时满足传输效率、持久化可回溯和重试优先级判定三种需求。本章从事件结构定义出发，逐步分析序列化选型、时间戳规范以及优先级字段在重试场景中的关键作用。

2.1 事件结构：最小必要字段集

一个埋点事件至少包含以下6 个必填字段，其余业务属性以 Map 形式附加：

2.2 序列化方案：JSON vs 二进制

埋点上报通常选用 JSON 作为序列化格式，原因在于：

• 自描述：无需额外 schema 即可解析，便于调试与动态打点；
• Kotlin 生态：kotlinx.serialization 提供编译期安全、零反射序列化；
• 重试场景：JSON 字符串可直接存于本地数据库或文件，无需反序列化即可查看内容。

当对体积有极致要求时（如弱网大量缓存），可降级为 Protocol Buffers，但会增加 debug 成本。

序列化示例：kotlinx.serialization

@Serializable
data class AnalyticsEvent(
    @SerialName("id") val eventId: String,
    @SerialName("name") val eventName: String,
    @SerialName("uid") val userId: String,
    @SerialName("ts") val timestamp: Long,
    @SerialName("p") val priority: Int = 1,
    @SerialName("props") val properties: Map<String, @Serializable Any> = emptyMap()
)

// 序列化
val event = AnalyticsEvent(
    eventId = UUID.randomUUID().toString(),
    eventName = "screen_view",
    userId = "u_abc123",
    timestamp = System.currentTimeMillis(),
    priority = 1,
    properties = mapOf("screen" to "home", "duration" to 5000)
)
val json = Json { ignoreUnknownKeys = true; encodeDefaults = true }
val payload: String = json.encodeToString(event)

2.3 时间戳规范：UTC 毫秒级 + 本地时钟偏移记录

上报系统的重试逻辑高度依赖时间戳：

• 事件时间戳：客户端产生事件时的 UTC 毫秒数，用于时效性过滤（超过 TTL 的事件直接丢弃，不再重试）；
• 本地时间偏移：客户端将 System.currentTimeMillis() 与 SystemClock.elapsedRealtime() 做差值，记录偏移量。服务端在收到事件后可反推设备真实时钟偏差，辅助判断重试窗口。

2.4 优先级字段：重试队列调度的核心

priority 字段控制事件在上报队列中的处理顺序和服务端的重试优先级：

在序列化负载中，priority 同时写入 event 对象的顶层字段，方便重试中间件（如本地 PriorityQueue 或 Room 的 ORDER BY）直接排序。

2.5 数据模型整体结构图

下图展示了一个完整埋点事件从构造到序列化的数据流动与字段分组：

2.6 稳定性优化：空值与默认值保护

在埋点 SDK 中，数据模型应避免空指针和非法值导致序列化崩溃：

• event_id 使用 UUID.randomUUID().toString() 自动生成兜底；
• timestamp 为 Long 类型，禁止使用 Long?，避免重试时出现 null 时间戳；
• properties 提供 MutableMap() 并内联 .toMap() 防止外部修改。

2.7 常见错误自查