FranklinWH-Toolbox/docs/fault-record/implementation-status.md

故障录波当前实现状态

核对日期：2026-10-16。按 technical-design.md 和 ui-design.md 完成首版编码；尚未用真实设备测试，依赖实测的前提见 technical-design.md。

1. 代码位置

层	位置	内容
L0	service/utils/mqttClient/mqttClient.go	补充订阅表加锁（OnConnect 回调与业务线程并发访问）
L1	service/repositories/mqtt/fwh_mqtt/	fwh_mqtt_client.go：按环境的客户端，Request／Publish／Subscribe，有订阅时不空闲断开；fwh_mqtt_envelope.go：信封构造与 topic 工具
—	service/repositories/mqtt/fwh_xlog/	Xlog 业务从客户端包移出，固定生产服
L2	service/function/FaultRecordProtocol/	377 构造、378／379／607～610 解析（兼容旧版本 608 将 id 误写为第二个 result）、setVal 校验与 idData 解读、触发源／错误码字典
L2	service/function/FaultRecordFile/	hexData（code=1/2/3）、failuredata、waveformdata、压缩包（按文件头识别 gzip／bzip2）、CSV（zip）
存储	service/repositories/mongo/faultRecordRepo.go	集合 FaultRecordOperation，索引在 mongo.Init 注册
存储	service/repositories/minio/faultRecordRepo.go	对象键 fault-record/<env>/<gatewaySn>/<fileName>
下载	`service/repositories/api/fwh_pro	fwh_test/fwh_faultRecordUpload.go`
锁	service/cache/redisx/lockx.go	新增 TryLockWithToken：以操作 ID 为 token，重启后可接管自己的网关锁
L3	service/task/queue/faultRecordQueue/	asynq 队列 fault-record；执行器状态机、取消、重启恢复；RecoverActive 在启动时重新提交未结束操作
L4	service/services/faultRecordServices.go	创建／取消／查询／详情／录波解析／导出／设备列表
L5	service/controllers/faultRecordControllers.go、service/routes/faultRecordRoutes.go	见下方接口表
前端	src/views/fault-record/	record（录波记录）、device-info（设备信息）、function（功能操作：1/3/4/7）、param-write（参数设置：5/6，读取走 cmd=0）四个页面，公共组件在 common/；功能码 2 暂不开放
前端	src/service/faultRecord/、src/router/record.ts	接口封装；菜单“故障录波 → 生产服／测试服 → 功能”

已删除：旧参数设置接口 /faultRecord/paramSetting 及其页面 fault-record/read|write、faultRecordState store、客户端包中的 FaultRecordParamSetting／ChargeChannel、测试服手动脚本。

2. HTTP 接口

方法	路径	说明
GET	/faultRecord/devices?env=&gatewaySn=	站点信息中的 aGate + aPower（pe）列表
POST	/faultRecord/operations	创建操作，返回 id；kind 为 device_info／record_fetch／param_read／param_write
GET	/faultRecord/operations?env=&gatewaySn=&kind=&pageNum=&pageSize=	操作历史（共享）
GET	/faultRecord/operations/:id	详情：状态、阶段时间、逐项结果（含解析）、原始报文
POST	/faultRecord/operations/:id/cancel	取消
POST	/faultRecord/operations/:id/retry-download	上传已完成但下载失败时手动重试下载
GET	/faultRecord/operations/:id/record	录波解析结果（基本信息、通道、波形）
GET	`/faultRecord/operations/:id/export?format=raw	csv`

3. 已完成的验证

全部离线，未连接任何设备或服务器：

• 协议与解析：用 CloudLog_2026-10-14_104644.csv 全部报文和 2026-10-14_05_46_20.tar.bz2 做单元测试（目录 15 条、failuredata 字段、16×1536 波形、故障点对齐、CSV）。
• MQTT 客户端：用内存假连接测试多订阅者分发、引用计数订阅、一问一答匹配与超时（-race）。
• 执行器：用样本报文回放完整 record_fetch（sent → … → done，faultRecordID=5226）和 device_info；另测设备忙、过滤其他 cmd／网关、378 超时、取消发送 cmd=4、重启时 accepted → interrupted、ready 直接下载恢复、网关锁占用。
• 后端 go build、go vet 通过；前端 vue-tsc、vite build 通过，新增代码无 eslint 错误。
• 未做：页面实际渲染效果未在浏览器中查看（需要登录环境）。

4. 实测时需要关注

建议按此顺序在测试服实测，每步保存操作详情中的原始报文：

1. 设备信息：读取 code=1,2,3，核对目录与设备一致；确认 MQTT 能订阅 s2c（详情中应能看到 380）。
2. 录波获取：先选一条记录获取，确认出现 607／609、文件下载成功、波形可查看、两种导出可用。这一步验证“只监听平台上传”是否成立。 再勾选多条一起获取，确认压缩包包含全部记录，以及 379 中多组 4/5 的顺序。
3. 功能操作读取：读取 4、7，确认 cmd=3 外层支持及 idData 解读是否正确。
4. 参数设置：设一个无害参数（如采样频率设为当前值）并勾选自动复读；确认 setResultList 顺序，以及 code=1 可配采样通道与索引的对应（索引 1 = 第 1 项）。
5. 取消：获取录波时在“设备已应答”阶段取消，观察设备对 cmd=4 的反应。
6. pe 设备：对一个 aPower 做第 1、2 步，确认下载路径中的 <equipNo> 是否仍为网关 SN。
7. 生产服：确认配置后重复第 1、2 步。

可调参数集中在 service/task/queue/faultRecordQueue/deps.go 的 defaultTimeouts（378 等待 30s、379 等待 2 分钟／录波 4 分钟、上传 5 分钟；收到 610 后 15 秒开始下载、失败每 15 秒重试至总超时）。