第1章 埋点定义与状态模型建立

1.1 适用场景

本章适用于以下团队或项目阶段：

• 新建数据埋点体系，需统一管理埋点生命周期。
• 现有埋点流程混乱、状态不透明，导致测试与验收困难。
• 多团队协作（产品、开发、测试、数据）需要标准化状态语言。
• 自动化埋点测试平台建设前，需完成状态模型前置定义。

1.2 前置条件

• 已完成埋点需求文档（BRD / PRD），明确至少 5 个核心埋点事件。
• 数据治理团队已输出《埋点规范 v1.0》，包含命名规则、数据类型、上报协议。
• 产品、开发、测试三方已确认埋点优先级与上线节奏。
• 已选定状态管理工具（如 Jira / Excel / 自研平台），支持状态字段配置。

1.3 操作步骤

步骤一：定义状态节点

基于埋点生命周期，识别并定义关键状态节点。每个节点代表埋点从诞生到废弃的一个稳定阶段。推荐采用以下 6 个核心状态，覆盖完整生命周期：

步骤二：建模流转关系

定义状态之间的合法迁移路径，确保每个流转都有明确的触发动作与校验条件。采用有向图建模，禁止出现循环依赖或跳跃式流转。

• 合法流转：DRAFT → IMPL → REPORTED → VERIFIED → LIVE
• 终态收敛：VERIFIED 或 LIVE 可流转至 DEPRECATED
• 禁止路径：DRAFT → LIVE（跳过开发与验证）、LIVE → IMPL（回退需走变更流程）

下图展示了完整的 6 节点状态流转模型，其中实线为主流程路径，虚线为废弃分支：

步骤三：定义状态属性清单

为每个状态节点绑定一组标准化属性，确保所有团队对状态的理解一致。属性清单是后续自动化测试断言与监控报警的输入依据。

# 状态模型定义示例
states:
  - state_id: DRAFT
    state_name: 草稿
    state_type: initial
    transitions:
      - IMPL
    trigger: 埋点需求评审通过
    validation:
      required_fields: ["event_name", "event_id", "trigger_condition"]
    owner: 数据产品经理

  - state_id: IMPL
    state_name: 已埋入
    state_type: intermediate
    transitions:
      - REPORTED
    trigger: 代码部署完成 + 自检通过
    validation:
      code_review: true
      unit_test_pass: true
    owner: 开发工程师

1.4 输入输出物

1.5 责任边界

1.6 记录材料

• 状态模型评审纪要：记录评审日期、参与人、决议要点、遗留问题。
• 状态属性清单 v1.0：经三方签字的最终属性表，作为后续变更基线。
• 流转图附件：将本章 SVG 流转图导出为 PNG / SVG 文件，归档至项目 Wiki。

1.7 异常处理

1.8 验收标准

• 状态节点覆盖从“需求录入”到“数据下架”的全部关键阶段，不少于 5 个。
• 每个状态节点均包含完整的 8 项属性（ID、名称、类型、可流转至、触发条件、校验规则、责任人、时间戳）。
• 流转关系图为有向无环图，主路径清晰，废弃分支独立。
• 状态模型 YAML 契约已通过三方评审签字，并提交至项目仓库。
• 测试团队已基于状态属性清单编写至少 3 条状态校验冒烟用例（覆盖初始态、中间态、终态）。