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

## 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\":\"%'` 并人工确认是否掩码