归档

openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/design.md

@@ -111,3 +111,12 @@
 
 - `signal_bad_reason` 的优先级阈值最终是否需要沉淀到 `pkg/constants` 作为可复用常量，还是先在单一计算函数中集中维护。
 - 审计日志中店铺相关字段是否统一使用 `shop_name`，还是区分 `source_shop_name` / `target_shop_name` 以更明确表达分配回收语义。
+
+## 实施记录（2026-04-30）
+
+- 已覆盖的审计写入主链路：`internal/service/iot_card/service.go` 单卡分配/回收，`internal/service/device/service.go` 设备分配/回收，`internal/service/device/binding.go` 绑卡/解绑，配合 `internal/service/iot_card/audit.go` 与 `internal/service/device/audit.go` 统一补齐可读字段。
+- 审计查询侧已同步扩展字段说明：`internal/service/asset_audit/operation_content.go` 新增 `iccids`、`device_virtual_no`、`device_virtual_nos`、`target_shop_name`、`source_shop_name` 等说明口径。
+- 设备实时状态已统一在 B 端计算 `signal_quality` 与 `signal_bad_reason`，再由 C 端 DTO 复用映射结果。
+- 已完成静态验证：`go build ./...`。
+- 已完成文档验证：`GOCACHE=/tmp/jh-gocache go run cmd/gendocs/main.go`，`docs/admin-openapi.yaml` 中可见 `signal_quality`、`signal_bad_reason` 与新增 DTO 字段。
+- 待补联调验证：当前会话未直接调用后台管理端 / C 端接口，也未触发新的资产操作写入，因此仍需在联调环境补做新日志样本与接口返回抽样。

openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/tasks.md

@@ -0,0 +1,31 @@
+## 1. 审计日志可读性增强
+
+- [x] 1.1 梳理当前资产审计日志主要写入点，标记仍只写内部主键字段的卡、设备、归属变更相关链路
+- [x] 1.2 按卡、设备、店铺归属三类场景补充统一的业务可读字段，保持现有内部字段不删除不改名
+- [x] 1.3 调整资产审计日志操作内容字段描述与归一化逻辑，确保新增可读字段在查询结果中稳定返回
+- [ ] 1.4 通过手工抽样检查典型资产日志记录，确认能直接看出卡标识、设备标识与店铺归属信息
+
+## 2. 设备信号综合字段
+
+- [x] 2.1 为后台管理端设备实时 DTO 新增 `signal_quality` 与 `signal_bad_reason` 字段，并补充中文描述
+- [x] 2.2 实现统一的信号摘要计算逻辑，基于 `rsrp`、`rsrq`、`rssi`、`sinr` 输出固定的用户友好文案
+- [x] 2.3 将后台管理端信号摘要结果映射到 C 端设备实时 DTO，保持两端字段名和文案口径一致
+- [ ] 2.4 手工调用后台管理端与 C 端相关接口，确认新增字段可见且原始四个信号字段仍然保留
+
+## 3. 文档与交付检查
+
+- [x] 3.1 更新相关接口文档或生成产物，确保新增响应字段在文档中可见
+- [x] 3.2 复核本次变更未引入店铺删除规则调整或企业账号列表行为变更
+- [x] 3.3 记录本次变更的手工验证结果与剩余风险，保证提案可直接进入实现阶段
+
+## 验证记录
+
+- 已完成：`go build ./...`
+- 已完成：`GOCACHE=/tmp/jh-gocache go run cmd/gendocs/main.go`
+- 已完成：抽样查询 `tb_asset_operation_log` 近期 `card_allocate/card_recall/device_allocate/device_recall/device_bind_card/device_unbind_card` 记录，确认当前线上历史日志仍以内部字段为主，覆盖面与本次修复范围一致
+- 未完成：未在当前会话内直接调用后台管理端与 C 端接口，也未触发新的资产审计写操作生成新日志样本
+
+## 剩余风险
+
+- 需在可用的联调环境中补做任务 1.4 与 2.4，确认新写入日志样本和两端实时接口返回值与本次代码改动一致
+- 现有历史资产审计日志不会自动回填新增可读字段，本次变更只覆盖新的写入结果

openspec/changes/improve-audit-log-readability-and-signal-summary/tasks.md

@@ -1,19 +0,0 @@
-## 1. 审计日志可读性增强
-
-- [ ] 1.1 梳理当前资产审计日志主要写入点，标记仍只写内部主键字段的卡、设备、归属变更相关链路
-- [ ] 1.2 按卡、设备、店铺归属三类场景补充统一的业务可读字段，保持现有内部字段不删除不改名
-- [ ] 1.3 调整资产审计日志操作内容字段描述与归一化逻辑，确保新增可读字段在查询结果中稳定返回
-- [ ] 1.4 通过手工抽样检查典型资产日志记录，确认能直接看出卡标识、设备标识与店铺归属信息
-
-## 2. 设备信号综合字段
-
-- [ ] 2.1 为后台管理端设备实时 DTO 新增 `signal_quality` 与 `signal_bad_reason` 字段，并补充中文描述
-- [ ] 2.2 实现统一的信号摘要计算逻辑，基于 `rsrp`、`rsrq`、`rssi`、`sinr` 输出固定的用户友好文案
-- [ ] 2.3 将后台管理端信号摘要结果映射到 C 端设备实时 DTO，保持两端字段名和文案口径一致
-- [ ] 2.4 手工调用后台管理端与 C 端相关接口，确认新增字段可见且原始四个信号字段仍然保留
-
-## 3. 文档与交付检查
-
-- [ ] 3.1 更新相关接口文档或生成产物，确保新增响应字段在文档中可见
-- [ ] 3.2 复核本次变更未引入店铺删除规则调整或企业账号列表行为变更
-- [ ] 3.3 记录本次变更的手工验证结果与剩余风险，保证提案可直接进入实现阶段

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