归档

openspec/specs/asset-audit-readable-content/spec.md

@@ -0,0 +1,53 @@
+# asset-audit-readable-content Specification
+
+## Purpose
+TBD - created by archiving change improve-audit-log-readability-and-signal-summary. Update Purpose after archive.
+## Requirements
+### Requirement: 资产操作审计日志必须补充业务可读字段
+系统 SHALL 在资产操作审计日志中保留现有内部主键字段，同时 MUST 为关键操作对象补充业务可读字段，确保业务侧无需查库即可理解操作内容。
+
+#### Scenario: 卡相关日志补充 ICCID
+- **WHEN** 系统记录针对单卡或多卡的分配、回收、删除、实名、停复机等操作日志
+- **THEN** `before_data` 或 `after_data` 除内部卡 ID 外，还包含对应的 `iccid` 或 `iccids`
+
+#### Scenario: 设备相关日志补充设备标识
+- **WHEN** 系统记录设备绑定、解绑、切卡、远程控制、删除等操作日志
+- **THEN** `before_data` 或 `after_data` 除内部设备 ID 外，还包含至少一种业务可读设备标识，如虚拟号、IMEI 或 SN
+
+#### Scenario: 店铺相关日志补充店铺名称
+- **WHEN** 系统记录资产分配、资产回收或归属变更类日志
+- **THEN** `before_data` 或 `after_data` 在店铺 ID 之外还包含相应店铺名称，便于直接识别归属变化
+
+### Requirement: 审计日志可读字段必须遵循兼容新增原则
+系统 SHALL 以向后兼容方式扩展资产审计日志内容，不得通过删除现有内部字段来换取可读性。
+
+#### Scenario: 现有内部字段仍然保留
+- **WHEN** 系统为审计日志补充可读字段
+- **THEN** 现有 `card_id`、`device_id`、`target_shop_id`、`binding_id` 等内部字段仍然保留，不被移除或重命名
+
+#### Scenario: 新增字段不影响旧日志读取
+- **WHEN** 现有日志消费方继续读取资产操作日志
+- **THEN** 旧字段结构保持可用，新增可读字段仅作为补充信息出现
+
+### Requirement: 同类审计场景必须使用统一的可读字段命名
+系统 SHALL 在同类资产审计场景中使用稳定一致的可读字段命名，避免同一语义在不同日志里出现多套字段名。
+
+#### Scenario: 单卡与批量卡操作字段一致
+- **WHEN** 系统分别记录单卡操作和批量卡操作日志
+- **THEN** 单卡场景使用 `iccid`，批量场景使用 `iccids` 或卡对象列表中的 `iccid` 字段，命名保持一致
+
+#### Scenario: 设备相关可读字段命名稳定
+- **WHEN** 系统记录多个设备相关操作日志
+- **THEN** 设备业务标识字段使用统一命名，不在不同接口间随意切换字段语义
+
+### Requirement: 审计日志补充可读字段不得引入额外破坏性变更
+系统 SHALL 仅增强资产审计日志的可读性，不得借本次变更调整店铺删除规则、账号过滤规则或其他无关业务行为。
+
+#### Scenario: 店铺删除规则保持不变
+- **WHEN** 本次变更上线
+- **THEN** 店铺删除相关业务规则不因审计日志优化而发生变化
+
+#### Scenario: 企业账号列表行为保持不变
+- **WHEN** 本次变更上线
+- **THEN** 账号列表接口的企业账号展示逻辑不因审计日志优化而发生变化
+

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

@@ -0,0 +1,69 @@
+# 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 端返回结果
+