junhong_cmp_fiber/docs/feature-504-multi-view-audit-center/跨视角调查与前端导航契约.md

# 跨视角调查与前端导航契约

本文对应 `build-multi-view-audit-center` 任务 9.5，冻结 request、correlation、资金和风险调查接口，以及现有业务页面进入审计中心的第一跳。所有字段路径均位于统一响应的 `response.data` 下；列表字段位于 `items[]`。本文只定义前端调用契约，不包含前端页面实现。

## 跨视角只读接口

| 视角 | 接口 | 入参来源 | 响应重点 |
|---|---|---|---|
| 请求链路 | `GET /api/admin/audit/requests/{request_id}/timeline` | 审计或 Integration 节点的 `investigation_refs.request_id`，或开发人员从 Access Log 粘贴 | `request_id`、`access_log_lookup_request_id`、`nodes[]` |
| 业务链路 | `GET /api/admin/audit/correlations/{correlation_id}/timeline` | 审计、Integration、Outbox、任务或业务详情中的稳定 correlation | `correlation_id`、`nodes[]` |
| 资金时间线 | `GET /api/admin/audit/finance/timeline` | 业务页面稳定 ID、调查节点引用或调查人员输入 | 分页 `items[]`、事实来源、金额权威、`investigation_refs` |
| 风险总览 | `GET /api/admin/audit/risks/overview` | 调查人员选择的 RFC3339 时间范围及可选筛选，最长 31 天 | 信号、风险、结果、动作、来源和趋势 |
| 风险明细 | `GET /api/admin/audit/risks/events` | 风险总览分桶携带相同筛选，或调查人员输入 | 分页风险事件及 `investigation_refs` |

以上接口仅允许超级管理员和平台账号访问，全部为 GET。认证身份只来自认证上下文；不提供导出、修改、删除、风险处置、自动封禁、重试、补偿或恢复能力。

## 资产和组织页面逐行导航

| 源页面 | 前置接口 | `response.data` 稳定字段 | 入口名称与可见条件 | 目标接口与参数映射 | 降级行为 |
|---|---|---|---|---|---|
| 卡列表 | `GET /api/admin/iot-cards/standalone` | `items[].id/iccid/virtual_no/shop_id/device_virtual_no/authorized_enterprise_id` | 平台显示“审计记录”，要求 `id` 非零；代理显示“活动记录”，要求 `iccid` 非空；企业不从此列表进入 | 平台：`/audit/resources/iot_card/{id}/timeline`；代理：`/agent/resource-activities/iot_card/{iccid}` | 缺少对应 ID/ICCID 时隐藏；企业改从企业卡列表进入 |
| 设备列表 | `GET /api/admin/devices` | `items[].id/virtual_no/imei/sn/shop_id/bound_card_count/authorized_enterprise_id` | 平台要求 `id`；代理要求 `virtual_no`；企业不从此列表进入 | 平台：`/audit/resources/device/{id}/timeline`；代理：`/agent/resource-activities/device/{virtual_no}` | 缺少字段时隐藏；企业改从企业设备列表进入 |
| 设备卡槽 | `GET /api/admin/devices/{virtual_no}/cards` | `bindings[].id/iot_card_id/iccid/slot_position/is_current` | 平台可分别查看卡和绑定审计，要求相应 ID；代理可查看卡活动，要求 ICCID；企业仅在设备和卡均有效授权时显示卡活动 | 平台卡：`iot_card/{iot_card_id}`；平台绑定：`device_sim_binding/{bindings[].id}`；代理/企业卡：`iot_card/{iccid}` 的主体活动接口 | 不用绑定 ID 证明授权；设备时间线继续使用上层设备 ID/VirtualNo |
| 统一资产详情 | `GET /api/admin/assets/resolve/{identifier}` | `asset_type/asset_id/identifier/virtual_no/iccid/bound_device_id/cards[].card_id/exchange_trace[].asset_id/can_view` | 平台在 `asset_id` 存在时显示“审计记录”；代理在卡 ICCID 或设备 VirtualNo 存在时显示“活动记录”；企业不显示 | 平台：`card→iot_card/{asset_id}`、`device→device/{asset_id}`；代理：卡用 `iot_card/{iccid}`、设备用 `device/{virtual_no}` | 缺稳定字段时隐藏；换货轨迹仅 `can_view=true` 且资产 ID 存在时跳转；企业不得回退调用 resolve |
| 资产分配列表/详情 | `GET /api/admin/asset-allocation-records[/{id}]` | `items[].id/allocation_no/asset_type/asset_id/asset_identifier/from_owner_type/from_owner_id/to_owner_type/to_owner_id/related_device_id`；详情另有 `related_card_ids[]` | 平台要求记录或资产 ID；代理要求 `allocation_no` 且当前关联资产或店铺仍在范围内；企业无独立入口 | 平台：`asset_allocation_record/{id}` 及 `{asset_type}/{asset_id}`；代理：`/agent/resource-activities/asset_allocation_record/{allocation_no}` | 后端独立复核分配归属；不能因可打开旧详情就视为有权；企业从已授权资产活动查看结论 |
| 换货列表/详情 | `GET /api/admin/exchanges[/{id}]` | `items[].id/exchange_no/old_asset_type/old_asset_id/new_asset_type/new_asset_id/shop_id/submitter_id` | 平台要求换货或资产 ID；代理要求 `exchange_no` 且换货店铺仍在范围内；企业无独立入口 | 平台：`exchange_order/{id}`，旧新资产分别使用响应类型和 ID；代理：`/agent/resource-activities/exchange_order/{exchange_no}` | 旧新资产仅在各自仍可管理时开放；企业从有效授权资产活动查看结论 |
| 店铺列表/详情 | `GET /api/admin/shops[/{id}]` | `items[].id/shop_name/shop_code/parent_id/business_owner_account_id` 或详情同名字段 | 平台要求 `id`；代理要求 `shop_code` 且为自己或下级店铺；企业不显示 | 平台：`/audit/resources/shop/{id}/timeline`；代理：`/agent/resource-activities/shop/{shop_code}` | 缺字段或越权时隐藏/显示不可用，不搜索平台审计 |
| 企业列表 | `GET /api/admin/enterprises` | `items[].id/enterprise_name/enterprise_code/owner_shop_id` | 平台要求 `id`；代理要求 `enterprise_code` 且 owner shop 在范围内；企业自身不显示 | 平台：`enterprise/{id}`；代理：`/agent/resource-activities/enterprise/{enterprise_code}` | 当前没有企业详情接口，前端不得假设存在；企业 ID 不作为主体活动路径参数 |
| 企业卡列表 | `GET /api/admin/enterprises/{id}/cards` | `items[].id/iccid/virtual_no/device_id` | 平台要求 `id`；企业要求 `iccid` 且当前授权有效；代理不从此列表进入 | 平台：`iot_card/{id}`；企业：`/enterprise/resource-activities/iot_card/{iccid}` | 路由中的企业 ID 不作为授权证明；后端始终使用认证上下文复核 |
| 企业设备列表 | `GET /api/admin/enterprises/{id}/devices` | `items[].device_id/virtual_no` | 平台要求 `device_id`；企业要求 `virtual_no` 且当前授权有效；代理不从此列表进入 | 平台：`device/{device_id}`；企业：`/enterprise/resource-activities/device/{virtual_no}` | 字段为空或授权撤销时隐藏/显示活动不可用，不回退平台接口 |

## 账号、交易和资金页面逐行导航

| 源页面 | 前置接口 | `response.data` 稳定字段 | 入口名称与可见条件 | 目标接口与参数映射 | 降级行为 |
|---|---|---|---|---|---|
| 账号列表/详情 | `GET /api/admin/accounts[/{id}]` | 列表 `items[].id`；详情 `id` | 平台在 ID 非零时显示“审计记录” | `/audit/resources/account/{id}/timeline` | 缺 ID 时隐藏，不按用户名搜索 |
| 店铺列表/详情 | `GET /api/admin/shops[/{id}]` | 列表 `items[].id`；详情 `id` | ID 非零时显示“审计记录”和“资金链路” | 审计：`shop/{id}`；资金：`/audit/finance/timeline?shop_id={id}` | 缺 ID 时两个入口均隐藏 |
| 企业列表 | `GET /api/admin/enterprises` | `items[].id` | ID 非零时显示“审计记录” | `/audit/resources/enterprise/{id}/timeline` | 不假设存在企业详情接口 |
| 订单列表/详情 | `GET /api/admin/orders[/{id}]` | `items[].id/order_no` 或详情 `id/order_no` | ID 非零时显示“审计记录”和“资金链路” | 审计：`order/{id}`；资金：`/audit/finance/timeline?order_id={id}` | 不要求前端补 payment/refund ID；缺 ID 时隐藏 |
| 退款列表/详情 | `GET /api/admin/refunds[/{id}]` | `items[].id/refund_no/order_id/approval_instance_id` 或详情同名字段 | ID 非零时显示审计和资金入口；审批 ID 非零时显示“审批审计” | 审计：`refund/{id}`；资金：`finance/timeline?refund_id={id}`；审批：`approval_instance/{approval_instance_id}` | 缺审批 ID 只隐藏审批入口，不解析退款编号猜测 |
| 代理充值列表/详情 | `GET /api/admin/agent-recharges[/{id}]` | `items[].id/recharge_no/shop_id/agent_wallet_id/approval_instance_id` 或详情同名字段 | ID 非零时显示审计和资金入口；审批 ID 非零时显示审批审计 | 审计：`agent_recharge/{id}`；资金：`finance/timeline?recharge_id={id}` | 缺 `payment_no` 由服务端关联，不要求前端补猜 |
| 代理在线充值结果 | `POST /api/admin/agent-recharges` | `recharge_id/recharge_no/payment_no` | `recharge_id` 非零时显示“资金链路” | `finance/timeline?recharge_id={recharge_id}`；可附加 `payment_no` 精确筛选 | `payment_no` 不直接构造 Integration 详情；缺 recharge ID 时隐藏 |
| 资产钱包 | `GET /api/admin/assets/{identifier}/wallet` | `wallet_id/resource_type/resource_id` | `wallet_id` 非零时显示“资金链路”；资源类型和 ID 齐全时显示“资产审计” | 资金：`finance/timeline?wallet_id={wallet_id}`；审计：`resources/{resource_type}/{resource_id}/timeline` | 两个入口独立判断；缺某组字段只隐藏对应入口 |
| 店铺资金概况 | `GET /api/admin/shops/fund-summary` | `items[].shop_id` | `shop_id` 非零时显示行内“资金链路” | `finance/timeline?shop_id={shop_id}` | 不要求该接口未返回的 agent wallet ID |
| 店铺主钱包流水 | `GET /api/admin/shops/{shop_id}/main-wallet/transactions` | path `shop_id`；`items[].id/asset_type/asset_id/asset_identifier` | 始终可按合法 path 显示资金入口；资产类型和 ID 齐全时显示资产审计 | 资金：`finance/timeline?shop_id={shop_id}`；审计：`resources/{asset_type}/{asset_id}/timeline` | 缺资产 ID 仍保留店铺资金入口，不按资产编号猜测 |
| 资产钱包流水 | `GET /api/admin/assets/{identifier}/wallet/transactions` | 上层钱包接口 `wallet_id`；`items[].id/reference_type/reference_no` | 上层 `wallet_id` 非零时显示“资金链路” | `finance/timeline?wallet_id={wallet_id}` | `reference_type/reference_no` 仅展示；需后端节点明确返回资源引用后才能继续跳转 |

## 调查节点逐行跳转

| `investigation_refs` 字段 | 入口名称 | 可见条件 | 目标接口与参数 | 降级行为 |
|---|---|---|---|---|
| `event_id` | “事件详情” | 非空 | `GET /api/admin/audit/events/{event_id}` | 空值隐藏 |
| `actor_ref.kind/id` | “查看操作者行为” | kind 和 id 均非空 | `GET /api/admin/audit/actors/{kind}/{id}/events` | 任一缺失即隐藏，不用当前账号资料补齐 |
| `resource_refs[]` | “查看资源审计” | `resource_type/resource_id` 均非空 | `GET /api/admin/audit/resources/{resource_type}/{resource_id}/timeline` | 只有 Key 时先精确搜索；零或多命中不自动选择 |
| `request_id` | “查看请求链路” | 非空 | `GET /api/admin/audit/requests/{request_id}/timeline` | 空值隐藏，不扫描 Access Log 猜测 |
| `correlation_id` | “查看业务链路” | 非空 | `GET /api/admin/audit/correlations/{correlation_id}/timeline` | 空值隐藏，不按相近时间拼链路 |
| `integration_refs[].integration_id` | “查看外部交互” | 非空 | `GET /api/admin/audit/integrations/{integration_id}` | 空值隐藏，不使用数据库主键或相似资源猜测 |

`actor_ref.kind` 第一阶段只使用 `account/openapi/system_task/scheduled_job/external_system`。代理和企业活动响应不得包含 `investigation_refs`。

## 六条完整调用链

### 资产详情

1. 调用 `GET /api/admin/assets/resolve/{identifier}`。
2. 平台读取 `data.asset_type/asset_id`：卡将 `card` 转为 `iot_card`，调用 `GET /api/admin/audit/resources/iot_card/{asset_id}/timeline?page=1&page_size=20`；设备调用 `.../device/{asset_id}/timeline`。
3. 代理读取 `data.iccid` 或 `data.virtual_no`，调用对应 `/agent/resource-activities/...`。
4. 字段缺失时隐藏入口；企业不调用 resolve，也不回退平台接口。

### 订单

1. 调用 `GET /api/admin/orders/{id}`，读取 `data.id`。
2. “审计记录”调用 `GET /api/admin/audit/resources/order/{id}/timeline`。
3. “资金链路”调用 `GET /api/admin/audit/finance/timeline?order_id={id}&page=1&page_size=20`。
4. Payment、Refund、钱包等关联由服务端解析，前端不补猜。

### 退款

1. 调用 `GET /api/admin/refunds/{id}`，读取 `data.id` 和可选 `data.approval_instance_id`。
2. 审计调用 `resources/refund/{id}/timeline`，资金调用 `finance/timeline?refund_id={id}`。
3. 审批实例 ID 非零时再调用 `resources/approval_instance/{approval_instance_id}/timeline`。
4. 审批字段缺失只隐藏审批入口，不影响退款审计与资金链路。

### 钱包

1. 调用 `GET /api/admin/assets/{identifier}/wallet`，读取 `data.wallet_id/resource_type/resource_id`。
2. “资金链路”调用 `finance/timeline?wallet_id={wallet_id}`。
3. “资产审计”调用 `resources/{resource_type}/{resource_id}/timeline`。
4. 两组稳定字段分别判断，不使用交易备注或 reference 编号前缀推断资源。

### 通知

1. 点击通知后先调用 `GET /api/admin/notifications/{id}/target`。
2. 仅当 `data.available=true` 时展示跳转。
3. `data.target_type=integration_log` 且 `data.target_key` 非空时，将 target key 原样作为 `integration_id` 调用 `GET /api/admin/audit/integrations/{target_key}`。
4. 其他 target type 先进入对应业务详情，再按本文业务页面矩阵进入审计；不可用时只展示通知正文。

### 风险节点

1. 调用 `GET /api/admin/audit/risks/overview?created_from={from}&created_to={to}`。
2. 点击风险、结果、动作或来源分桶时，将相同时间范围和对应稳定编码带入 `GET /api/admin/audit/risks/events`。
3. 从明细 `items[].investigation_refs` 直接进入事件、操作者、资源、request、correlation 或 Integration 视角。
4. 缺少的引用入口隐藏；风险中心不提供处置、封禁或恢复按钮。

## 统一降级与事实边界

- 缺少目标接口必需的稳定 ID 或 identifier 时隐藏入口，不按名称、中文描述、时间或编号前缀猜测。
- 平台只有 Registry Key 时先调用精确资源搜索；零命中或多命中停留在搜索结果。
- 已删除资源只要调查节点仍有稳定资源类型和 ID，就可查看事件快照时间线。
- 代理或企业遇到越权、授权撤销或资源不存在时统一显示“活动不可用”，不回退平台调查、资源搜索或旧 operation log。
- request/correlation 时间线的 `record_source` 保留 Audit Event、Integration Log、Outbox、Asynq 摘要和 Domain Ledger 引用的事实边界；Outbox 投递成功不等于业务成功。
- 资金金额和余额以钱包流水及对应业务表为权威；Audit Event 仅用于解释谁做了什么，不用于资金重算。
- 旧 operation log 仅由平台独立历史入口访问，不拼接到新 `/api/admin/audit/*`。