修正数据

docs/add-asset-operation-audit-log/操作内容字段说明.md

@@ -0,0 +1,102 @@
+# 资产审计日志操作内容字段说明
+
+## 1. 查询接口
+
+- 路径：`GET /api/admin/assets/:identifier/operation-logs`
+- 说明：先按资产标识符解析资产，再查询该资产的审计日志。
+
+## 2. 前端应优先使用的字段
+
+为避免历史数据格式差异，前端应优先使用以下三个字段：
+
+1. `operation_content_before`：操作内容（变更前）
+2. `operation_content_after`：操作内容（变更后）
+3. `operation_fields_desc`：字段中文说明（`key=字段名`，`value=中文解释`）
+
+`before_data/after_data` 保留为原始审计数据，建议仅作为调试或回放使用。
+
+## 3. 通用字段
+
+| 字段 | 说明 |
+|---|---|
+| `operator_type` | 操作人类型中文名称（如平台用户、代理账号、企业账号、个人客户、系统） |
+| `operator_type_code` | 操作人类型编码（如 `admin_user`、`agent_user`） |
+| `operator_name` | 操作人可读名称，优先返回用户名/店铺名/企业名/客户昵称 |
+| `batch_total` | 批量总数 |
+| `success_count` | 成功数量 |
+| `fail_count` | 失败数量 |
+| `failed_items` | 失败明细 |
+| `reason` | 原因说明 |
+
+## 4. 常见操作字段
+
+### 4.1 分配/回收
+
+| 字段 | 说明 |
+|---|---|
+| `target_shop_id` / `to_shop_id` | 目标店铺ID |
+| `source_shop_id` / `from_shop_id` | 来源店铺ID |
+| `device_ids` | 设备ID列表 |
+| `card_ids` | 卡ID列表 |
+| `selection_type` | 选择方式 |
+| `new_status` | 变更后状态 |
+
+### 4.2 设备绑卡/解绑
+
+| 字段 | 说明 |
+|---|---|
+| `binding_id` | 绑定记录ID |
+| `slot_position` | 插槽位置 |
+| `iot_card_id` | 卡ID |
+| `iccid` | 卡ICCID |
+| `unbind` | 是否执行解绑 |
+
+### 4.3 设备停复机
+
+| 字段 | 说明 |
+|---|---|
+| `success_count` | 成功数量 |
+| `fail_count` | 失败数量 |
+| `skip_count` | 跳过数量 |
+| `failed_items` | 失败明细（含ICCID和原因） |
+
+### 4.4 远程控制
+
+| 字段 | 说明 |
+|---|---|
+| `speed_limit` | 限速值（KB/s） |
+| `ssid` | WiFi 名称 |
+| `password` | WiFi 密码（已脱敏） |
+| `enabled` | WiFi 开关状态 |
+| `target_iccid` | 目标ICCID |
+| `switch_mode` | 切卡模式（0自动/1手动） |
+
+### 4.5 轮询与实名
+
+| 字段 | 说明 |
+|---|---|
+| `enable_polling` | 轮询开关 |
+| `realname_policy` | 实名策略（none/before_order/after_order） |
+| `real_name_status` | 实名状态（0未实名/1已实名） |
+
+## 5. 兼容性说明
+
+历史日志中 `before_data` 可能是资产快照而不是操作内容。接口已做归一化处理：
+
+- 自动抽取并返回 `operation_content_before/after`
+- 当历史数据缺少“变更前操作内容”时，会按“变更后字段”与资产快照尽量回填
+- 历史日志中的 `后台用户#ID`、`代理用户#ID` 等占位名称，接口会尽量按当前账号资料补全为可读名称
+
+因此，前端无需再自行解析 `before_data/after_data` 的多种历史格式。
+
+## 6. 前端处理建议
+
+建议前端按以下优先级渲染变更明细：
+
+1. 遍历 `operation_content_after` 的字段键作为“变更项集合”
+2. 字段名展示优先使用 `operation_fields_desc[key]`，没有则回退为 `key`
+3. 变更前值读取 `operation_content_before[key]`
+4. 变更后值读取 `operation_content_after[key]`
+5. 当前值为 `null` 时按“未知/未记录”展示，不要直接当空字符串
+
+`before_data/after_data` 建议只用于问题排查，不参与主界面渲染。