transitions:
  - from: INVITING
    event: INVITE_TIMEOUT
    to: TERMINATED
    action: notify_caller_timeout
  - from: RINGING
    event: CALLEE_ACCEPT
    to: CONNECTING
    action: start_media_negotiation
  - from: ESTABLISHED
    event: NETWORK_INTERRUPT
    to: RECONNECTING
    action: trigger_ice_restart
  - from: RECONNECTING
    event: MEDIA_REESTABLISHED
    to: ESTABLISHED
    action: resume_media_transport
  - from: "*"
    event: FORCE_TERMINATE
    to: TERMINATED
    action: cleanup_all_resources

type ChairPrivilege string

const (
    PrivMuteAll        ChairPrivilege = "mute_all"
    PrivUnmuteAll      ChairPrivilege = "unmute_all"
    PrivKickParticipant ChairPrivilege = "kick_participant"
    PrivLockMeeting    ChairPrivilege = "lock_meeting"
    PrivAssignSpeaker  ChairPrivilege = "assign_speaker"
    PrivRecordControl  ChairPrivilege = "record_control"
)

var rolePrivileges = map[string][]ChairPrivilege{
    "chair":        {PrivMuteAll, PrivUnmuteAll, PrivKickParticipant, PrivLockMeeting, PrivAssignSpeaker, PrivRecordControl},
    "co_chair":     {PrivMuteAll, PrivUnmuteAll, PrivKickParticipant, PrivAssignSpeaker},
    "participant":  {},
}

[Client] → [API Gateway] → [Auth Interceptor: 校验 ChairPrivilege] 
         → [Command Bus] → [Meeting Aggregate: 业务规则校验] 
         → [Event Sourcing: 持久化 CommandExecuted Event] 
         → [Projection: 更新实时权限视图] 
         → [Push Service: 下发 Signaling Message 至被操作端]

type SignalingAdapter interface {
    Parse(raw []byte) (Event, error)
    Serialize(evt Event) ([]byte, error)
    HeartbeatInterval() time.Duration
}

// 状态机上下文：池化复用，避免 GC 压力
type FSMContext struct {
    SessionID   string                 // 全局唯一会话标识
    CurrentState State                 // 当前状态（原子读写）
    Version     uint64                 // 乐观锁版本号
    ExtData     map[string]interface{} // 扩展字段：SDP、ICE Candidate、主席权限位图等
    mu          sync.Mutex             // 仅保护 ExtData 与 Action 执行串行化
}

// 事件载荷：对象池管理
type Event struct {
    Type      EventType
    Payload   interface{} // 具体业务载荷（如 InviteReq, MediaAnswer, ChairCmd）
    Timestamp int64
    IdempotencyKey string // 幂等键
}

// 迁移定义：只读常驻内存，启动时由配置中心加载构建有向图
type Transition struct {
    From       State
    Event      EventType
    To         State
    Guards     []GuardFunc      // 前置校验：权限、资源配额、版本兼容
    Actions    []ActionFunc     // 副作用动作：持久化、推送、计费、埋点
    PostChecks []PostCheckFunc  // 后置校验：媒体建联确认、下发 ACK 成功
}

func (e *Engine) Dispatch(ctx *FSMContext, evt *Event) (err error) {
    // 1. 幂等去重（Redis Lua 脚本原子检查并设置，TTL = 2 * MaxRetransmitInterval）
    if !idempotent.TryAcquire(ctx.SessionID, evt.IdempotencyKey) {
        return ErrDuplicateEvent // 客户端重传，静默丢弃并返回 200 OK
    }
    defer idempotent.Release(ctx.SessionID, evt.IdempotencyKey)

    // 2. 乐观锁 CAS 循环（最多重试 3 次，指数退避）
    for attempt := 0; attempt < 3; attempt++ {
        oldVer := atomic.LoadUint64(&ctx.Version)
        trans, ok := e.lookupTransition(ctx.CurrentState, evt.Type)
        if !ok {
            metrics.IllegalEventCounter.Inc()
            return ErrInvalidTransition
        }

        // 3. 前置 Guard 校验（权限、资源、版本）
        if !trans.runGuards(ctx, evt) {
            return ErrGuardFailed
        }

        // 4. 执行 Actions（持久化、推送等），收集补偿动作用于回滚
        compensations, execErr := trans.runActions(ctx, evt)
        if execErr != nil {
            // 补偿回滚：逆序执行 Compensate()
            runCompensations(compensations)
            return execErr
        }

        // 5. CAS 更新状态与版本
        newState := trans.To
        if atomic.CompareAndSwapUint64(&ctx.Version, oldVer, oldVer+1) {
            atomic.StoreUint8((*uint8)(&ctx.CurrentState), uint8(newState))
            
            // 6. 异步后置检查（不阻塞主流程，失败走告警+人工/自动修复）
            go trans.runPostChecksAsync(ctx, evt)
            
            // 7. 状态变更事件入 Kafka，驱动下游投影/计费/风控
            e.eventBus.Publish(StateChangedEvent{SessionID: ctx.SessionID, From: ctx.CurrentState, To: newState, Version: oldVer+1})
            return nil
        }
        // CAS 失败：并发冲突，短暂退避重试
        time.Sleep(time.Duration(attempt+1) * time.Millisecond)
    }
    return ErrConcurrentConflict
}

// 权限位图定义（支持 64 种细粒度权限）
const (
    PermMuteAll       = 1 << iota // 0
    PermKickUser                  // 1
    PermLockMeeting               // 2
    PermAssignSpeaker             // 3
    PermControlRecording          // 4
    PermManageLayout              // 5
    // ... 预留扩展位
)

// 会议权限快照：随状态机版本号原子更新
type PermissionSnapshot struct {
    Version     uint64           // 关联 FSM Version
    ChairID     string           // 当前主席 UserID
    CoChairs    []string         // 联席主席列表
    RolePerms   map[string]uint64 // 角色 -> 权限位图
    UserPerms   map[string]uint64 // 用户显式授予/撤销的差集权限
    RevokedAt   map[string]int64  // 权限撤销时间戳（用于因果一致性判断）
}

// 客户端/网关校验函数：纯内存位运算，零 RPC
func (ps *PermissionSnapshot) Check(uid string, perm uint64) bool {
    // 1. 显式用户权限最高优先
    if p, ok := ps.UserPerms[uid]; ok {
        return p&perm != 0
    }
    // 2. 角色权限
    if role := getUserRole(uid); role != "" {
        if p, ok := ps.RolePerms[role]; ok && p&perm != 0 {
            return true
        }
    }
    // 3. 主席/联席主席隐含全权限
    return uid == ps.ChairID || contains(ps.CoChairs, uid)
}

sequenceDiagram
    participant OldChair
    participant SignalingServer
    participant NewChair
    participant AllClients

    Note over OldChair,AllClients: 阶段 1：发起转移（主席主动离开或超时判定）
    OldChair->>SignalingServer: LEAVE / HEARTBEAT_TIMEOUT
    SignalingServer->>SignalingServer: 选举算法选出 NewChair
    SignalingServer->>NewChair: CHAIR_TRANSFER_REQUIRE (Token, Version=V)
    
    Note over NewChair: 本地校验 Version 一致性<br/>持久化「准主席」状态
    NewChair-->>SignalingServer: CHAIR_TRANSFER_ACK (Token, Version=V)
    
    Note over SignalingServer: 阶段 2：广播确认
    SignalingServer->>AllClients: CHAIR_CHANGED (NewChairID, Version=V+1)
    AllClients-->>SignalingServer: ACK
    
    Note over SignalingServer: 收齐法定人数 ACK (Quorum = N/2+1)<br/>提交版本 V+1，更新 PermissionSnapshot

# test/contracts/call_fsm.yaml
scenarios:
  - name: "正常呼叫建立"
    initial: IDLE
    steps:
      - event: SEND_INVITE
        expect_state: INVITING
      - event: RECV_180_RINGING
        expect_state: RINGING
      - event: RECV_200_OK
        expect_state: CONNECTING
        actions: [start_ice, start_dtls]
      - event: ICE_CONNECTED
        expect_state: ESTABLISHED
  
  - name: "呼叫中网络中断恢复"
    initial: ESTABLISHED
    steps:
      - event: NETWORK_INTERRUPT
        expect_state: RECONNECTING
        actions: [trigger_ice_restart]
      - event: ICE_RECONNECTED
        expect_state: ESTABLISHED
  
  - name: "主席离开自动转移"
    initial: ESTABLISHED
    setup:
      chair: "user_A"
      participants: ["user_B", "user_C"]
    steps:
      - event: CHAIR_LEAVE
        actor: "user_A"
        expect_state: ESTABLISHED # 会话不变
        expect_chair: "user_B"    # 断言主席变更

// FuzzFSMTransitions 随机生成合法/非法事件序列，验证：
// 1. 无 Panic、无死锁
// 2. 状态始终在合法枚举范围内
// 3. 资源（端口、编解码器、定时器）无泄漏
func FuzzFSMTransitions(f *testing.F) {
    f.Add([]EventType{INVITE, ACCEPT, ICE_OK})
    f.Fuzz(func(t *testing.T, events []EventType) {
        ctx := NewTestContext()
        for _, evt := range events {
            _ = engine.Dispatch(ctx, NewEvent(evt))
        }
        // 最终状态必须可终止
        if ctx.CurrentState != TERMINATED {
            engine.Dispatch(ctx, NewEvent(FORCE_TERMINATE))
        }
        assert.NoLeak(t, ctx)
    })
}

graph LR
    A[配置中心] -->|Watch| B(网关/Worker 进程)
    B --> C{校验器}
    C -->|语法/语义/兼容性| D[本地内存生效]
    D --> E[上报生效版本]
    E --> F[Prometheus Metric: fsm_config_version]
    F --> G[Grafana 告警: 版本不一致 > 5min]

// 插件接口标准
type ActionPlugin interface {
    Name() string
    Version() string
    Execute(ctx *FSMContext, evt *Event) (compensation CompensationFunc, err error)
    Rollback(ctx *FSMContext, compData []byte) error
}

// 运行时注册表：读写锁保护，版本化管理
var pluginRegistry = struct {
    sync.RWMutex
    plugins map[string]map[string]ActionPlugin // name -> version -> instance
}{plugins: make(map[string]map[string]ActionPlugin)}

// 热加载流程：下载 .so/.wasm -> 校验签名 -> 实例化 -> 灰度注册 -> 全量切换
func LoadPlugin(artifactURL string) error { ... }

[Client SDK] 
    │
    ├── WebRTC DataChannel  ──► [WebRTC Adapter] ──┐
    ├── SIP over TLS        ──► [SIP Adapter]      ├──► [CIR: Canonical Intermediate Representation] ──► [核心 FSM 引擎]
    ├── Private WS/QUIC     ──► [Private Adapter]  │
    └── HTTP Long Polling   ──► [HTTP Adapter]     │

message SignalingEvent {
  string session_id = 1;
  uint64 version = 2;
  EventType type = 3;           // 统一事件类型：INVITE, ANSWER, CANDIDATE, CHAIR_CMD...
  oneof payload {
    InvitePayload      invite = 10;
    AnswerPayload      answer = 11;
    IceCandidatePayload candidate = 12;
    ChairCommandPayload chair_cmd = 20;
    MediaControlPayload media_ctrl = 30;
  }
  map<string, string> metadata = 99; // 透传字段：设备指纹、网络类型、SDK版本
}

// 营销内容合规拦截器
func MarketingComplianceInterceptor(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if isMarketingAPI(r.URL.Path) {
            content := extractMarketingContent(r)
            // 1. 极限词检测（最、首、顶级、国家级...）
            if banned := sensitive.Filter(content); len(banned) > 0 {
                audit.Log("marketing_violation", r.UserID, banned)
                http.Error(w, "内容包含违规用语", http.StatusBadRequest)
                return
            }
            // 2. 资质校验（医疗/金融/教育类需资质备案）
            if needQualification(r.TenantID) && !qualification.Valid(r.TenantID) {
                http.Error(w, "资质未备案", http.StatusForbidden)
                return
            }
        }
        next.ServeHTTP(w, r)
    })
}

# 容量模型参数（定期离线训练更新）
CAPACITY_MODEL = {
    "cpu_per_session_idle": 0.0002,      # 核/会话（空闲心跳）
    "cpu_per_session_active": 0.0015,    # 核/会话（活跃转发）
    "mem_per_session": 12 * 1024,        # Bytes (Context + Buffer)
    "max_sessions_per_core": 4000,       # 经验上限
    "scale_up_threshold": 0.7,           # CPU/MEM 水位
    "scale_down_threshold": 0.3,
    "cooldown_seconds": 300,
}

# HPA 自定义指标适配器：暴露 predicted_session_capacity 给 K8s HPA
def calculate_desired_replicas(current_sessions, current_replicas):
    capacity_per_replica = MAX_SESSIONS_PER_POD * 0.8 # 安全系数
    desired = math.ceil(current_sessions / capacity_per_replica)
    return clamp(desired, MIN_REPLICAS, MAX_REPLICAS)

## 故障复盘: INC-202410-001 信令风暴导致全站 15% 会话建立失败

### 1. 现象描述
- 时间：2024-10-15 14:02 - 14:18
- 影响：呼叫建立成功率跌至 85%，P99 延迟 3.2s
- 发现路径：Grafana 告警 → OnCall 接手

### 2. 根因分析 (5 Why)
1. **直接原因**：Worker 进程 Dispatch 队列堆积，GC STW > 2s
2. **中间原因**：大量 `INVITE_RETRANSMIT` 事件未幂等去重，重复执行 `start_media_negotiation` 创建海量 ICE Agent
3. **深层原因**：Redis 幂等键 TTL 设置过短 (1s) < SIP 重传间隔 (T1=500ms, T2=4s)，导致重传包穿透幂等层
4. **系统原因**：压测未覆盖「弱网重传风暴」场景；代码评审未关注幂等键 TTL 与协议重传定时器关系
5. **根本原因**：缺乏「协议层重传特性与应用层幂等设计」的联合验证机制

### 3. 修复与预防措施
- [x] **即时修复**：幂等键 TTL 调整为 `MAX_RETRANSMIT_DURATION * 2 = 64s`，上线验证恢复正常
- [x] **代码层**：增加 `IdempotencyKey` 生成规则文档，强制包含 `CSeq` 与 `Branch` 参数
- [x] **测试层**：新增契约测试用例 `weak_network_retransmit_storm`，纳入夜ly 压测
- [x] **架构层**：引入「信令风暴熔断器」，检测单 Session 事件频率 > 阈值自动进入 `THROTTLED` 状态，仅处理首包

### 4. 经验沉淀
- 更新《信令幂等设计指南 v2.1》
- 新增架构评审 Checklist 项：`幂等键 TTL >= 协议最大重传周期 * 2`