# 异步命令、事件与状态收敛

设备、媒体、录像和宿主操作往往不能在一次 HTTP 请求内完成。可靠客户端必须区分“命令是否执行”和“业务结果是否就绪”。

```mermaid
flowchart LR
    S([开始]) --> P[Pending]
    P --> R[Running]
    R --> O{进入终态}
    O --> X[Succeeded · Failed · TimedOut · Cancelled]
```

## 通用状态

常见过程状态包括 `Pending`、`WaitingDependency`、`Dispatched`、`Running`，终态包括 `Succeeded`、`Failed`、`TimedOut`、`Cancelled`。历史模块可能出现 `Queued` 或 `Canceled` 等拼写；未知值应展示并上报，不能导致整个响应反序列化失败。

## 命令与业务结果

| 场景 | 命令成功后还要确认 |
|---|---|
| 启动流 | MediaServer 真实流在线 |
| 协议控制 | 设备响应与协议会话收敛 |
| 开始录像 | 会话运行、文件产生并索引 |
| 裁剪合并 | 输出文件存在、时长和内容正确 |
| 生命周期 | 进程、health、MediaServer 和任务恢复 |
| RTC | ICE 与媒体真实连通 |

## 轮询

保存 commandId/sessionId/correlationId，按 1、2、5、10 秒退避查询。客户端自身超时后不要再次 POST；先查询命令、资源或会话是否已经存在。

依赖命令必须保存完整依赖链。上游失败或超时时，下游不得假装执行成功。

## 运行态 WebSocket

先读取 `/api/v2/events/runtime/info` 的协议信息，再连接 `/api/v2/events/runtime/ws`，使用子协议 `akstream-runtime-v1`。

客户端至少处理：

- 初始 snapshot；
- 增量 event；
- sequence/eventId 排序、去重与缺口；
- ping/pong；
- 权限失效和服务端关闭；
- 重连后的 REST 快照校准。

重连可以立即尝试一次，再按 1、2、5、10 秒退避，最大 30 秒。不能假设断线期间消息永远不丢失。

## 迟到结果

命令正式 `TimedOut` 后，设备仍可能迟到返回成功。平台保留 late result 审计，但不会反向覆盖已经对外形成的终态。客户端应同时展示正式状态与迟到证据，不要把它误判为数据损坏，也不要自动把超时业务改成成功。

## 第三方通知

需要业务通知时使用公开的第三方 Webhook 方案，按文档检查验签、事件去重与失败重试；不要调用产品组件接口。

## 状态机检查表

- 写操作保存稳定业务键与返回 ID。
- 事件按 eventId 去重。
- 终态后再检查最终业务资源。
- 只用稳定 failureCode 控制分支，不匹配本地化错误文案。
- 超时先查询，重试前判断操作是否可安全重放。
- 断线后用 REST 校准。
- 状态转移和补偿进入审计。