3. 状态机建模与流转规则：状态节点、触发条件、转换动作、异常状态

模块间埋点状态流转的本质是一个有限状态机（FSM）：每个埋点数据包在生命周期中处于有限个离散状态，由明确的触发条件驱动状态迁移，迁移时执行预定动作。本章从模块边界出发，定义状态节点、触发条件、转换动作与异常处理策略，建立跨模块可验证的流转规则。

3.1 核心状态节点

埋点数据从采集到最终落盘或发送，经历以下核心状态。每个状态对应一个模块的职责边界：

3.2 触发条件分类

状态迁移由内外部事件触发。按来源分为两类：

• 内部触发：定时器到期、缓存达到阈值、网络恢复、重试间隔结束。
• 外部触发：用户产生新埋点、应用切前台/后台、服务端推送配置更新。

以下为典型转换的触发条件矩阵（仅列出主要合法迁移）：

3.3 转换动作

每次状态迁移需执行一组预定义动作，形成模块间的控制流。以下为各迁移的动作伪代码：

// 状态迁移动作示例（伪代码）
onTransition(State from, State to, Event event) {
    if (from == QUEUED && to == SENDING) {
        markDispatched(event.dataId);
        searializeToNetworkBuffer(event.data);
        updateMetrics("queue_dequeue", 1);
    }
    if (from == SENDING && to == SUCCESS) {
        removeFromRetryCache(event.dataId);
        writeSuccessLog(event.data);
        notifyCallbacks("onUploadSuccess", event.dataId);
    }
    if (from == SENDING && to == RETRYING) {
        saveToRetryQueue(event.data, retryCount+1);
        scheduleRetryTimer(event.dataId, exponentialBackoff(retryCount));
        emitWarning("network_timeout", event.dataId);
    }
    if (from == RETRYING && to == DISCARDED) {
        removeFromRetryQueue(event.dataId);
        writeDiscardLog(event.data, reason: "max_retries");
        notifyCallbacks("onUploadDiscard", event.dataId);
    }
}

3.4 异常状态与处理策略

异常状态并非独立节点，而是转换过程中出现的偏离预期路径的情形。常见异常及处理：

3.5 状态机模型总览

下图展示完整的埋点状态流转，包含所有核心节点、合法转换与异常处理路径（虚线表示异常回退）。

3.6 跨模块状态同步边界

状态转换往往跨越模块边界，需建立信任链路防止状态篡改。关键设计原则：

• 状态所有权：每个状态节点由唯一模块拥有（如上表&SVG标注），其他模块只能通过预定义接口读取或转换。
• 状态持久化：QUEUED、RETRYING、FAILED 状态必须在磁盘或数据库保留副本，用于崩溃恢复。
• 幂等转换：同一触发条件多次施加应产生相同结果（例如重复收到200 OK，只执行一次SUCCESS动作）。
• 数据流回溯：使用全局递增的 dataId 关联所有状态迁移记录，便于调试。

3.7 选型权衡：单状态机 vs 分层状态机

3.8 风险点与规避

• 循环转换：RETRYING↔SENDING 持续失败形成活锁。对策：重试次数硬限制 + 熔断器。
• 状态丢失：进程杀死后未持久化状态。对策：每次转换前同步写入 WAL（Write-Ahead Log）。
• 转换冲突：两个线程同时尝试转换同一 dataId。对策：使用 dataId 粒度锁或状态乐观锁（CAS）。

3.9 落地步骤

1. 定义状态枚举与转换矩阵：在一张表列出所有合法转换，作为团队成员 contract。
2. 实现状态机引擎：采用 StateMachineEngine 类，注册转换规则与动作监听器。
3. 集成持久化层：每个转换动作前，将 (dataId, from, to, timestamp) 写入事件溯源存储。
4. 添加异常探测：定时扫描处于 SENDING 或 RETRYING 超时的 dataId，强制触发异常处理。
5. 编写转换覆盖测试：使用状态机测试框架（如 StateMachineTest）验证每条转换路径。

3.10 验收标准