MiguDelay 架构 27：关键类索引与阅读路径

系列导航：系列总览 · 上一篇：MiguDelay 架构 26：当前分支差异、风险与维护建议

扫描基线

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

1. 关键类索引

类	owner	主要调用者	主要被调用对象	线程
PlaybackRuntime	App.cpp	App.cpp	全部服务、绑定、ViewModel	控制线程
ApplicationIngress	Runtime	MQTT handlers	configured handlers	任意到控制
TaskAdmissionService	Runtime	Task VM、TaskManager	Task command Port	控制
TaskSession	Runtime	Orchestrator	无 I/O	控制
TaskOrchestrator	Runtime	Admission、Preview、Reconfig	Session、Gateway、Effects	控制
TaskHandleGateway	Runtime	Orchestrator	legacy backend	控制和 callback
LegacyTaskHandleAdapter	Gateway	Gateway	TaskHandle、Output	worker boundary
TaskHandle	singleton	Adapter、transfer	concrete Tasks	worker
RecvNetworkFlowFFmpeg	recv context	StartRecvTask	FFmpeg、decode callbacks	media
Output	recv context	Recv flow	Preview、Encoder callbacks	tick
OutputWithLocalFileReader	recv context	DelayReader	Preview、Encoder callbacks	tick
OutputModeService	Runtime	Binding	StateView	控制
AuxPlaybackService	Aux components	VM、Router、Binding	Store、Reader、FrameSource	控制
PreviewFrameRouter	Runtime	TaskStartBinding	Registry、Tracker、Trigger、Aux	任意到控制
MonitorAudioService	Runtime	VM、Binding	Player Adapter	控制
StreamReconfigurationService	Runtime	Binding	operation Port、Task Port	控制和 worker
MasterBackupService	Runtime	VM、Ingress	Transport	控制
MachineAuditService	Runtime	Binding、Ingress	Gateway	控制
ShieldSnapshotService	Runtime	Binding	Source、Publisher	控制

2. 按问题阅读

任务为什么没启动

QML or MQTT
  -> TaskAdmissionService
  -> TaskOrchestrator.start
  -> TaskStartEffects.prepareStart/probe
  -> TaskHandleGateway
  -> StartRecvTask
  -> Gateway result
  -> Orchestrator

任务为什么停不下来

TaskOrchestrator.stop
  -> resource ledger
  -> stopPush/stopRecord/stopReceive tickets
  -> TaskHandle take context
  -> Gateway result
  -> TaskSession.completeStop

画面为什么不显示

Recv or Output callback
  -> adaptPreviewFrame
  -> PreviewFrameRouter generation check
  -> route by source/mode
  -> PreviewSurfaceRegistry
  -> YuvVideoItem

为什么不能返回 Delay

StreamReconfiguration requestDelay
  -> Output pending generation
  -> cache complete promotes active generation
  -> versioned delayed video
  -> FrameAvailabilityTracker exact match
  -> OutputMode capability

为什么 Aux 有画面但节目不动

Aux Reader buffers
  -> AuxFrameSourceAdapter
  -> Output callback
  -> PreviewFrameRouter
  -> AuxPlaybackService.handleVideoFrame
  -> current program/progress

为什么主备不同步

authoritative domain event
  -> ReplicationPublisher
  -> MQTT
  -> MasterBackupHandle
  -> ApplicationIngress
  -> LegacyReplicationBinding
  -> ReplicationCommandApplier
  -> typed Port

3. 固定排障步骤

1. 找入口。
2. 找 raw 到 typed 边界。
3. 找唯一状态 owner。
4. 找 identity、generation、ticket、requestId。
5. 找线程切换。
6. 找最终消费者。
7. 找 reject、timeout、cancel、stale、shutdown 收敛路径。

4. 推荐新人阅读顺序

1. 总览。
2. App 启动与 Runtime。
3. 公共类型和线程合同。
4. Admission → Session → Orchestrator → Gateway。
5. 收流 → Output → 录制/推流。
6. OutputMode → Aux → Preview。
7. Reconfiguration。
8. 主备、监看音频、机审、截图。
9. 测试与风险。

5. 术语速查

• Service：规则中心和通常的状态 owner。
• Session：纯状态机。
• Orchestrator：跨步骤编排与资源账本。
• Port：领域所需最小能力接口。
• Gateway：外部异步系统关联和 callback gate。
• Adapter：数据或 API 形状转换。
• Binding：新领域与 legacy 副作用之间的迁移胶水。
• Snapshot：按值只读状态。
• Generation：同一 owner 内的版本号。
• Ticket：具体异步操作号。
• Stale：完成了但不再属于当前上下文。
• Barrier：等待真实已接受操作全部结算。

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 26：当前分支差异、风险与维护建议