huang
fe4c545308
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m55s
99 lines
3.7 KiB
Markdown
99 lines
3.7 KiB
Markdown
# 资产操作审计日志功能总结
|
||
|
||
## 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\":\"%'` 并人工确认是否掩码
|