MiguDelay 架构 23：屏蔽截图报告

系列导航：系列总览 · 上一篇：MiguDelay 架构 22：机审会话 · 下一篇：MiguDelay 架构 24：Transfer 导入导出工具链

扫描基线

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

1. 功能

离开 Delay 输出模式时，按 0、3、6、9、12 秒抓取五张 Delay Surface 图片；返回 Delay 时 flush 已完成图片并上报。失败不影响任务 stop barrier。

2. 对象分工

类	职责
ShieldSnapshotService	batch generation、5 slots、聚合、flush/cancel
LegacyShieldSnapshotSource	Delay Surface、grabToImage、JPG
LegacyShieldSnapshotPublisher	shield_report_image MQTT
LegacyShieldSnapshotBinding	mode/task event 转 context/start/flush/cancel

3. 触发

• OutputMode 从 Delay 离开：authoritative 节点 start。
• 返回 Delay：先 flush，再发布 block status，保证顺序。
• task generation 替换或 terminal phase：cancel old batch。

Context 冻结 identity、generation、tunnelId、clientId、replyTopic。

4. 批次流程

sequenceDiagram
    participant M as OutputModeEvent
    participant S as ShieldSnapshotService
    participant T as SlotTimers
    participant SRC as SnapshotSource
    participant R as PreviewRegistry
    participant P as Publisher

    M->>S: start immutable context
    S->>S: allocate batch generation and five slots
    loop slot zero to four
        T->>S: slot due
        S->>SRC: capture
        SRC->>R: get Delay surface
        SRC->>SRC: grab image and save JPG
        SRC-->>S: typed artifact or error
    end
    S->>S: settle all slots and sort successes
    S->>P: publish report

5. slot 规则

• 每个 slot 只接受第一次 completion。
• 单 slot 失败不取消整个 batch。
• 五个 slot 全部 settled 后发布成功图片。
• directory unavailable 可取消全部 batch。
• capture/publish completion 必须匹配 batch generation 和 task generation。

6. Source 边界

只有 Source 能接触：

• PreviewSurfaceRegistry::Delay
• YuvVideoItem
• grabToImage
• directory creation
• JPG encoding/save

Service 不包含 Qt Quick 类型。

7. Publisher schema

• type
• client_id
• main_tunnel_id
• schedule_id
• ordered images
  • image_url
  • snapshot_time

replyTopic 为空时同步拒绝。

8. flush 与 cancel

flush

• cancel pending captures。
• 发布已完成 artifacts。
• invalidate active generations。
• 只合并完全相同 immutable context。

cancelAll

• invalidate capture/publish。
• 不发布已完成图片。

9. shutdown

Binding disconnect → Service invalidate/cancel → Source/Publisher callback gate → destroy objects。

10. 源码证据

• src/code/module/playback/shieldsnapshot/*
• src/code/module/playback/preview/previewsurfaceregistry.*
• src/code/controls/yuvvideoitem.*
• tests/shield_snapshot_service/*

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 22：机审会话 · 下一篇：MiguDelay 架构 24：Transfer 导入导出工具链