# 平台基础审计调查接口

本文冻结 `build-multi-view-audit-center` 任务 2.4 的接口、业务页面参数来源和降级规则。字段路径均位于统一响应的 `response.data` 下；列表字段位于 `items[]`。

## 基础接口

| 视角 | 接口 | 参数来源 |
|---|---|---|
| 全局事件 | `GET /api/admin/audit/events` | 调查筛选区或其他节点携带的稳定筛选值 |
| 事件详情 | `GET /api/admin/audit/events/{event_id}` | `investigation_refs.event_id` 或人工粘贴的稳定 ID |
| 操作者 | `GET /api/admin/audit/actors/{kind}/{id}/events` | `investigation_refs.actor_ref` 或平台账号选择器 |
| 资源搜索 | `GET /api/admin/audit/resources/search` | 调查人员选择类型并输入精确业务标识 |
| 资源时间线 | `GET /api/admin/audit/resources/{resource_type}/{resource_id}/timeline` | 业务响应稳定 ID、资源搜索结果或 `investigation_refs.resource_refs[]` |
| 请求链路 | `GET /api/admin/audit/requests/{request_id}/timeline` | 节点 `request_id` 或开发人员从 Access Log 粘贴 |
| 业务链路 | `GET /api/admin/audit/correlations/{correlation_id}/timeline` | 节点或业务详情中的稳定 `correlation_id` |
| 资金时间线 | `GET /api/admin/audit/finance/timeline` | 店铺、钱包、订单、支付、退款、充值、审批、交易号、操作者、时间或 correlation |
| 风险总览/明细 | `GET /api/admin/audit/risks/overview`、`GET /api/admin/audit/risks/events` | 调查时间范围及风险分桶稳定筛选 |

认证身份和数据范围只来自认证上下文，不接受 query/path/body 伪造。接口仅允许超级管理员和平台账号访问，全部为 GET，不提供导出、修改、删除、恢复或处置能力。

## 资产与组织页面映射

| 前置接口 | 稳定字段 | 平台目标 |
|---|---|---|
| 卡列表 `/iot-cards/standalone` | `id` | `iot_card/{id}` |
| 设备列表 `/devices` | `id` | `device/{id}` |
| 设备卡槽 `/devices/{virtual_no}/cards` | `bindings[].iot_card_id`、`bindings[].id` | `iot_card/{iot_card_id}`、`device_sim_binding/{id}` |
| 统一资产 `/assets/resolve/{identifier}` | `asset_type`、`asset_id`、绑定资产 ID | `card` 转换为 `iot_card/{asset_id}`；`device` 使用 `device/{asset_id}` |
| 分配列表/详情 `/asset-allocation-records[/{id}]` | `id`、`asset_type`、`asset_id`、`related_device_id`、`related_card_ids[]` | `asset_allocation_record/{id}` 及相应资产资源 ID；接口已返回的 `iot_card/device` 不再转换 |
| 换货列表/详情 `/exchanges[/{id}]` | `id`、旧/新 `asset_type` 与 `asset_id` | `exchange_order/{id}` 及旧、新资产资源 ID |
| 店铺列表/详情 `/shops[/{id}]` | `id` | `shop/{id}` |
| 企业列表 `/enterprises` | `id` | `enterprise/{id}`；不得假设存在企业详情接口 |
| 企业卡列表 `/enterprises/{id}/cards` | `items[].id` | `iot_card/{id}` |
| 企业设备列表 `/enterprises/{id}/devices` | `items[].device_id` | `device/{device_id}` |

## 交易与资金页面映射

| 前置接口 | 稳定字段 | 平台目标 |
|---|---|---|
| 账号列表/详情 `/accounts[/{id}]` | `id` | `account/{id}` |
| 订单列表/详情 `/orders[/{id}]` | `id` | `order/{id}`；资金视角使用 `order_id={id}` |
| 退款列表/详情 `/refunds[/{id}]` | `id`、`approval_instance_id` | `refund/{id}`；资金视角使用 `refund_id={id}`；审批非空时使用 `approval_instance/{id}` |
| 代理充值列表/详情 `/agent-recharges[/{id}]` | `id` | `agent_recharge/{id}`；资金视角使用 `recharge_id={id}` |
| 代理在线充值创建结果 | `recharge_id`、`payment_no` | 资金视角以 `recharge_id` 为第一跳，`payment_no` 仅作额外精确筛选 |
| 资产钱包 `/assets/{identifier}/wallet` | `wallet_id`、`resource_type`、`resource_id` | 资金视角使用 `wallet_id`；资产审计使用 `{resource_type}/{resource_id}` |
| 店铺资金概况 `/shops/fund-summary` | `items[].shop_id` | 资金视角使用 `shop_id` |
| 店铺主钱包流水 | path `shop_id`、资产类型与 ID | 资金视角使用 `shop_id`；资产 ID 存在时使用对应资源时间线 |
| 资产钱包流水 | 上层 `wallet_id` | 资金视角使用 `wallet_id`；不解析业务编号前缀猜测资源 |

资金视角已交付；缺失的支付、退款、钱包等关联由服务端 Query 解析。完整逐页面映射和调用链见[跨视角调查与前端导航契约](跨视角调查与前端导航契约.md)。

## 统一调查引用

平台调查节点统一返回 `investigation_refs`：可空 `event_id`、可空 `actor_ref{kind,id}`、`resource_refs[]{resource_type,resource_id,resource_key,display_name}`、可空 `request_id`、可空 `correlation_id` 和 `integration_refs[]{integration_id}`。前端只使用存在的稳定引用，不解析中文名称、备注、编号前缀或相近时间推断关系。

## 降级规则

- 缺少目标接口必需的稳定 ID 或 identifier 时隐藏入口。
- 只有 Registry Key、没有内部 ID 时先精确资源搜索；零命中或多命中均不自动选择。
- 已删除资源只要节点保留 `resource_type/resource_id`，仍可查看事件快照时间线。
- 代理或企业不得回退调用平台审计、资源搜索或旧 operation log。
- 旧 operation log 保持独立历史入口，不拼接到新审计接口。
- 通知先调用 `/notifications/{id}/target`；仅 `available=true` 时按白名单目标继续跳转。