break
b3499adfca
Constraint: 切换 main 前必须保存当前七月分支全部项目进展，套餐生效提案仅属于 Iteration/7-11。 Rejected: 将七月套餐修复直接移植到 main | 两个分支的可靠投递架构不同。 Confidence: medium Scope-risk: broad Directive: 不得将本提交整体 cherry-pick 到 main；main 套餐热修必须基于其纯 Asynq 代码独立实施。 Tested: git diff --check；openspec validate fix-package-activation-starvation --strict。 Not-tested: 按用户要求未运行自动化测试；go build ./... 因当前审计改造中的 Enterprise 模型字面量和 role.recordFailure 参数类型错误未通过。
60 lines
4.7 KiB
Markdown
60 lines
4.7 KiB
Markdown
# 平台基础审计调查接口
|
||
|
||
本文冻结 `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[]` |
|
||
|
||
认证身份和数据范围只来自认证上下文，不接受 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 解析。
|
||
|
||
## 统一调查引用
|
||
|
||
平台调查节点统一返回 `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` 时按白名单目标继续跳转。
|