junhong_cmp_fiber/openspec/specs/device-signal-summary/spec.md

device-signal-summary Specification

Purpose

TBD - created by archiving change improve-audit-log-readability-and-signal-summary. Update Purpose after archive.

Requirements

Requirement: 设备实时状态必须新增信号综合字段

系统 SHALL 在设备实时状态响应中保留 rsrp、rsrq、rssi、sinr 四个原始字段，并新增 signal_quality 与 signal_bad_reason 两个综合字段。

Scenario: 后台管理端返回综合字段

• WHEN 管理员查询设备实时状态且 Gateway 返回了信号相关数据
• THEN 响应同时包含原始四个信号字段以及 signal_quality、signal_bad_reason

Scenario: C 端返回综合字段

• WHEN 个人客户查询设备实时状态且 Gateway 返回了信号相关数据
• THEN 响应同时包含原始四个信号字段以及 signal_quality、signal_bad_reason

Requirement: 信号好坏字段必须使用面向小白的固定文案

系统 SHALL 使用固定中文文案表达信号综合好坏，不得直接要求用户理解通信技术指标。

Scenario: 信号很好

• WHEN 多项信号指标显示设备当前网络状态较优
• THEN signal_quality 返回 信号很好

Scenario: 信号正常

• WHEN 信号指标处于可接受区间且未出现明显异常
• THEN signal_quality 返回 信号正常

Scenario: 信号较弱或很差

• WHEN 信号指标显示覆盖、质量或抗干扰能力明显下降
• THEN signal_quality 返回 信号较弱 或 信号很差

Scenario: 数据不足

• WHEN 四个原始信号字段全部缺失或不足以支撑判断
• THEN signal_quality 返回 暂无数据

Requirement: 信号怀疑原因字段必须使用怀疑式提示语

系统 SHALL 使用单一的、面向非专业用户的“怀疑原因”文案解释信号异常，不得直接输出技术术语结论。

Scenario: 覆盖较弱

• WHEN 信号指标更接近覆盖不足问题
• THEN signal_bad_reason 返回 怀疑当前位置信号覆盖较弱

Scenario: 干扰较多

• WHEN 信号指标更接近干扰或质量下降问题
• THEN signal_bad_reason 返回 怀疑周围干扰较多

Scenario: 遮挡较强

• WHEN 信号指标更接近设备所处位置存在遮挡的问题
• THEN signal_bad_reason 返回 怀疑设备所处位置遮挡较强

Scenario: 网络环境不稳定

• WHEN 多项指标波动或组合异常但无法归为单一覆盖问题
• THEN signal_bad_reason 返回 怀疑网络环境不稳定

Scenario: 暂时无法判断

• WHEN 原始数据缺失或组合不足以产出可信原因
• THEN signal_bad_reason 返回 暂时无法判断

Requirement: B 端与 C 端必须复用同一套信号摘要口径

系统 SHALL 在后台管理端统一计算信号综合字段，并由 C 端复用同一结果映射，确保两端口径一致。

Scenario: 两端返回一致文案

• WHEN 同一设备在后台管理端与 C 端分别查询实时状态
• THEN 两端返回的 signal_quality 与 signal_bad_reason 含义一致，不出现口径分叉

Scenario: 调整规则只需修改一处

• WHEN 后续调整信号摘要阈值或文案
• THEN 系统只需修改统一计算逻辑，即可同步影响后台管理端与 C 端返回结果