# 故障录波文档导航

本目录整理通过 MQTT 直接获取和设置子设备故障录波数据的需求与设计，覆盖生产服和测试服。当前状态：首版已编码并通过离线测试，待真实设备实测（见 [implementation-status.md](implementation-status.md)）。文档中的待实测内容不代表设备已支持。

建议阅读顺序：requirements → technical-design → ui-design；查协议细节再看 protocol-specification 和 FaultFilter 文档。

## 文档职责

| 文档 | 内容 | 何时读取 |
| --- | --- | --- |
| [requirements.md](requirements.md) | 四项功能目标、预期行为、待确认的产品口径 | 确定要做什么、讨论验收范围时 |
| [technical-design.md](technical-design.md) | 分层架构、MQTT 客户端、异步操作与恢复、存储、取消、双环境 | 讨论如何实现、评审后端设计时 |
| [ui-design.md](ui-design.md) | 菜单结构、各功能页面布局和交互 | 实现或评审前端页面时 |
| [FaultFilter_MQTT协议文档.md](FaultFilter_MQTT协议文档.md) | 设备侧故障录波服务的业务协议：命令码、字段、`hexData` 字节结构、功能码、错误码 | 业务层字段的权威依据；与其他文档冲突时以它为准 |
| [protocol-specification.md](protocol-specification.md) | `377～380` 逐字段结构、示意报文、关联规则和编号补充清单 | 核对协议结构、逐项补充缺失信息时 |
| [protocol-observations.md](protocol-observations.md) | `377～380` 报文、真实样本时间线、旧协议描述和存疑项 | 判断协议字段、核对新抓包时 |
| [implementation-status.md](implementation-status.md) | 当前仓库已实现的能力、代码入口和差距 | 开始修改代码或核对当前行为时 |
| [CloudLog_2026-10-14_104644.csv](CloudLog_2026-10-14_104644.csv) | 2026-10-14 测试服原始通讯日志，含 `607～610` 上传过程 | 核对样本原文时 |
| [2026-10-14_05_46_20.tar.bz2](2026-10-14_05_46_20.tar.bz2) | 上述日志对应的录波文件（实为 gzip tar），记录序号 7 | 开发和测试文件解析时 |

## 事实与决策的边界

- **真实报文**用于确认样本覆盖的消息字段和顺序；单份日志不证明未覆盖场景的行为。
- **已验证代码**用于确认现有参数设置请求结构；当前代码行为见实现状态文档。
- **旧协议描述**保留为待验证线索。与真实报文冲突时，以真实报文为准。
- **用户后续确认**记录在协议详细描述中；与旧样本不同的服务端约定单独标注，不改写历史样本。
- **功能需求**定义目标；**技术设计**只记录当前可支持的方案与必须先验证的条件。两者不因现有代码或单份日志而自动改写。

## 与 DataDownload 的关系

[DataDownload](../data-download/README.md) 已有基于 FWH API 的故障录波召唤、下载和归档流程。本目录讨论新增的 MQTT 直连路径。MQTT 路径的文件同样由平台上传到 hes-upload，`607.faultRecordID` 是平台召唤记录 ID，可与 DataDownload 的记录互查。用户决定：本功能完整实现并测试通过后，再考虑开放给 DataDownload；在此之前 DataDownload 继续使用原 FWH API 方案。本阶段不把现有 DataDownload 行为视为 MQTT 协议事实。

## 维护方式

新增抓包先更新 `protocol-observations.md` 并标明证据；字段和协议规则确认后更新 `protocol-specification.md`；产品范围变化更新 `requirements.md`；确认设计决策后更新 `technical-design.md`；页面调整更新 `ui-design.md`；代码落地后再更新 `implementation-status.md`。避免把同一项存疑写成多处互相冲突的结论。