1. 埋点状态数据模型设计

埋点状态数据模型是模块边界通信中状态管理的核心契约。在分布式系统中，一个埋点从采集到最终归档，会经历多个阶段，每个阶段对应一个精确的状态值。设计清晰的状态枚举、严格的转换规则、完整的附加字段以及可靠的版本号控制，是实现埋点状态机的基础。

1.1 状态枚举定义

定义状态枚举时，需要为每个状态分配一个整型值、一个字符串名称，并明确语义。下面是埋点生命周期的标准状态枚举：

1.2 状态转换图

下面这张状态转换图描述了埋点从创建到归档的完整路径，以及异常转移和重试回退机制。

1.3 状态附加字段

每个状态除了枚举值外，还需要携带一组附加字段，用于支撑诊断、审计和重试策略。附加字段在状态转换时按规则写入：

1.4 版本号控制

版本号用于解决分布式环境下状态更新冲突的问题。采用 单调递增的 64 位整数 作为版本号，每次状态转换时原子递增。版本号必须满足以下契约：

1. 乐观锁：更新状态时携带当前版本号，服务端比对版本号一致才允许更新，否则返回冲突。
2. 全局单调：版本号在同一个埋点实例的生命周期内单调递增，不允许回退。
3. 初始值：埋点创建时版本号设为 1，此后每次状态转换 +1。
4. 并发写冲突：当两个模块同时尝试更新状态时，后到达的请求会收到版本冲突提示，触发重试或降级。

版本号在状态数据模型中存储为 version 字段，序列化为 JSON 时的示例如下：

{
  "tracking_id": "evt_9a8b7c6d5e",
  "status": "VALIDATED",
  "version": 3,
  "fields": {
    "error_code": 0,
    "error_message": "",
    "retry_count": 0,
    "last_updated": 1712534400123,
    "transition_cost_ms": 42,
    "source_node": "collector-01",
    "enrichment_tags": null,
    "batch_id": ""
  }
}

1.5 数据模型完整结构

综合状态枚举、附加字段和版本号，得到埋点状态机的完整数据模型结构（Protobuf 定义）：

syntax = "proto3";

message TrackingEvent {
  string tracking_id = 1;
  EventStatus status = 2;
  uint64 version = 3;
  StateFields fields = 4;
}

enum EventStatus {
  UNKNOWN = 0;
  INITIAL = 1;
  COLLECTED = 2;
  VALIDATED = 3;
  ENRICHED = 4;
  AGGREGATED = 5;
  ARCHIVED = 6;
  FAILED = 99;
}

message StateFields {
  int32 error_code = 1;
  string error_message = 2;
  int32 retry_count = 3;
  uint64 last_updated = 4;
  uint64 transition_cost_ms = 5;
  string source_node = 6;
  map<string, string> enrichment_tags = 7;
  string batch_id = 8;
}