stateDiagram-v2
    [*] --> IDLE : 初始化
    IDLE --> DIALING : 发起呼叫
    IDLE --> RINGING : 收到邀请
    DIALING --> CONNECTING : 信令交互成功
    RINGING --> CONNECTING : 用户接受
    CONNECTING --> CONNECTED : 媒体协商完成
    CONNECTED --> HOLDING : 用户保持
    HOLDING --> CONNECTED : 用户恢复
    CONNECTED --> DISCONNECTING : 任意端挂断
    DISCONNECTING --> IDLE : 资源释放完成
    CONNECTING --> FAILED : 信令/媒体超时
    FAILED --> IDLE : 用户确认/自动重试
    [*] --> RECONNECTING : 网络中断触发
    RECONNECTING --> CONNECTED : 重连成功
    RECONNECTING --> FAILED : 重连超时

interface CallEvent {
  type: CallEventType;           // 枚举：USER_DIAL, SIGNAL_INVITE, TIMER_TIMEOUT...
  payload?: Record<string, any>; // 透传业务数据（sdp, callId, errorCode...）
  timestamp: number;             // 事件发生时间，用于幂等/去重
  source: 'user' | 'signal' | 'media' | 'timer' | 'system';
}

┌─────────────────────────────────────┐
│         UI / 业务逻辑层              │  仅订阅 State 变更，发送 Intent
├─────────────────────────────────────┤
│         FSM 核心调度层               │  StateMachine: transition(), guard(), action()
│  ┌─────────────┐ ┌───────────────┐  │
│  │ State Registry│ │ Transition Table│ │  纯内存数据结构，可序列化持久化
│  └─────────────┘ └───────────────┘  │
├─────────────────────────────────────┤
│         Side-Effect 执行层           │  Network / MediaEngine / Timer / Logger
│  - 信令收发 (WebRTC/SIP)             │
│  - 媒体协商/启停                     │
│  - 定时器管理                        │
│  - 埋点/日志上报                     │
└─────────────────────────────────────┘

// 状态机核心接口
interface ICallStateMachine {
  currentState: CallState;
  dispatch(event: CallEvent): Promise<TransitionResult>;
  subscribe(listener: StateChangeListener): UnsubscribeFn;
  getSnapshot(): CallStateSnapshot; // 用于崩溃恢复/多端同步
}

// 执行器接口（依赖倒置，便于单测 Mock）
interface ICallSideEffectExecutor {
  sendSignal(msg: SignalMessage): Promise<void>;
  startMedia(constraints: MediaConstraints): Promise<void>;
  stopMedia(): Promise<void>;
  setTimer(ms: number, callback: () => void): TimerId;
  clearTimer(id: TimerId): void;
  reportEvent(eventName: string, props: Record<string, any>): void;
}

const guards: Record<CallState, Record<CallEventType, GuardFn>> = {
  CONNECTED: {
    USER_HOLD: (ctx) => !ctx.isScreenSharingActive, // 共享中不可保持
    USER_MUTE: (ctx) => true,
    NETWORK_INTERRUPT: (ctx) => ctx.networkQuality < 2, // 弱网才触发重连
  },
  // ...
};

type SideEffectCmd =
  | { type: 'SEND_SIGNAL'; payload: SignalMessage }
  | { type: 'START_MEDIA'; payload: MediaConstraints }
  | { type: 'START_TIMER'; payload: { key: TimerKey; ms: number } }
  | { type: 'REPORT'; payload: AnalyticsEvent };

function onEnterConnected(ctx: CallContext): SideEffectCmd[] {
  return [
    { type: 'START_MEDIA', payload: ctx.mediaConstraints },
    { type: 'START_TIMER', payload: { key: 'CALL_DURATION', ms: 1000 } },
    { type: 'REPORT', payload: { event: 'call_connected', callId: ctx.callId } },
  ];
}

class CallStateMachine {
  private eventQueue: CallEvent[] = [];
  private processing = false;

  async dispatch(event: CallEvent) {
    // 幂等去重：同一 callId + 同类型事件在 200ms 内仅保留最新
    if (this.isDuplicate(event)) return;
    this.eventQueue.push(event);
    await this.flushQueue();
  }

  private async flushQueue() {
    if (this.processing) return;
    this.processing = true;
    while (this.eventQueue.length) {
      const evt = this.eventQueue.shift()!;
      await this.transition(evt); // 内部含 guard/action/executor
    }
    this.processing = false;
  }
}

stateDiagram-v2
    state "通话主状态机" as Main {
        [*] --> IDLE
        IDLE --> CONNECTED
        CONNECTED --> DISCONNECTING
        DISCONNECTING --> IDLE
    }

    state "能力正交区域" as Orthogonal {
        state "屏幕共享" as Share {
            [*] --> IDLE_S
            IDLE_S --> SHARING : START_SHARE
            SHARING --> IDLE_S : STOP_SHARE
        }
        state "云端录制" as Record {
            [*] --> IDLE_R
            IDLE_R --> RECORDING : START_REC
            RECORDING --> IDLE_R : STOP_REC
        }
        state "实时转写" as Trans {
            [*] --> IDLE_T
            IDLE_T --> TRANSCRIBING : ENABLE_AI
            TRANSCRIBING --> IDLE_T : DISABLE_AI
        }
    }

    Main ||--|| Orthogonal : 并发执行

// 伪代码：组合式 HSM 核心
class CallContext {
  main: MainStateMachine;
  capabilities: Map<CapabilityType, SubStateMachine> = new Map();
  
  dispatch(event: CallEvent) {
    // 1. 主流程优先处理（挂断/重连等全局事件）
    const mainResult = this.main.dispatch(event);
    
    // 2. 广播给所有激活的子状态机（共享/录制/转写）
    // 子状态机内部自行判断 Guard，不关心则忽略
    for (const [, sub] of this.capabilities) {
      sub.dispatch(event); // 火并忘，不阻塞主流程
    }
    return mainResult;
  }
  
  // 启动子能力：动态挂载子状态机
  async enableCapability(type: CapabilityType, config: any) {
    const sub = createSubMachine(type, config, this.executor);
    this.capabilities.set(type, sub);
    await sub.dispatch({ type: 'INIT', payload: config });
  }
}

// call_snapshot.proto
message CallSnapshot {
  string call_id = 1;
  MainState main_state = 2;           // 枚举
  map<string, CapabilitySnapshot> capabilities = 3; // 子状态机快照
  int64 timestamp_ms = 4;
  string version = 5;                 // FSM 配置版本号，防止版本不匹配
  // 关键上下文：用于崩溃恢复/多端同步/后台保活
  MediaContext media_ctx = 10;        // sdp, ice候选, 码率配置
  NetworkContext net_ctx = 11;        // 当前网络类型、RTT、丢包率
  UserPreference user_pref = 12;      // 静音/关摄像头/设备选择
}

// 标准事件：state_transition
{
  "event": "state_transition",
  "call_id": "uuid-v4",
  "device_id": "hash",
  "app_version": "3.2.1",
  "fsm_config_version": "v20240515",
  "from_state": "CONNECTING",
  "to_state": "CONNECTED",
  "trigger_event": "SIGNAL_ANSWER",
  "trigger_source": "signal",
  "duration_ms": 1250,           // 状态停留时长
  "transition_cost_ms": 12,      // FSM 内部决策耗时
  "executor_cost_ms": 1200,      // 副作用执行耗时
  "result": "SUCCESS",           // SUCCESS / GUARD_REJECT / EXECUTOR_ERROR
  "error_code": null,
  "context": {                   // 关键上下文采样（非全量）
    "network_type": "wifi",
    "rtt_ms": 45,
    "codec": "H264/VP9",
    "is_p2p": true
  }
}

[Client A] --(INVITE)--> [Signal Server] --(OFFER)--> [Client B]
    |                                                          |
    |--(Trace: call_id=abc)--> [Media Server (SFU)] <--(Trace)--|
    |        |                                                 |
    |        +---> [Recording Service]                         |
    |        +---> [ASR Transcribe Service]                    |

graph LR
    A[外部事件: 用户操作/信令/网络] --> B{路由器 Router}
    B -->|灰度比例/白名单| C[新 FSM 引擎]
    B -->|默认兜底| D[旧逻辑 Legacy Controller]
    C --> E[统一 Executor 接口]
    D --> E
    E --> F[信令/媒体/定时器/埋点]
    
    C -.->|状态同步| D
    D -.->|状态同步| C

// 录制子状态机 Guard 强制合规检查
const recordGuards = {
  IDLE_R: {
    START_REC: (ctx) => {
      // 1. 必须已获得全员同意（或主持人强制模式+入会提示）
      if (!ctx.consentManager.allConsented()) return { allowed: false, reason: 'CONSENT_REQUIRED' };
      // 2. 必须在合规区域（数据不出境）
      if (!ctx.geoCompliance.isAllowedRegion()) return { allowed: false, reason: 'REGION_BLOCKED' };
      // 3. 未成年模式下强制关闭录制
      if (ctx.userProfile.isMinor && ctx.meetingConfig.minorProtection) return { allowed: false, reason: 'MINOR_PROTECTION' };
      return { allowed: true };
    }
  },
  RECORDING: {
    STOP_REC: (ctx) => true, // 随时允许停止
    USER_LEAVE: (ctx) => {   // 参会者离开自动停止录制（合规兜底）
      ctx.executor.dispatch({ type: 'STOP_RECORD', payload: { reason: 'PARTICIPANT_LEFT' } });
      return { allowed: false, reason: 'AUTO_STOP_ON_LEAVE' }; // 禁止流转，由 Action 驱动停止
    }
  }
};

stateDiagram-v2
    CONNECTING --> ENCRYPTION_NEGOTIATING : E2EE 开启
    ENCRYPTION_NEGOTIATING --> CONNECTED : 密钥协商成功
    ENCRYPTION_NEGOTIATING --> FAILED : 协商超时/密钥不匹配
    CONNECTED --> ENCRYPTION_ROTATING : 密钥轮换
    ENCRYPTION_ROTATING --> CONNECTED : 轮换完成

// 快照序列化前置处理器
function sanitizeSnapshot(snapshot: CallSnapshot): SafeSnapshot {
  return {
    ...snapshot,
    context: {
      ...snapshot.context,
      // 脱敏处理
      userId: hashPII(snapshot.context.userId),
      mediaCtx: {
        ...snapshot.context.mediaCtx,
        localCandidates: snapshot.context.mediaCtx.localCandidates.map(maskIP),
        remoteCandidates: undefined, // 远端候选地址不落盘
      },
      // 移除明文 SDP，仅保留协商结果
      negotiatedCodec: snapshot.context.mediaCtx.negotiatedCodec,
    },
  };
}

// 简单对象池模式
class CallMachinePool {
  private pool: CallStateMachine[] = [];
  private readonly MAX_POOL = 50;

  acquire(config: CallConfig): CallStateMachine {
    const machine = this.pool.pop() ?? new CallStateMachine();
    machine.reset(config); // 重置状态、清空队列、取消定时器
    return machine;
  }

  release(machine: CallStateMachine) {
    machine.teardown(); // 显式释放引用、取消订阅
    if (this.pool.length < this.MAX_POOL) this.pool.push(machine);
  }
}