MiguDelay 架构 02：PlaybackRuntime 组合根

系列导航：系列总览 · 上一篇：MiguDelay 架构 01：应用启动与关闭 · 下一篇：MiguDelay 架构 03：公共类型、状态、错误与线程合同

扫描基线

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

1. 定位

PlaybackRuntime 是 composition root：它知道具体实现如何组装、初始化和关闭，但不拥有任务 phase、输出模式、播单等业务真值。

2. 成员分组

分组	关键对象
共享媒体 Port	OutputModeStateView、AuxFrameSourceAdapter
任务域	TaskSession、TaskHandleGateway、TaskWorkspacePolicy、PushRetryController、TaskOrchestrator、TaskAdmissionService
Preview	PreviewSurfaceRegistry、FrameAvailabilityTracker、FirstFrameTrigger、PreviewFrameRouter
Aux	PlaybackRuntimeDetail::AuxPlaybackComponents
输出模式	OutputModeService、ILegacyOutputModeBinding
流重配置	operation port、service、binding
主备	transport、service、binding、replication binding
外围	MonitorAudio、MachineAudit、ShieldSnapshot
UI	ViewModels、PlaybackUiContext、PlaybackErrorModel
外部入口	ApplicationIngress、TaskErrorAdapter

3. 初始化顺序

flowchart TD
    A["Shared ports and gateway"] --> B["Task and preview foundations"]
    B --> C["Aux components"]
    C --> D["Preview router"]
    D --> E["Task binding and orchestrator"]
    E --> F["Peripheral services"]
    F --> G["Admission"]
    G --> H["ViewModels and UiContext"]
    H --> I["Error adapter"]
    I --> J["ApplicationIngress"]

具体逻辑：

1. 创建 Gateway、Workspace。
2. 创建 Session、Preview 基础对象、Monitor、OutputMode。
3. 初始化 Aux 私有组件。
4. 创建 Preview Router。
5. 创建 Retry、TaskStart Binding、Orchestrator。
6. 创建机审、截图、主备、复制、流重配置等外围域。
7. 创建 Admission。
8. 创建 ViewModels 与 PlaybackUiContext。
9. 创建 TaskErrorAdapter。
10. 最后 configure ApplicationIngress。

外部入口最后开启，避免系统只初始化一半时收到命令。

4. 关键类调用

App.cpp
  -> PlaybackRuntime.initialize
       -> createLegacyTaskHandleAdapter
       -> TaskHandleGateway.initialize
       -> AuxPlaybackComponents.initialize
       -> createLegacyTaskStartBinding
       -> TaskOrchestrator
       -> create domain services and bindings
       -> create ViewModels
       -> PlaybackUiContext
       -> ApplicationIngress.configure

5. 主要信号主干

• TaskHandleGateway::resultReady → TaskOrchestrator::handleGatewayResult
• TaskOrchestrator::taskStateChanged → Tracker、FirstFrameTrigger、Preview、ViewModels、Ingress、Reconfiguration
• FirstFrameTrigger::firstOutputFrame → TaskOrchestrator::firstOutputFrame
• 各领域 stateChanged → 对应 ViewModel
• 各领域 typed error → PlaybackErrorModel

6. 关闭顺序

sequenceDiagram
    participant RT as PlaybackRuntime
    participant ING as ApplicationIngress
    participant RC as Reconfiguration
    participant O as TaskOrchestrator
    participant B as Domain Bindings
    participant S as Domain Services
    participant G as TaskHandleGateway
    participant P as Preview Registry

    RT->>ING: shutdown
    RT->>RC: shutdown and wait workers
    RT->>O: beginShutdown
    O-->>RT: shutdownReady after stop barrier
    RT->>B: disconnect and shutdown
    RT->>S: shutdown
    RT->>G: shutdown callback gate
    RT->>P: clear surfaces

7. 所有权规则

• unique_ptr：Runtime 独占，关闭顺序可见。
• QObject parent：适合 signal/slot 展示对象。
• shared_ptr：跨线程 Port/Adapter 延长生命周期，不代表共享写权。
• const interface/reference：跨领域只暴露最小能力。
• QML Item 由页面拥有，Registry 只保存 QPointer。

initialize() 任一步失败均调用幂等 shutdown() 回滚。

8. 源码证据

• src/code/module/playback/runtime/playbackruntime.h
• src/code/module/playback/runtime/playbackruntime.cpp
• src/code/module/playback/runtime/detail/auxplaybackcomponents.*

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 01：应用启动与关闭 · 下一篇：MiguDelay 架构 03：公共类型、状态、错误与线程合同