diff --git a/openspec/changes/improve-audit-log-readability-and-signal-summary/.openspec.yaml b/openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/.openspec.yaml similarity index 100% rename from openspec/changes/improve-audit-log-readability-and-signal-summary/.openspec.yaml rename to openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/.openspec.yaml diff --git a/openspec/changes/improve-audit-log-readability-and-signal-summary/design.md b/openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/design.md similarity index 86% rename from openspec/changes/improve-audit-log-readability-and-signal-summary/design.md rename to openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/design.md index 0b4366a..e9eff08 100644 --- a/openspec/changes/improve-audit-log-readability-and-signal-summary/design.md +++ b/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 端接口，也未触发新的资产操作写入，因此仍需在联调环境补做新日志样本与接口返回抽样。 diff --git a/openspec/changes/improve-audit-log-readability-and-signal-summary/proposal.md b/openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/proposal.md similarity index 100% rename from openspec/changes/improve-audit-log-readability-and-signal-summary/proposal.md rename to openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/proposal.md diff --git a/openspec/changes/improve-audit-log-readability-and-signal-summary/specs/asset-audit-readable-content/spec.md b/openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/specs/asset-audit-readable-content/spec.md similarity index 100% rename from openspec/changes/improve-audit-log-readability-and-signal-summary/specs/asset-audit-readable-content/spec.md rename to openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/specs/asset-audit-readable-content/spec.md diff --git a/openspec/changes/improve-audit-log-readability-and-signal-summary/specs/device-signal-summary/spec.md b/openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/specs/device-signal-summary/spec.md similarity index 100% rename from openspec/changes/improve-audit-log-readability-and-signal-summary/specs/device-signal-summary/spec.md rename to openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/specs/device-signal-summary/spec.md diff --git a/openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/tasks.md b/openspec/changes/archive/2026-04-30-improve-audit-log-readability-and-signal-summary/tasks.md new file mode 100644 index 0000000..0def972 --- /dev/null +++ b/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，确认新写入日志样本和两端实时接口返回值与本次代码改动一致 +- 现有历史资产审计日志不会自动回填新增可读字段，本次变更只覆盖新的写入结果 diff --git a/openspec/changes/improve-audit-log-readability-and-signal-summary/tasks.md b/openspec/changes/improve-audit-log-readability-and-signal-summary/tasks.md deleted file mode 100644 index fa05945..0000000 --- a/openspec/changes/improve-audit-log-readability-and-signal-summary/tasks.md +++ /dev/null @@ -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 记录本次变更的手工验证结果与剩余风险，保证提案可直接进入实现阶段 diff --git a/openspec/specs/asset-audit-readable-content/spec.md b/openspec/specs/asset-audit-readable-content/spec.md new file mode 100644 index 0000000..87d152d --- /dev/null +++ b/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** 账号列表接口的企业账号展示逻辑不因审计日志优化而发生变化 + diff --git a/openspec/specs/device-signal-summary/spec.md b/openspec/specs/device-signal-summary/spec.md new file mode 100644 index 0000000..b996278 --- /dev/null +++ b/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 端返回结果 +