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

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

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 等拼写；未知值应展示并上报，不能导致整个响应反序列化失败。

命令与业务结果

轮询

保存 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 校准。
• 状态转移和补偿进入审计。