# 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 端返回结果