4. 事件类型与触发机制：六大事件源驱动状态流转

在状态机驱动的埋点生命周期中，事件是触发状态跃迁的唯一输入。每类事件携带特有的语义、触发时机和载荷结构，状态机根据事件类型执行预定义的转换规则，同时记录埋点生命周期中的关键节点。本章定义六大标准事件类型，并给出触发机制、数据结构与 SDK 注册示例。

4.1 事件类型总览与分类

4.2 触发机制与状态机路由

所有事件统一经过 事件路由器，路由器根据事件类型将事件分发到对应的处理器。处理器内部维护一个 事件-状态转换表，确保只有满足前置条件的事件才会触发状态变化。

event_routing:
  - event_type: "app_start"
    handler: "AppStartHandler"
    allowed_states: ["IDLE", "SUSPENDED"]
    priority: 1
  - event_type: "page_enter"
    handler: "PageEnterHandler"
    allowed_states: ["ACTIVE", "FOREGROUND"]
    priority: 2
  - event_type: "user_action"
    handler: "UserActionHandler"
    allowed_states: ["ACTIVE", "PAGE_FOCUSED"]
    priority: 3
  - event_type: "network_change"
    handler: "NetworkChangeHandler"
    allowed_states: "*"
    priority: 10
  - event_type: "timeout"
    handler: "TimeoutHandler"
    allowed_states: ["ACTIVE", "WAITING", "SUSPENDED"]
    priority: 5
  - event_type: "error"
    handler: "ErrorHandler"
    allowed_states: "*"
    priority: 0
  - event_type: "custom"
    handler: "CustomEventHandler"
    allowed_states: "*"
    priority: 100

4.3 SDK 事件注册与派发 API

埋点 SDK 提供统一的 trackEvent 接口，调用方只需传入事件类型和负载。SDK 内部自动完成类型校验、绑定上下文、推入队列并通知状态机。

// TypeScript SDK 示例
import { EventBus, EventType } from '@track/state-machine-sdk';

// 注册监听器（内部状态机自动订阅）
EventBus.on(EventType.PAGE_ENTER, (event) => {
  console.log(`[状态机] 页面进入事件 → 当前状态: ${stateMachine.currentState}`);
  stateMachine.dispatch('page_enter', event.payload);
});

// 发送事件（业务方调用）
EventBus.emit({
  type: EventType.USER_ACTION,
  payload: {
    element_id: 'submit_btn',
    action_type: 'click',
    page_id: 'checkout',
    timestamp: Date.now()
  },
  meta: {
    session_id: getSessionId()
  }
});

4.4 事件优先级与队列处理

为了防止高并发操作导致状态混乱，所有事件先进入 有序队列，按优先级和到达时间排序。超时事件和错误事件拥有最高优先级，确保状态机及时做出故障响应。

// 队列调度核心逻辑（伪代码）
class EventQueue {
  dispatch(event) {
    this.queue.enqueue(event, priorityMap[event.type]);
    if (!this.processing) {
      this.processing = true;
      scheduleMicrotask(() => this.process());
    }
  }
  process() {
    while (this.queue.length > 0) {
      const event = this.queue.dequeue();
      const handler = this.router.route(event.type, stateMachine.currentState);
      if (handler) {
        handler.handle(event);
      }
    }
    this.processing = false;
  }
}

4.5 事件触发流程与状态机关联

// 日志输出示例（结构化日志）
[INFO] [EventRouter] 事件入队 | type=page_enter id=evt-0001 size=1.2KB
[INFO] [EventRouter] 命中处理器 PageEnterHandler | 优先级 2
[INFO] [StateMachine] 状态跃迁 | event=page_enter from=FOREGROUND to=PAGE_FOCUSED
[WARN] [EventRouter] 未找到处理器 | type=timeout currentState=IDLE (忽略)
[ERROR] [StateMachine] 状态转换异常 | event=error currentState=FOCUSED stack=TypeError: ...