MiguDelay 架构 06：MQTT 与协议入口

系列导航：系列总览 · 上一篇：MiguDelay 架构 05：QML、UiContext 与 ViewModel · 下一篇：MiguDelay 架构 07：任务准入与公开垫片门

扫描基线

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

1. 边界

MQTT 层负责连接、订阅、发布和原始消息分发；领域层不解析 topic 或 JSON。ApplicationIngress 是协议线程进入 Runtime 的唯一 typed 入口。

2. 核心类

类	职责	线程
MqttClient	连接、消费、发布、同步 UUID 请求、心跳、设备上报	多线程
PublishQueue	发布队列	publish thread
MessageHandle	topic → MessageHandlerBase	MQTT callback
ClientOperateHandle	命令 JSON 解析与 dispatch	协议线程
ApplicationIngress	typed value queued 到 Runtime owner thread	任意 → 控制
TaskManager	旧任务入口兼容 facade	控制线程

3. 内部线程

• consume：连接 broker、订阅和接收。
• publish：消费 PublishQueue。
• heartbeat：周期心跳，读取 ApplicationIngress::taskActive 原子快照。
• PC state report：设备状态上报。
• 同步请求：UUID → QEventLoop* 和 response map。

4. 消息调用链

sequenceDiagram
    participant Broker as MQTT Broker
    participant MQ as MqttClient
    participant MH as MessageHandle
    participant H as Concrete Handler
    participant ING as ApplicationIngress
    participant S as Domain Service

    Broker-->>MQ: topic and payload
    MQ->>MH: dispatchMessage
    MH->>H: handleMessage
    H->>H: validate and parse JSON
    H->>ING: ingest typed value
    ING->>ING: queued invoke owner thread
    ING->>S: call configured handler

5. topic 映射

MessageHandle 初始化至少注册：

• client find topic
• 当前设备 request topic
• control sync topic
• 备机 backup sync topic

动态配对后可增加或移除 operate handler。

6. ApplicationIngress 合同

• configure 前不接受投递。
• payload 按值复制。
• 每个入口检查 m_accepting。
• queued 回 owner thread 后再调用 Handler。
• m_taskActive 仅给心跳线程只读。
• shutdown 先关 accepting，再清 handlers。

7. 错误策略

JSON/schema 错误在 Handler 边缘拒绝；业务拒绝由 Service 返回稳定 code；异步回复使用原 request identity/topic，不能在 completion 时重新读取当前配置。

8. 源码证据

• src/code/net/mqtt/MqttClient.*
• src/code/net/mqtt/PublishQueue.*
• src/code/module/netmessagehandle/MessageHandle.*
• src/code/module/netmessagehandle/clientoperate/*
• src/code/module/netmessagehandle/masterbackup/*
• src/code/module/playback/runtime/applicationingress.*
• protocol/mqtt/TopicDef.h

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 05：QML、UiContext 与 ViewModel · 下一篇：MiguDelay 架构 07：任务准入与公开垫片门