保留提案基线以便团队 worktree 按契约执行

Constraint: omx team 默认使用独立 worktree，要求 leader 工作区干净
Rejected: git stash 提案文件 | 会让 worker 无法读取当前提案契约
Confidence: high
Scope-risk: narrow
Directive: 后续实现必须继续严格按 tasks.md 顺序推进，不得擅自跳步
Tested: git status 仅剩未跟踪的 .omx 上下文文件
Not-tested: 未验证提案内容本身的实现正确性

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

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-30

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

@@ -0,0 +1,113 @@
+## Context
+
+当前仓库已经存在资产域审计日志能力，核心入口为 `internal/service/asset_audit`，并由 `iot_card`、`device`、`asset` 等多个 Service 在写操作节点调用。现状问题不是“没有日志”，而是很多 `operation_content` 更偏向研发排障视角，包含大量 `card_id`、`device_id`、`target_shop_id`、`binding_id` 之类的内部主键，对业务人员不友好。
+
+设备实时状态方面，后台管理端通过 `asset.Service.fetchDeviceGatewayInfo()` 从 Gateway 获取完整设备信息，C 端再通过 `mapDeviceGatewayInfoToClientInfo()` 复用该结果。`rsrp`、`rsrq`、`rssi`、`sinr` 已完整透出，但缺少“人能直接看懂”的归纳结论，因此同一问题会在 B 端与 C 端重复解释。
+
+约束如下：
+- 必须遵循 `Handler -> Service -> Store -> Model` 分层，不在 Handler 中拼复杂业务判断。
+- 不新增自动化测试文件，本次仅规划实现与手工验证路径。
+- 审计日志优化必须兼容现有字段，避免破坏现有依赖方。
+- 信号综合字段只新增，不替换或删除原始信号字段。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 让资产操作审计日志的 `before_data/after_data` 在保留内部 ID 的同时，补足业务可读字段。
+- 为设备实时状态新增 `signal_quality` 与 `signal_bad_reason` 两个综合字段。
+- 统一 B 端与 C 端对信号综合字段的输出文案和判定逻辑。
+- 将“怀疑原因”设计为面向小白的提示语，而不是通信指标术语解释。
+
+**Non-Goals:**
+- 不调整店铺删除时“店铺下仍有账号”的业务规则。
+- 不处理“禁用企业账号看不到”的假问题。
+- 不修改现有原始信号字段 `rsrp`、`rsrq`、`rssi`、`sinr` 的保留与含义。
+- 不新增独立的信号诊断接口或独立日志查询接口。
+
+## Decisions
+
+### 决策1：审计日志采用“补充可读字段”而不是“替换内部字段”
+
+**选择**：保留现有 `..._id`、`..._ids`、`target_shop_id` 等内部字段，同时补充可读字段，如 `iccid`、`iccids`、`device_virtual_no`、`device_imei`、`shop_name`、`enterprise_name`。
+
+**理由**：
+- 兼容已有日志消费方与排障场景。
+- 业务查看与研发定位可同时满足，不需要二选一。
+- 变更影响更小，不需要迁移历史日志结构。
+
+**备选方案**：直接把内部 ID 字段改写为名称或业务标识。
+**放弃原因**：会损失排障精度，也可能影响已存在的日志解析逻辑。
+
+### 决策2：可读字段在各业务写入点就近补齐
+
+**选择**：在 `iot_card`、`device`、`asset` 等具体业务 Service 组装审计参数时，就近把业务标识和名称补进 `BeforeData` / `AfterData`，`asset_audit` 负责统一封装但不做过度猜测。
+
+**理由**：
+- 具体业务 Service 最清楚当前上下文里哪张卡、哪台设备、哪家店铺是本次操作对象。
+- 避免在 `asset_audit` 层引入大量额外查询和猜测逻辑。
+- 更符合现有项目里“Service 负责业务语义拼装”的边界。
+
+**备选方案**：在 `asset_audit` 中根据 ID 反查名称并自动补全。
+**放弃原因**：会让通用审计层承担过多领域知识，也会增加额外查询成本和隐式行为。
+
+### 决策3：信号综合字段在 B 端统一计算，C 端复用映射结果
+
+**选择**：在后台管理端 Gateway 映射链路中新增统一的信号摘要计算函数，先产出 `DeviceGatewayInfo.signal_quality` 与 `DeviceGatewayInfo.signal_bad_reason`，再由 C 端映射函数直接透传。
+
+**理由**：
+- 避免 B 端和 C 端分别实现一套阈值和文案，造成口径漂移。
+- 现有 C 端本来就是从 B 端 DTO 映射，复用成本最低。
+- 未来如果要调阈值或文案，只需要维护一处。
+
+**备选方案**：B 端与 C 端各自计算。
+**放弃原因**：重复逻辑多，后续难保证一致。
+
+### 决策4：信号综合字段采用“结果 + 怀疑原因”的轻量模型
+
+**选择**：
+- `signal_quality` 使用固定的用户可读枚举：`信号很好 / 信号正常 / 信号较弱 / 信号很差 / 暂无数据`
+- `signal_bad_reason` 使用怀疑式提示语：`怀疑当前位置信号覆盖较弱 / 怀疑周围干扰较多 / 怀疑设备所处位置遮挡较强 / 怀疑网络环境不稳定 / 暂时无法判断`
+
+**理由**：
+- 适合小白用户快速理解，不要求其理解通信指标定义。
+- “怀疑”语气符合基于多指标估算而非绝对诊断的产品事实。
+- 可在不暴露复杂阈值的前提下给出下一步判断方向。
+
+**备选方案**：直接输出“RSRP 低 / SINR 低 / RSRQ 差”等技术术语。
+**放弃原因**：对非技术用户不友好，无法满足本次需求目标。
+
+### 决策5：信号判定使用固定优先级规则，避免多原因并列
+
+**选择**：当多个原始指标同时异常时，按固定优先级输出单一 `signal_bad_reason`，优先表达最容易被用户理解的问题类型；当数据缺失或不足时输出“暂时无法判断”。
+
+**理由**：
+- 单字段只返回一个原因，前端展示更稳定。
+- 避免一次返回多个原因造成文案冗长和理解负担。
+- 更适合现有 DTO 结构，不需要额外数组字段。
+
+**备选方案**：返回原因列表。
+**放弃原因**：复杂度更高，也不符合“只新增两个字段”的收敛目标。
+
+## Risks / Trade-offs
+
+- **[风险] 审计日志可读字段补充不一致** → **缓解**：在设计中约束“同类资源尽量使用统一字段名”，例如卡统一使用 `iccid`/`iccids`，设备统一使用 `device_virtual_no` 或 `device_imei`。
+- **[风险] 信号怀疑原因与真实现场不完全一致** → **缓解**：文案统一使用“怀疑”语气，并保留原始四个指标供专业人员复核。
+- **[风险] 设备实时 DTO 新增字段后文档未同步** → **缓解**：实现阶段同步更新 DTO 描述与生成文档。
+- **[权衡] 不在审计通用层自动反查名称会保留部分业务代码重复** → **接受**：本次优先保持边界清晰与最小侵入。
+
+## Migration Plan
+
+1. 在变更目录中明确审计日志与信号摘要的规格要求。
+2. 实现阶段先补充 B 端设备实时 DTO 与统一信号摘要函数，再同步 C 端映射。
+3. 分批调整资产审计日志主要写入点，优先覆盖当前已确认大量写入内部主键的链路。
+4. 生成并检查接口文档，确认新增字段在后台管理端与 C 端响应中可见。
+5. 通过手工接口调用与数据库日志抽样确认行为符合预期。
+
+**回滚策略：**
+- 若信号摘要文案或阈值不符合预期，可仅回滚摘要计算与 DTO 新字段，不影响原始四个指标。
+- 若审计日志可读字段补充引发问题，可回滚具体写入点变更，保留现有日志表与基础审计能力。
+
+## Open Questions
+
+- `signal_bad_reason` 的优先级阈值最终是否需要沉淀到 `pkg/constants` 作为可复用常量，还是先在单一计算函数中集中维护。
+- 审计日志中店铺相关字段是否统一使用 `shop_name`，还是区分 `source_shop_name` / `target_shop_name` 以更明确表达分配回收语义。

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

@@ -0,0 +1,26 @@
+## Why
+
+当前资产操作审计日志虽然已经落库，但很多操作内容仍主要记录内部主键 ID，业务侧排查时很难直接看懂“到底操作了哪张卡、哪台设备、哪家店铺”。同时，设备实时状态里虽然已有 `rsrp`、`rsrq`、`rssi`、`sinr` 四个原始指标，但一线使用人员难以理解，影响 C 端与后台管理端对设备信号状态的快速判断。
+
+## What Changes
+
+- 新增 `feature-001-asset-audit-readable-content`：优化资产操作审计日志的操作内容结构，在保留内部 ID 的同时补充业务可读字段，如 `iccid`、设备标识、店铺名称、企业名称等。
+- 新增 `feature-002-device-signal-summary`：基于设备实时状态中的 `rsrp`、`rsrq`、`rssi`、`sinr` 计算两个新的综合字段，分别表达“信号好坏”和“怀疑原因”。
+- 统一后台管理端与 C 端设备实时信息输出口径，确保两个新增信号字段在两端含义一致。
+- 明确本次变更不处理店铺删除规则，也不处理企业账号列表过滤问题，避免需求范围漂移。
+
+## Capabilities
+
+### New Capabilities
+- `asset-audit-readable-content`: 定义资产操作审计日志中面向业务可读的操作内容字段要求与展示语义。
+- `device-signal-summary`: 定义设备实时信号综合字段的计算输出、文案口径与 B/C 端返回要求。
+
+### Modified Capabilities
+- 无
+
+## Impact
+
+- 影响资产审计日志相关服务与写入点，主要涉及 `internal/service/asset_audit`、`internal/service/iot_card`、`internal/service/device`、`internal/service/asset`。
+- 影响设备实时状态 DTO 与映射逻辑，主要涉及 `internal/model/dto/asset_dto.go`、`internal/model/dto/client_asset_dto.go`、`internal/service/asset/service.go`、`internal/handler/app/client_asset.go`。
+- 影响后台管理端与 C 端既有响应结构，但属于向后兼容的新增字段，不引入破坏性变更。
+- 无新增外部依赖、无新增数据表、无新增路由。

openspec/changes/improve-audit-log-readability-and-signal-summary/specs/asset-audit-readable-content/spec.md

@@ -0,0 +1,49 @@
+## ADDED 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/changes/improve-audit-log-readability-and-signal-summary/specs/device-signal-summary/spec.md

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

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

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