故障录波功能需求

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

1. 目标与范围

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

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

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

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

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

2. 功能需求

FR-01 查询实时数据

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

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

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

用户能查询目标子设备可获取的录波记录，并选择记录发起获取。
系统应区分“请求已被设备应答”“设备报告文件处理结果”和“原始文件已可读取”三个阶段。
导出应交付实际录波文件；仅有文件名或逐索引成功标志不满足导出需求。
同一次请求包含多个记录时，应能看到每个记录的结果，避免把部分成功显示为全部成功。
状态应覆盖“设备已应答”“记录已就绪（379）”“平台开始上传（607）”“上传完成（609）”“已下载”，以及每个阶段的失败或超时。
获取到的压缩包应解析出故障数据和波形数据供查看：基本信息、快照通道、多通道波形（原始值），见 ui-design.md。
导出：用户可任选原始压缩包或 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，用户根据实现效果再提意见。
异步：所有操作异步执行，前端查询进度；服务重启后能自动恢复未完成的操作。
多条获取：一次可获取多条录波记录，设备打成一个包（2026-10-19 用户确认，替换原“每次 1 条”）。
设备忙：本工具内对同一网关串行；设备因其他来源（如 FWH 平台网页）回复 busy 时，明确提示用户，不自动重试。
取消：进行中的操作可取消，必要时向设备发送 cmd=4（退出）结束当前处理。
设备列表：支持 aGate/MCA、aPower-PE、aPower-MPPT、aHub（即 aPbox）四种设备，来源与判断规则见 technical-design.md；生产服和测试服调用各自的接口。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。

4. 验收前需确定的事项

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

requirements.md 9.0 KB 履歴 Raw