junhong_cmp_fiber/docs/feature-504-multi-view-audit-center/平台基础审计调查接口.md

平台基础审计调查接口

本文冻结 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 解析。完整 ID 生命周期、逐接口字段、页面映射和调用链见审计链路与前端接入指南。

统一调查引用

平台调查节点统一返回 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 时按白名单目标继续跳转。