MiguDelay 架构 03：公共类型、状态、错误与线程合同

系列导航：系列总览 · 上一篇：MiguDelay 架构 02：PlaybackRuntime 组合根 · 下一篇：MiguDelay 架构 04：配置持久化与任务工作区

扫描基线

• 项目：MiguDelay（DDLive）
• 分支：refactor/video-frame-provider
• HEAD：d28ec061406e4e3df93e3d1a92478d71a9ad4908
• 工作树：clean
• 扫描日期：2026-08-04
• 说明：内容以当前 HEAD 源码为准；仓库旧架构文档只作为检索线索。

1. 目标

新播放层通过值对象把原始 JSON、std::any、legacy struct 和 QML 可变属性隔离在边界之外。

2. 类型分类

类型	含义	示例
Command	请求尝试改变状态	StartTaskCommand、RestartPushCommand
Event	已接受或已发生的事实	OutputModeChangedEvent
Async Result	后台完成结果，必须过滤 stale	TaskGatewayResult、StreamOperationResult
Snapshot/View	按值只读状态	TaskStateView、MonitorAudioStateView
Identity	稳定业务身份	TaskIdentity
Generation	同一 owner 内递增版本	TaskGeneration
Ticket	一代任务中的具体异步操作号	TaskTicket
Error	稳定 domain/code/message/context	PlaybackError

flowchart LR
    TG["Task generation"] --> Q["One task lifecycle"]
    Q --> T1["Receive ticket"]
    Q --> T2["Record ticket"]
    Q --> T3["Push ticket"]
    OG["Operation generation"] --> R["One target reconfiguration"]

generation 回答“是否仍属于当前一轮”，ticket 回答“当前一轮中的哪项操作”。

3. 错误调用链

legacy TaskHandle error
  -> TaskErrorAdapter
  -> PlaybackError or typed stream event
  -> domain service or PlaybackErrorModel
  -> ViewModel and QML

PlaybackErrorModel 是展示聚合器，不是任务状态机；错误不能绕过 TaskSession 直接改 phase。

4. 线程合同

线程	允许	禁止
应用控制线程	修改领域真值、管理 QObject 生命周期	长时间阻塞媒体 I/O
MQTT/回调线程	复制 payload、边缘解析、queued invoke	直接写 Service 状态
TaskHandle worker	执行 legacy task	操作 QML/Service
QtConcurrent worker	使用冻结 request 做阻塞工作	回读变化中的 QObject 配置
Output/Reader/Encoder	处理媒体帧、读取窄 Port	写输出模式或任务 phase
QML/渲染	创建 Item、渲染、grab	持有后台任务生命周期

queued connection 只解决执行线程，接收端仍需检查 shutdown、generation、ticket、phase 和 immutable context。

5. 生命周期术语

• callback gate：关闭后晚到 callback 不再进入业务对象。
• shutdown gate：关闭后拒绝新 command/event。
• cancellation：请求后台尽快退出，不代表已经退出。
• drain：等待已接受工作达到安全终态。
• 任务 drain 由 TaskSession stop barrier 实现。
• 当前流重配置仅在 shutdown() 中等待全部 watcher。

6. 源码证据

• src/code/module/playback/playbacktypes.h
• src/code/module/playback/playbackcommands.h
• src/code/module/playback/playbackstateviews.h
• src/code/module/playback/playbackerror.h
• src/code/module/playback/playbackmetatypes.*
• src/code/module/playback/runtime/taskerroradapter.*

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 02：PlaybackRuntime 组合根 · 下一篇：MiguDelay 架构 04：配置持久化与任务工作区