埋点字典要回答的六个问题

一份最小可用记录

以下结构来自工作札记中的示例，不对应任何真实公司的数据规范。对每个事件，我会要求字典回答 6 个问题：业务含义、触发条件、必填字段、用户身份、版本生效时间和维护人。

名称稳定，语义也要稳定

同一个名称若先表示按钮点击，后来改成页面成功加载，时间序列就失去可比性。若业务含义改变，应新增版本或事件，而不是只改文档里的描述。

业务语言和技术实现要并排写。产品同事需要看懂事件代表什么，开发和分析人员需要知道它在何时触发。

字段要写允许值和缺失规则

字段类型还不够。来源字段是自由文本还是枚举，空值表示未知还是不适用，都需要明确。否则同一概念会出现大小写、缩写和空字符串等多种写法。

• 列出允许值与默认值。
• 说明字段在哪些端和版本可用。
• 标记敏感字段及保留期限。
• 记录去重键和重复事件的处理方式。

用验收样例连接文档和数据

上线前准备一组操作路径，写明每一步预期产生的事件和字段。验收时同时查看客户端日志、接收端原始记录和分析表。三处一致，才能说明文档描述已经落到数据链路中。

1. 按路径操作从明确的起点完成一次示例流程，保留时间和测试身份。
2. 核对原始事件检查触发顺序、字段值、重复记录和时区。
3. 核对分析表确认清洗、去重和身份合并没有改变业务含义。

把变更当作版本管理

字典应保留变更日期、影响范围和迁移说明。分析查询引用事件时，也应注明适用版本。这样遇到时间序列断点，才能判断是用户行为变化还是记录方式改变。