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

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 账号列表接口的企业账号展示逻辑不因审计日志优化而发生变化