归档

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 记录本次变更的手工验证结果与剩余风险，保证提案可直接进入实现阶段