MiguDelay 架构 25：构建、依赖、测试与验证边界

系列导航：系列总览 · 上一篇：MiguDelay 架构 24：Transfer 导入导出工具链 · 下一篇：MiguDelay 架构 26：当前分支差异、风险与维护建议

扫描基线

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

1. 构建

• CMake 3.20+
• C++17
• AUTOUIC、AUTOMOC、AUTORCC
• Qt 5/6 Core、Quick、Concurrent、Multimedia、Network、Svg、PrintSupport、X11Extras
• output：bin/<BuildType>

2. 主要第三方

依赖	用途
FFmpeg	demux、decode、encode、mux、filter、resample
x264	H.264 编码
libyuv	YUV 转换
FluentUI	QML UI
spdlog	日志
Paho MQTT	MQTT
PulseAudio	Linux 监看音频
Breakpad	Linux crash dump
OpenSSL	SSL/crypto
Boost	部分基础设施

3. 测试分层

领域和服务 C++ tests

• task_session
• task_start_orchestrator
• task_handle_gateway
• task_ingress_admission
• task_workspace_policy
• stream_reconfiguration_service
• push_retry_controller
• output_mode_domain
• aux_playback_domain
• preview_domain
• monitor_audio_service
• master_backup_service
• replication_command_applier
• machine_audit_service
• shield_snapshot_service

UI 和 Runtime tests

• playback_runtime
• playback_ui
• aux_playback_ui
• output_mode_ui
• monitor_audio_ui
• master_backup_ui

静态架构 tests

大量 Python/shell 测试检查：

• Provider 边界
• Runtime 组合根
• UI 依赖方向
• Port 唯一来源
• lifecycle binding
• 各领域禁止 legacy 类型泄漏
• baseline 行为合同

4. 测试调用图

flowchart TD
    UNIT["Focused Cpp tests"] --> RULE["State and command rules"]
    ARCH["Python architecture tests"] --> BOUND["Dependency and source boundaries"]
    UI["QML and ViewModel tests"] --> PRES["Presentation contracts"]
    MAN["Manual runtime scenarios"] --> REAL["Real media network device behavior"]

5. Stub 的意义和风险

tests/playback_runtime 使用多组 stubs 替代 gateway factory、task start binding、reconfiguration、machine audit、master backup、shield snapshot、monitor binding 和 YuvVideoItem。

优点：可验证组合顺序和失败回滚。风险：若 stub 接口过度顺从，可能掩盖真实 callback 线程、不可中断 I/O 和资源关闭问题。测试应验证合同，不应驱动生产代码增加无业务意义的代理层。

6. 当前仍需实机验证

• 可达或不可达输入和参数突变。
• 长时间延时文件跨分片。
• RTMP/SRT 端点和无限重试。
• 多音轨、设备切换和 PulseAudio 恢复。
• 四种输出模式真实音画。
• QML Window/Page 快速重建。
• 双机 MQTT bind、timeout、reconnect、replication。
• 机审 HTTP/MQTT。
• QQuickItem screenshot。
• shutdown 时正在 probe、reconfigure、prewarm、encode、mux。

7. Mermaid 校验

本知识库包中的 Mermaid 使用：

• ASCII node/participant IDs。
• 标准 flowchart、sequenceDiagram、stateDiagram-v2。
• 不使用智能引号。
• 所有代码块经过结构校验；结果见根目录 MERMAID_VALIDATION.md。

8. 源码证据

• src/CMakeLists.txt
• tests/**
• docs/playback-behavior-baseline.md
• tests/playback_behavior_baseline.json

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 24：Transfer 导入导出工具链 · 下一篇：MiguDelay 架构 26：当前分支差异、风险与维护建议