FranklinWH-Toolbox/docs/fault-record

故障录波文档导航

本目录整理通过 MQTT 直接获取和设置子设备故障录波数据的需求与设计，覆盖生产服和测试服。当前状态：需求和整体设计已确认，待编码；双环境 MQTT 客户端已完成，其余未实现（见 implementation-status.md）。文档中的待实测内容不代表设备已支持。

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

文档职责

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

事实与决策的边界

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

与 DataDownload 的关系

DataDownload 已有基于 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。避免把同一项存疑写成多处互相冲突的结论。