# 故障录波当前实现状态

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

## 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` | 按环境域名无 token 下载 |
| 锁 | `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` | 导出原始压缩包或 CSV（zip） |

## 3. 已完成的验证

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

- 协议与解析：用 [CloudLog_2026-10-14_104644.csv](CloudLog_2026-10-14_104644.csv) 全部报文和 [2026-10-14_05_46_20.tar.bz2](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 秒重试至总超时）。