# 故障录波功能需求

> 状态：需求梳理，2026-09-30；2026-10-16 补充双环境需求、文件获取方式和 FR-06 操作方式。本文记录目标能力与待确认的产品口径，不将协议描述中的未验证字段写为已确认需求。协议证据见 [protocol-observations.md](protocol-observations.md)，当前实现见 [implementation-status.md](implementation-status.md)。

## 1. 目标与范围

目标是在 `repositories/mqtt` 对接设备故障录波协议，使以下操作可以直接通过 MQTT 完成，减少对 FWH API 的依赖：

1. 查询子设备故障录波实时数据；
2. 查询和导出子设备故障录波记录；
3. 查询子设备故障录波参数；
4. 设置子设备故障录波参数。

本工具负责向设备发送请求并监听设备上传；对 `379` 的应答和录波文件上传由 FWH 平台自动完成，本工具不重复应答。录波文件的触发和状态跟踪走 MQTT，文件本身仍从 FWH 平台的 hes-upload 下载。

以上能力需同时支持**测试服**和**生产服**（见 FR-05）。这里的“子设备”至少需要明确所在网关、设备类型和设备 SN。现有样本只有 aGate，且网关 SN 与 `info.sn` 相同；真正子设备的寻址方式待实测。

本需求描述独立的 MQTT 能力。现有 [DataDownload](../data-download/requirements.md) 的故障录波任务、日期固化和文件归档规则继续由其文档定义；是否接入新 MQTT 能力需单独设计。

## 2. 功能需求

### FR-01 查询实时数据

- 用户能指定目标网关和子设备，发起故障录波实时数据查询。
- 系统应呈现设备实际返回的数据、对应设备和单项结果；请求被应答与数据已返回应是可区分的状态。
- 若设备没有返回目标数据、返回失败或超时，系统应给出可定位的结果，不把空数据解释为查询成功。

**已确定**：开放 `code=1～3`，按字段显示原始值，可展开原始 `hexData`；页面见 [ui-design.md](ui-design.md#4-设备信息)。`code` 集合（`1～3`）及含义已由 [FaultFilter_MQTT协议文档](FaultFilter_MQTT协议文档.md) 定义；单条记录的故障数据和波形数据不属于实时数据查询，归入 FR-02。

### FR-02 查询与导出录波记录

- 用户能查询目标子设备可获取的录波记录，并选择记录发起获取。
- 系统应区分“请求已被设备应答”“设备报告文件处理结果”和“原始文件已可读取”三个阶段。
- 导出应交付实际录波文件；仅有文件名或逐索引成功标志不满足导出需求。
- 同一次请求包含多个记录时，应能看到每个记录的结果，避免把部分成功显示为全部成功。

- 状态应覆盖“设备已应答”“记录已就绪（`379`）”“平台开始上传（`607`）”“上传完成（`609`）”“已下载”，以及每个阶段的失败或超时。
- 获取到的压缩包应解析出故障数据和波形数据供查看：基本信息、快照通道、多通道波形（原始值），见 [ui-design.md](ui-design.md#31-录波详情抽屉或独立标签页)。
- 导出：用户可任选原始压缩包或 CSV。

**已确定**：可一次获取多条记录，设备打成一个包上传（2026-10-19 用户确认，最多 32 条）；导出原始压缩包或 CSV；导出不设权限；暂不清理。按 FaultFilter 文档，记录列表来自 `cmd=0, code=3` 目录，记录序号即目录项索引；每条记录生成 `failuredata` 与 `waveformdata` 两个文件，设备每次获取记录前会清空历史文件。文件由平台上传后，按 `https://<环境域名>/hes-upload/v1/file/download/logger/<equipNo>/<文件名>.tar.bz2` 下载。功能统一称为“故障录波”。

### FR-03 查询录波参数

- 用户能读取目标子设备的当前故障录波参数，并看到参数 ID、当前值和读取结果。
- 读取结果应来自设备本次返回的数据；本地上次填写的设置值不能冒充设备当前值。

**已确定**：开放功能码 2、4、5、6、7（1、3 为动作，无可读状态）；显示原始十六进制，协议已定义结构的同时显示解读。按 FaultFilter 文档，查询指令为 `cmd=3`，`idList` 可一次填多个功能码（`1～7`），返回 `idInfo[].idData` 十六进制，结构参照对应功能码的设置参数；经外层转发的实际报文待实测。

### FR-04 设置录波参数

- 用户能为指定子设备提交一个或多个参数 ID 与设置值。
- 系统应分别呈现指令应答与逐参数执行结果；仅收到接收应答时，不应声称每项参数已经生效。
- 失败或未确认的参数应能被识别，避免整批请求被误报为全部成功。

**已确定**：提交前弹窗确认，危险操作醒目标注；以 `379` 逐项 `resultOne` 判定结果，可选设置后自动复读。**仍待实测**：`378` 与 `379(cmd=1)` 的实际报文。按 FaultFilter 文档，参数 ID 实为功能码，各功能码的 `setVal` 字节结构已定义；逐项结果为 `setResultList[].resultOne`，整体 `result` 为 `ok`／`error`。

### FR-05 支持测试服和生产服

- 用户发起任一操作时能选择测试服或生产服。
- 同一操作的 MQTT 收发、文件下载和登录凭据都使用所选环境，结果中标明环境。
- 一个环境不可用（未配置、连接失败）时，不影响另一个环境的操作。

### FR-06 操作方式与记录（用户确认，2026-10-16）

- **页面**：主菜单“故障录波”，子菜单分生产服和测试服，再按功能分页面（录波记录、设备信息、功能操作、参数设置）。页面设计见 [ui-design.md](ui-design.md)，用户根据实现效果再提意见。
- **异步**：所有操作异步执行，前端查询进度；服务重启后能自动恢复未完成的操作。
- **多条获取**：一次可获取多条录波记录，设备打成一个包（2026-10-19 用户确认，替换原“每次 1 条”）。
- **设备忙**：本工具内对同一网关串行；设备因其他来源（如 FWH 平台网页）回复 `busy` 时，明确提示用户，不自动重试。
- **取消**：进行中的操作可取消，必要时向设备发送 `cmd=4`（退出）结束当前处理。
- **设备列表**：支持 aGate/MCA、aPower-PE、aPower-MPPT、aHub（即 aPbox）四种设备，来源与判断规则见 [technical-design.md](technical-design.md#5-设备与站点信息)；生产服和测试服调用各自的接口。377 `type` 分别为 `aGate`、`pe`、`mppt`、`apbox`；另有 `dif`（Digital Interface）暂未开放。
- **时间**：目录和录波中的时间暂按设备时间原样显示，测试有问题再改。
- **记录**：操作过程记录在数据库中，原始文件存 MinIO；操作历史所有人共享，并记录操作人。暂不实现数据清理。
- **权限**：功能全部开放；参数设置提交前必须弹窗确认，危险操作醒目标注。
- **导出**：用户可任选导出原始压缩包或 CSV。
- **与 DataDownload**：本功能完整实现并测试通过后，再考虑开放给 DataDownload；DataDownload 暂时继续使用原 FWH API 方案。
- **数据展示**：录波数据只显示原始值和通道含义代码，不做物理量换算。

### FR-07 功能码划分（用户确认，2026-10-16）

- **功能操作**页：1 清除波形、3 手动触发、4 设备对时、7 录波开关。1、3 只执行；4、7 用 `cmd=3` 读取、`cmd=1` 设置。
- **参数设置**页：5 采样频率、6 可配采样通道，读取和复读改用 `cmd=0`（code=2／code=1）。
- **功能码 2**（采样通道配置）设备端暂未实现，暂不开放。
- 原“参数读取”页取消，由上述两页各自附带读取。FR-03 的读取需求按此落实。

## 3. 共同需求

- 每次操作应保留目标网关、子设备类型/SN、所请求的 `code`／`index`／参数 ID，以及设备返回的原始结果，便于排查请求与上传不一致的问题。
- 请求超时、设备拒绝、上传失败、单项失败、文件缺失和报文无法关联应分别呈现，不合并成笼统的“成功/失败”。
- 设备类型的可选值及大小写应以真实协议验证；当前样本不能证明所有类型都能使用这四项能力。
- 并发操作不能互相误认上传结果：本工具内同一网关串行，关联规则见 [technical-design.md](technical-design.md#44-关联规则)。

## 4. 验收前需确定的事项

| 功能 | 必须取得的证据或决策 |
| --- | --- |
| 实时数据 | `code=3` 已验证；`code=1/2` 实报；可见输出形式 |
| 记录查询 | 查询条件（目录来源与 `index` 映射已明确） |
| 文件导出 | 平台对本工具直连发出的 `cmd=2` 同样自动上传（下载认证、压缩包结构已确认） |
| 双环境 | 测试服与生产服各完成一次完整的 `cmd=2` 获取与下载 |
| 功能操作读取 | 4、7 的 `cmd=3` 实报样本 |
| 参数设置 | `cmd=1` 完整成功及失败样本、最终成功条件 |
| 通用收发 | `379/380` topic、消息关联、超时与重发行为 |