|
|
# 实时故障显示需求说明
|
|
|
|
|
|
日期：2026-07-23
|
|
|
|
|
|
来源：`新需求.png`
|
|
|
|
|
|
## 需求目标
|
|
|
|
|
|
当前故障需要在实时监控页即时、准确、明确地显示出来，不能再依赖 10 分钟一次的历史扫描后才出现在报警预览中。
|
|
|
|
|
|
本次需求涉及四块：
|
|
|
|
|
|
1. 0x17 回路分控器参数解析调整
|
|
|
2. 实时监控页新增当前故障显示
|
|
|
3. 报警预览历史记录即时写入
|
|
|
4. 未定义回路不参与轮询
|
|
|
|
|
|
## 当前问题
|
|
|
|
|
|
### 实时监控页没有故障信息
|
|
|
|
|
|
当前实时监控页只展示回路开关状态、电压、电流、功率、调光值等信息，没有展示当前故障条目。
|
|
|
|
|
|
结果是：即使设备已经返回故障，用户也无法在实时监控页直接看到。
|
|
|
|
|
|
### 报警预览显示太慢
|
|
|
|
|
|
后台当前通过 `ScanM9z` 定时扫描故障，定时周期是 10 分钟：
|
|
|
|
|
|
```go
|
|
|
AddTaskByFunc("ScanM9z", "ScanM9z", "@every 10m", m9zTtyApi.ScanM9z)
|
|
|
```
|
|
|
|
|
|
所以用户看到“十几分钟后报警预览才有故障内容”，和当前代码行为一致。
|
|
|
|
|
|
### 故障文案不够准确
|
|
|
|
|
|
当前故障文案包含：
|
|
|
|
|
|
```text
|
|
|
欠压/短路故障
|
|
|
过压/开路故障
|
|
|
电源故障
|
|
|
未知异常
|
|
|
```
|
|
|
|
|
|
新需求要求按实际故障类型显示，不再混用“欠压/过压”描述。
|
|
|
|
|
|
### 回路电流解析需要调整
|
|
|
|
|
|
当前 0x17 解析中，回路总电流按 `0.1A` 处理。
|
|
|
|
|
|
新需求示例：
|
|
|
|
|
|
```text
|
|
|
01 BF = 0.447A
|
|
|
```
|
|
|
|
|
|
也就是 `0x01BF = 447`，应按 `0.001A` 解析。
|
|
|
|
|
|
## 当前故障显示区域
|
|
|
|
|
|
“当前故障显示区域”指实时监控页上一块专门展示当前故障的区域。
|
|
|
|
|
|
它不是历史报警列表，也不是报警预览页，而是当前设备正在发生的故障提示。
|
|
|
|
|
|
建议位置：
|
|
|
|
|
|
```text
|
|
|
实时监控页右上方空白区域
|
|
|
或实时监控页底部空白区域
|
|
|
```
|
|
|
|
|
|
建议显示内容：
|
|
|
|
|
|
```text
|
|
|
当前故障：
|
|
|
回路1短路故障
|
|
|
回路2开路故障
|
|
|
回路3设备1/2电源故障
|
|
|
```
|
|
|
|
|
|
没有故障时显示：
|
|
|
|
|
|
```text
|
|
|
当前无故障
|
|
|
```
|
|
|
|
|
|
建议在该区域增加一个手动刷新按钮：
|
|
|
|
|
|
```text
|
|
|
刷新当前故障
|
|
|
```
|
|
|
|
|
|
按钮用途：
|
|
|
|
|
|
1. 现场人员可以立即重新读取当前故障，不必等待下一次自动刷新
|
|
|
2. 调试和验收时可以快速确认故障是否已恢复
|
|
|
3. 当通信短暂异常或页面刚恢复时，可以主动刷新当前状态
|
|
|
|
|
|
交互建议：
|
|
|
|
|
|
1. 点击后调用实时监控接口重新读取当前故障
|
|
|
2. 按钮请求期间显示 loading 或禁用，避免连续点击造成串口请求堆积
|
|
|
3. 刷新成功后更新当前故障区域
|
|
|
4. 刷新失败时提示“当前故障刷新失败”或保留原状态并显示错误提示
|
|
|
|
|
|
每条故障建议包含：
|
|
|
|
|
|
| 字段 | 说明 |
|
|
|
| --- | --- |
|
|
|
| 回路号 | 例如：回路1、回路2 |
|
|
|
| 故障类型 | 短路故障、开路故障、电源故障 |
|
|
|
| 设备号 | 仅电源故障需要显示，例如：设备1、设备2 |
|
|
|
| 故障码 | 可选显示，例如：01、02、04 01、04 03 |
|
|
|
|
|
|
## 故障码解析规则
|
|
|
|
|
|
0x17 返回的故障码按以下规则解析：
|
|
|
|
|
|
| 故障码 | 含义 | 显示文案 |
|
|
|
| --- | --- | --- |
|
|
|
| `0x01` | 短路故障 | 回路n短路故障 |
|
|
|
| `0x02` | 开路故障 | 回路n开路故障 |
|
|
|
| `0x04 + 设备掩码` | 电源故障 | 回路n设备x电源故障 |
|
|
|
|
|
|
电源故障示例：
|
|
|
|
|
|
| 故障码 | 含义 | 显示文案 |
|
|
|
| --- | --- | --- |
|
|
|
| `04 01` | 设备1电源故障 | 回路n设备1电源故障 |
|
|
|
| `04 02` | 设备2电源故障 | 回路n设备2电源故障 |
|
|
|
| `04 03` | 设备1/2电源故障 | 回路n设备1/2电源故障 |
|
|
|
|
|
|
如果同一回路同时存在多类故障，应拆成多条故障显示，或合并为一条清晰文案。
|
|
|
|
|
|
## 收到故障无需确认
|
|
|
|
|
|
“收到故障无需确认”指设备返回故障数据后，系统直接显示并记录，不弹窗询问用户是否确认。
|
|
|
|
|
|
正确流程：
|
|
|
|
|
|
```text
|
|
|
设备返回故障 -> 后端解析 -> 实时监控显示 -> 写入报警历史
|
|
|
```
|
|
|
|
|
|
不需要：
|
|
|
|
|
|
```text
|
|
|
设备返回故障 -> 弹窗问用户是否确认 -> 用户确认后才显示/记录
|
|
|
```
|
|
|
|
|
|
报警预览页里“批量删除”的确认弹窗可以保留，因为它属于用户删除操作确认，不属于故障进入系统前的确认。
|
|
|
|
|
|
## 未定义设备不轮询
|
|
|
|
|
|
当前代码固定轮询 10 个回路：
|
|
|
|
|
|
```go
|
|
|
for i := 0; i < 10; i++ {
|
|
|
// read 0x17
|
|
|
}
|
|
|
```
|
|
|
|
|
|
新需求要求未定义设备不参与轮询。
|
|
|
|
|
|
建议行为：
|
|
|
|
|
|
```text
|
|
|
配置了 4 路：只轮询 0~3
|
|
|
配置了 8 路：只轮询 0~7
|
|
|
配置了 10 路：轮询 0~9
|
|
|
```
|
|
|
|
|
|
好处：
|
|
|
|
|
|
1. 减少串口请求
|
|
|
2. 避免无效设备超时
|
|
|
3. 提升实时监控响应速度
|
|
|
4. 报警预览可以更快出现有效故障
|
|
|
|
|
|
如果暂时没有回路数量配置，建议新增配置项，例如：
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"deviceInfo": {
|
|
|
"loopCount": 10
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
没有配置时默认 `10`，但现场可以按实际回路数量调整。
|
|
|
|
|
|
## 后端改动点
|
|
|
|
|
|
### 1. 调整 0x17 数据解析
|
|
|
|
|
|
文件：
|
|
|
|
|
|
```text
|
|
|
internal/library/m9z/m9z_SubLoopParameters.go
|
|
|
```
|
|
|
|
|
|
改动：
|
|
|
|
|
|
1. 回路总电流从 `0.1A` 比例调整为 `0.001A`
|
|
|
2. 保留 `AlarmStatus` 和 `AlarmCode`
|
|
|
3. 增加结构化故障列表，例如 `Faults []LoopFault`
|
|
|
|
|
|
建议结构：
|
|
|
|
|
|
```go
|
|
|
type LoopFault struct {
|
|
|
LoopIdx uint `json:"loop_idx"`
|
|
|
DeviceIdx uint `json:"device_idx,omitempty"`
|
|
|
Type string `json:"type"`
|
|
|
Message string `json:"message"`
|
|
|
Code string `json:"code"`
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 2. 统一故障文案生成
|
|
|
|
|
|
建议新增公共函数，供实时接口和历史扫描共用：
|
|
|
|
|
|
```go
|
|
|
func BuildLoopFaults(loopIdx uint, alarmStatus uint16, alarmCode string) []LoopFault
|
|
|
```
|
|
|
|
|
|
输出示例：
|
|
|
|
|
|
```text
|
|
|
回路1短路故障
|
|
|
回路2开路故障
|
|
|
回路3设备1/2电源故障
|
|
|
```
|
|
|
|
|
|
### 3. 实时接口返回故障字段
|
|
|
|
|
|
文件：
|
|
|
|
|
|
```text
|
|
|
internal/module/m9zTtyApi/read.go
|
|
|
```
|
|
|
|
|
|
接口：
|
|
|
|
|
|
```text
|
|
|
/m9z/getDeviceStatus2
|
|
|
```
|
|
|
|
|
|
每个回路建议增加字段：
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"has_fault": true,
|
|
|
"fault_msg": "回路1短路故障",
|
|
|
"fault_code": "01",
|
|
|
"faults": []
|
|
|
}
|
|
|
```
|
|
|
|
|
|
同时把实时监控中的回路电流改为直接使用 0x17 的回路总电流字段，不再累加子模块电流。
|
|
|
|
|
|
### 4. 实时写入报警历史
|
|
|
|
|
|
文件：
|
|
|
|
|
|
```text
|
|
|
internal/module/m9zTtyApi/cron.go
|
|
|
```
|
|
|
|
|
|
当前历史报警只由 `ScanM9z` 10 分钟扫描写入。新需求应改为：
|
|
|
|
|
|
```text
|
|
|
实时接口读到故障 -> 立即写入 data/data.json
|
|
|
```
|
|
|
|
|
|
同时需要做去重，避免实时接口每次刷新都重复插入同一条故障。
|
|
|
|
|
|
建议去重维度：
|
|
|
|
|
|
```text
|
|
|
comm_uid + loop_idx + fault_code + fault_msg + 未处理状态
|
|
|
```
|
|
|
|
|
|
### 5. 轮询数量配置化
|
|
|
|
|
|
把以下固定循环：
|
|
|
|
|
|
```go
|
|
|
for i := 0; i < 10; i++ {
|
|
|
}
|
|
|
```
|
|
|
|
|
|
改成：
|
|
|
|
|
|
```go
|
|
|
for i := 0; i < loopCount; i++ {
|
|
|
}
|
|
|
```
|
|
|
|
|
|
`loopCount` 从配置读取，未配置默认 10。
|
|
|
|
|
|
涉及位置：
|
|
|
|
|
|
```text
|
|
|
internal/module/m9zTtyApi/read.go
|
|
|
internal/module/m9zTtyApi/cron.go
|
|
|
```
|
|
|
|
|
|
## 前端改动点
|
|
|
|
|
|
### 1. 实时监控页增加当前故障区域
|
|
|
|
|
|
页面：
|
|
|
|
|
|
```text
|
|
|
实时监控
|
|
|
```
|
|
|
|
|
|
展示：
|
|
|
|
|
|
```text
|
|
|
当前故障：
|
|
|
回路1短路故障
|
|
|
回路2开路故障
|
|
|
```
|
|
|
|
|
|
无故障时：
|
|
|
|
|
|
```text
|
|
|
当前无故障
|
|
|
```
|
|
|
|
|
|
当前故障区域需要提供手动刷新按钮：
|
|
|
|
|
|
```text
|
|
|
刷新当前故障
|
|
|
```
|
|
|
|
|
|
点击后重新调用 `/m9z/getDeviceStatus2`，只刷新实时监控状态和当前故障显示，不需要弹确认框。
|
|
|
|
|
|
按钮请求期间应显示 loading 或禁用，避免连续点击造成重复串口请求。
|
|
|
|
|
|
### 2. 适配实时接口字段
|
|
|
|
|
|
调用接口：
|
|
|
|
|
|
```text
|
|
|
/m9z/getDeviceStatus2
|
|
|
```
|
|
|
|
|
|
读取字段：
|
|
|
|
|
|
```text
|
|
|
Loops[].has_fault
|
|
|
Loops[].fault_msg
|
|
|
Loops[].fault_code
|
|
|
Loops[].faults
|
|
|
```
|
|
|
|
|
|
### 3. 报警预览保持历史列表
|
|
|
|
|
|
页面：
|
|
|
|
|
|
```text
|
|
|
报警预览
|
|
|
```
|
|
|
|
|
|
接口继续使用：
|
|
|
|
|
|
```text
|
|
|
/m9z/fault/list
|
|
|
```
|
|
|
|
|
|
后端实时写入后，用户刷新报警预览即可更快看到记录。
|
|
|
|
|
|
### 4. 删除确认保留
|
|
|
|
|
|
报警预览页的批量删除确认弹窗可以保留。
|
|
|
|
|
|
“收到故障无需确认”只针对故障进入系统，不针对删除操作。
|
|
|
|
|
|
## 建议实施顺序
|
|
|
|
|
|
1. 后端先完成 0x17 解析和故障文案统一
|
|
|
2. 后端改 `/m9z/getDeviceStatus2` 返回当前故障
|
|
|
3. 后端增加实时写入历史和去重
|
|
|
4. 后端增加 `loopCount` 配置
|
|
|
5. 前端实时监控页增加当前故障区域和“刷新当前故障”按钮
|
|
|
6. 前端适配接口字段
|
|
|
7. 联调真实 0x17 报文：`01`、`02`、`04 01`、`04 02`、`04 03`
|
|
|
|
|
|
## 待确认点
|
|
|
|
|
|
1. `loopCount` 放在哪个配置节点：建议放在 `deviceInfo.loopCount`
|
|
|
2. 电源故障的设备掩码最大支持几个设备：目前图片只展示设备1、设备2
|
|
|
3. 同一回路多故障时前端展示为多行，还是合并为一行
|
