junhong_cmp_fiber/docs/add-asset-operation-audit-log/功能总结.md

资产操作审计日志功能总结

1. 功能目标

为资产域（IoT 卡/设备）补齐统一审计落库能力，解决“谁在什么时间对哪个资产做了什么变更、结果如何”的追溯问题。

2. 数据模型与落库

• 新增表：tb_asset_operation_log
• 关键字段：
  • 操作人：operator_id/operator_type/operator_name
  • 资产：asset_type/asset_id/asset_identifier
  • 操作：operation_type/operation_desc
  • 镜像：before_data/after_data（JSONB）
  • 请求上下文：request_id/ip_address/user_agent/request_path/request_method
  • 结果：result_status/error_code/error_msg
  • 批量统计：batch_total/success_count/fail_count
• 索引：
  • idx_asset_log_asset_created
  • idx_asset_log_identifier_created
  • idx_asset_log_operator_created
  • idx_asset_log_operation_created
  • idx_asset_log_result_created

3. 统一封装设计

3.1 基础设施统一入口

• internal/service/asset_audit/service.go
  • 统一 LogOperation(ctx, log) 异步写入
  • 写入失败只打 Error 日志，不阻断业务
• internal/service/asset_audit/builder.go
  • 统一组装 before/after、请求上下文、错误码摘要
  • 统一脱敏与裁剪

3.2 业务侧统一 helper

• IoT 卡：internal/service/iot_card/audit.go
• 设备：internal/service/device/audit.go
• 统一资产入口轮询：internal/service/polling/asset_polling_service.go 内部 helper
• 资产停用：internal/service/asset/lifecycle_service.go 内部 helper
• 导入任务：
  • internal/service/device_import/audit.go
  • internal/service/iot_card_import/audit.go

业务函数只传结构化参数，避免日志拼装散落在各分支。

4. 覆盖范围

4.1 IoT 卡

• 分配/回收、系列绑定、轮询开关、实名策略、手动实名状态、删除/批量删除
• 自动停复机 + 手动停复机（含 denied/failed）

4.2 设备

• 删除、分配/回收、系列绑定、绑卡/解绑
• 设备停机/复机（含成功数、失败数、失败摘要）
• 远程控制：限速、WiFi、切卡、切卡模式、重启、恢复出厂

4.3 统一资产入口与导入

• 统一入口：停用、轮询状态、实名策略
• 导入任务创建：设备导入、卡导入

5. 脱敏与体积控制

• 敏感键脱敏：password/passwd/pwd/secret/token/wifi_password/wifipwd
• WiFi 场景使用 password 键传参，落库前统一掩码处理
• before_data/after_data 超过阈值时裁剪并标记 _truncated=true

6. 查询与排障示例

6.1 审计日志查询 API（前端）

• 路径：GET /api/admin/assets/:identifier/operation-logs
• 操作人相关字段：
  • operator_type 返回中文标准文案（如平台用户、代理账号、企业账号、个人客户、系统）
  • operator_type_code 保留底层枚举编码（如 admin_user、agent_user）
  • operator_name 优先返回可读名称，历史 类型#ID 占位值会在查询时尽量补全
• 建议前端优先使用：
  • operation_content_before（操作内容变更前）
  • operation_content_after（操作内容变更后）
  • operation_fields_desc（字段中文说明）
• 原始字段 before_data/after_data 建议仅用于调试回放。
• 字段明细文档：docs/add-asset-operation-audit-log/操作内容字段说明.md

6.2 SQL 排障示例

完整 SQL 见：

• docs/add-asset-operation-audit-log/手工验收脚本.sql

常用排障问题：

1. 某资产最近操作：按 asset_type + asset_id 查询
2. 某操作人近期高风险动作：按 operator_id + result_status in ('failed','denied')
3. WiFi 明文泄露检查：检索 after_data::text ILIKE '%\"password\":\"%' 并人工确认是否掩码