MiguDelay 架构 04：配置持久化与任务工作区

系列导航：系列总览 · 上一篇：MiguDelay 架构 03：公共类型、状态、错误与线程合同 · 下一篇：MiguDelay 架构 05：QML、UiContext 与 ViewModel

扫描基线

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

1. 两类状态

• AppConfig：进程级配置与历史兼容入口，包含输入、备路、输出地址、延时、预览规格、MQTT、主备和机审配置。
• TaskWorkspacePolicy：单任务收录目录、identity marker、版本路径和历史保留策略。

AppConfig 不是任务 phase owner；TaskWorkspacePolicy 也不执行录制。

2. AppConfig 调用

QML setting page
  -> AppConfig.updateConfig
  -> update in-memory properties
  -> AppSettingsStore write
  -> emit URL or delay change signals
  -> LegacyStreamReconfigurationBinding

mountPath 使用 QtConcurrent::run 持久化快照。openPreviewOnStartup() 只恢复配置，不主动探测输入。

3. 流检测

sequenceDiagram
    participant QML as Settings QML
    participant C as AppConfig
    participant P as StreamProbeService
    participant G as GenerationTracker

    QML->>C: checkInputAsync url
    C->>G: allocate generation
    C->>P: probe frozen url
    P-->>C: probe result
    C->>G: verify current
    alt current result
        C->>C: update media info
    else stale result
        C->>C: discard
    end

主输入、pending 主输入、备输入和备输出各有检测入口，generation 防止旧结果覆盖新配置。

4. TaskWorkspacePolicy

输入 TaskWorkspacePrepareRequest 包含根路径、任务 identity 和启动原因。输出包括：

• recordRoot
• temporaryRoot
• versionsRoot
• identity marker
• 本次版本的 .venc、.dxt、.pcm 等路径

flowchart TD
    R["Prepare request"] --> M["Read identity marker"]
    M --> C{"Same task identity"}
    C -->|yes| KEEP["Keep compatible history"]
    C -->|no| ROTATE["Rotate old record root"]
    KEEP --> DIR["Create tmp and versions"]
    ROTATE --> DIR
    DIR --> MARK["Write identity marker atomically"]
    MARK --> READY["Workspace ready"]

5. 类调用链

TaskOrchestrator
  -> ILegacyTaskStartBinding.prepareStart
       -> TaskWorkspacePolicy.prepare
       -> TaskWorkspacePolicy.allocateVersion
       -> build immutable record requests

allocateVersion() 在同次启动中幂等；marker 和 manifest 使用临时文件替换原子写；退役目录异步删除。

6. 风险

• AppConfig 仍是大型单例，字段覆盖配置、协议和 UI。
• 异步持久化必须依赖正确的关闭顺序。
• 工作区磁盘满、轮换失败、崩溃恢复仍需真实文件系统验证。

7. 源码证据

• src/code/data/appconfig.*
• src/code/data/appsettingsstore.*
• src/code/data/streamprobeservice.*
• src/code/module/playback/workspace/taskworkspacepolicy.*
• src/code/module/playback/workspace/taskworkspacetypes.h

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 03：公共类型、状态、错误与线程合同 · 下一篇：MiguDelay 架构 05：QML、UiContext 与 ViewModel