修正数据

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

@@ -0,0 +1,98 @@
+# 资产操作审计日志功能总结
+
+## 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\":\"%'` 并人工确认是否掩码