aivfo-tl-3.0/项目文档/需求文档/05-实时通讯与服务监控.md

05 · 实时通讯与服务监控

父文档：../00-需求总览.md · 对应需求 7/10 · 决策 D6(部分) · 风险 R9

---

1. 现状（已核对修正）

实时显示是 MQTT 推送 + HTTP 轮询混合，不是"纯 5 秒轮询"：

• 舱室温压/状态/报警 = MQTT 订阅推送（operate MainPageViewModel.RecMqttMessage:512，订 TL/House/surface/{tlSn}）。
• 设备列表/运行时间/报警计数/培养记录 = HTTP 5 秒轮询（StartThread:741-770）。

薄弱点：

• control MQTT 保活 TryPing 循环被 return; 屏蔽（MqttService.cs:81）；WithCleanSession() 断线漏发不补。
• 断线仅写日志、无任何 UI 失联提示（operate/control 均是）。
• 在线态(HTTP online) 与 舱室态(MQTT) 来源割裂：broker 掉线但 HTTP 正常时，界面仍显"在线"、数据已停更，用户无感知。

---

2. 需求 10：实时显示准确稳定

1. 指标（🔶待定具体值）：状态刷新延迟上限（建议 ≤2s）、断线检出时间、重连最大时延，作为验收标准。
2. 就近取数：合并后 operate 优先直接读 control 内存/事件（本机实时），服务器仅用于跨端/历史，不再绕服务器一圈拉回。
3. 推送优先：实时状态走 MQTT/事件驱动，5 秒轮询降级兜底；恢复被屏蔽的保活心跳。
4. 链路健康可视化：界面显示服务器连接/MQTT/上报队列/最后成功通讯时间；断线/过期显著提示，不"假装实时"。
5. 稳定性兜底（分两类）：
   • 状态类：断网缓存最近状态 + 标注"离线/数据时间"，恢复自动补齐。
   • 临床数据类（图片/记录/标定）：⚠️ 现状图片直接落盘 tmpDir、无明确补传队列，关系病例数据完整性，需单独确认补传机制（落盘队列+断点续传+去重）。

---

3. 需求 7：服务监控页（只读）

• 入口：设置页新增"服务运行监控"。
• 背景：合并后 control 是后台线程、本身无界面，把其运行状态可视化。
• 显示（实时，来自 control 内存/事件）：服务器通信、CCD、拍照状态、温度、气体状态、数据上传队列、MQTT、磁盘。
• 只读：不做任何修改/新增/删除。受众=运维工程师。
• 与需求 10 链路健康打通：同一页展示通讯健康 + 最后通讯时间 + 断线告警。

---

4. front-management 一致性（详见 08）

front-management 订 TL/House/pc、5s/60s 轮询、有 ResolutionAdapter。三端（control/operate/front）状态同源但主题/接口不同。本轮需保证对焦相关状态语义一致（尤其新对焦的失败/中间态，front 不能显示成"正常"）。

---

5. 验收

1. 舱室状态刷新延迟 ≤ 约定值；断线在约定时间内检出。
2. 断网时界面有显著失联提示、不显示过期数据为实时。
3. 恢复后状态自动补齐；图片/记录按补传机制不丢。
4. 服务监控页只读、实时、含链路健康。

---

6. 全量操作日志链路（可观测性，见 14）

服务监控之外，系统新增全量操作日志作为问题定位/可观测性基座：

• C#/Java 所有操作经 Kafka(tl-oplog) → 日志微服务 aivfo-oplog → log 库 operation_log。
• 出问题时按 trace_id 把一次操作的跨端日志拉成时间线，定位失败步骤与输入/错误。
• 两级日志：操作级入库（长期、可查、AI 可分析）；调试级（串口/相机原始细节）走本地文件、按模块/按舱热开。
• 详见子文档 14。