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

审计链路与前端接入指南

本文对应 build-multi-view-audit-center 任务 9.5，作为审计链路和前端接入的单一说明入口。它回答以下问题：链路 ID 从哪里产生、存到哪里、不同入口为什么有的没有 request_id、15 条审计接口如何调用、每个入参与返回字段表示什么，以及前端应在哪些现有业务页面增加入口。

所有接口都使用统一响应 {code,msg,data,timestamp}；本文中的返回字段默认位于 response.data，列表项默认位于 response.data.items[]。本文定义调用契约，不包含前端页面实现；机器可读类型、枚举和约束以 docs/admin-openapi.yaml 为准。

一、先理解五个稳定 ID

字段	表示什么	谁产生	前端能否产生	主要用途
request_id	一次 HTTP 请求	请求携带 X-Request-ID 时沿用；否则 Fiber 中间件生成 UUID	业务页面不应为了审计查询临时生成；HTTP 客户端可统一传入自己的全局唯一 ID	把 Access Log、同一次 HTTP 内的 Audit Event、Integration Log 和 Outbox 串起来
correlation_id	一条可跨 HTTP、Outbox、Asynq、Callback 和外部交互的业务链路	HTTP 起点默认等于 request_id；进入异步或具体业务后可改为订单号、支付号、Integration ID、任务 ID 等稳定链路值	不得根据时间、资源或中文描述推断	查询完整业务链路；它不表示技术重试
parent_event_id	一个审计事件的直接父事件	批量根事件、异步派生或消费者在创建子事件时传播	不生成	表示直接因果和批量根子关系，不替代 correlation
integration_id	一次外部交互尝试的稳定 ID	Integration Log Writer 生成或调用方提供	不生成	查询单次外部交互详情，也是轮询链路的重要入口
trigger_series + attempt	同一外部操作的显式技术尝试序列和序号	可重试的 Integration 调用方	不生成	判断第几次重试；没有 series 时只展示单次记录，禁止猜测重试

request_id 的实际生命周期

1. 浏览器、开放接口调用方或外部回调发起 HTTP 请求。调用方如已提供 X-Request-ID，服务端沿用；否则服务端生成 UUID。
2. 服务端把同一个值写入响应头 X-Request-ID，浏览器可读取该响应头用于问题反馈。
3. Access Log 把它记录为 request_id，同时审计上下文在 HTTP 起点设置 request_id，并默认设置 correlation_id=request_id。
4. 当前请求内发生业务变更时，Audit Writer 将其写入 tb_audit_event.request_id；发生外部交互时可写入 tb_integration_log.request_id；创建可靠事件时可写入 tb_outbox_event.request_id。
5. 前端只有在事件或 Integration 返回了该值，或运维人员从响应头/Access Log 得到该值时，才调用请求时间线。普通资源详情页不需要先取得 request_id。

不是每个 HTTP 请求都会产生 Audit Event。例如普通列表查询只有 Access Log，没有业务审计事件；此时即使响应头有 X-Request-ID，请求时间线也可能没有业务节点。

request_id 在哪里落库

事实	存储位置	request_id 字段	correlation_id 字段	说明
HTTP 调试事实	Access Log 文件	JSON 字段 request_id	当前访问日志不承担业务 correlation 查询	用于按请求排查原始 HTTP；审计时间线不会扫描日志文件
Audit Event	tb_audit_event	request_id，非空列但允许保存空字符串	correlation_id，非空列但允许保存空字符串	解释谁对什么资源做了什么
Integration Log	tb_integration_log	request_id，可空	correlation_id，可空	解释调用了哪个外部系统、结果和尝试序列
Outbox	tb_outbox_event	request_id，允许空字符串	correlation_id，允许空字符串	可靠投递事实；投递成功不等于业务成功
Asynq	任务 payload 或 Audit Event 的任务资源引用	按任务类型选择性携带	按任务类型选择性携带	Redis 队列不是审计查询数据源；查询只展示已持久化引用，不扫描历史队列
手动轮询运行记录	tb_polling_manual_trigger_log	没有该字段	没有该字段	只承担进度、结果、触发人和卡列表；人工触发命令另写 Audit Event

二、轮询为什么通常没有 request_id

普通自动轮询由 Scheduler/Asynq Worker 触发，不是 HTTP 请求，因此没有 request_id 是正确语义：

1. Worker 调用 Gateway 前创建 Integration Log，生成 integration_id。
2. 普通轮询的 tb_integration_log.request_id 保持空；trigger_series 和 correlation_id 通常使用该 integration_id。
3. Gateway 返回后，如果观测结果实际改变卡、设备、套餐或网络状态，Worker 才写 Audit Event。
4. 该 Audit Event 的 request_id 仍为空，correlation_id 使用 Integration ID、Asynq Task ID 或稳定任务标识，从而与外部尝试和资源时间线关联。
5. 前端看到 request_id 为空时隐藏“请求链路”；correlation_id 非空时显示“业务链路”；无论两者是否存在，都可以继续使用 integration_id 或资源引用。

人工轮询需要区分两个事实：

• 管理员点击“手动触发”的 HTTP 命令会产生 Audit Event，因此该“谁发起了轮询”事件有 request_id。
• 随后真正执行轮询的是 Worker。当前手动队列只携带卡 ID，执行阶段没有原 HTTP request_id；Gateway 尝试和实际观测变化按 Worker 自身的 Integration ID/correlation 串联。
• tb_polling_manual_trigger_log 继续显示进度和结果；Audit Event 解释谁触发/取消；Integration Log 解释 Gateway 是否被调用以及调用结果。三类事实不能合并成一张记录。

三、前端选择入口的顺序

前端不应把 request_id 当作所有审计入口的必填条件。统一按以下顺序选择：

1. 业务页面已有内部 ID：平台直接调用资源时间线。
2. 代理或企业页面已有 ICCID、VirtualNo、分配单号、换货单号等业务 identifier：调用主体资源活动接口。
3. 订单、退款、充值、钱包或店铺页面：直接以任一稳定业务 ID 调用资金时间线，关联 ID 由服务端补全。
4. 审计节点返回 investigation_refs：按引用字段跳转事件、操作者、资源、请求、correlation 或 Integration 视角。
5. 只有 resource_key 没有内部 ID：先调用资源精确搜索，零命中或多命中时让用户选择，不自动猜测。
6. 必需字段不存在：隐藏入口；不得用名称、中文说明、相近时间、编号前缀或第三方流水猜关系。

四、15 条接口总览

接口	何时调用	必填入参	主要返回
GET /api/admin/audit/events	平台审计中心全局列表或其他节点带筛选跳转	无	EventPage
GET /api/admin/audit/events/{event_id}	查看一个稳定审计事件	event_id	EventDetail
GET /api/admin/audit/actors/{kind}/{id}/events	查看某个操作者行为	kind、id	EventPage
GET /api/admin/audit/resources/search	只有业务 Key、没有内部资源 ID	resource_type、keyword	ResourceSearchPage
GET /api/admin/audit/resources/{resource_type}/{resource_id}/timeline	平台业务页面或资源引用进入审计	resource_type、resource_id	EventPage
GET /api/admin/audit/requests/{request_id}/timeline	已有真实 request ID 时调查一次 HTTP	request_id	LinkTimeline
GET /api/admin/audit/correlations/{correlation_id}/timeline	调查跨请求、异步和外部业务链路	correlation_id	LinkTimeline
GET /api/admin/audit/finance/timeline	从订单、退款、充值、钱包、店铺等进入资金调查	至少一个稳定资金条件	FinanceTimelinePage
GET /api/admin/audit/risks/overview	平台风险中心总览	无；时间不传时使用在线窗口	RiskOverview
GET /api/admin/audit/risks/events	从风险分桶查看明细	无；分页和筛选可选	RiskEventPage
GET /api/admin/audit/integrations/overview	平台 Integration 调查总览	无；时间不传时使用在线窗口	IntegrationOverview
GET /api/admin/audit/integrations	外部交互列表和组合筛选	无	IntegrationListPage
GET /api/admin/audit/integrations/{integration_id}	查看单次外部交互和尝试序列	integration_id	IntegrationDetailResponse
GET /api/admin/agent/resource-activities/{resource_type}/{identifier}	代理查看授权范围内资源活动	resource_type、identifier	SubjectActivityPage
GET /api/admin/enterprise/resource-activities/{resource_type}/{identifier}	企业查看当前有效授权卡或设备活动	resource_type、identifier	SubjectActivityPage

平台 /audit/* 接口仅允许超级管理员和平台账号访问；代理、企业必须使用各自的主体活动接口。全部为 GET，不提供修改、删除、导出、恢复、重试、补偿或风险处置。

五、请求参数字典

通用时间与分页

字段	类型	是否必填	含义
created_from	RFC3339 字符串	否	起始时间，包含该时刻；未传时从在线留存窗口开始
created_to	RFC3339 字符串	否	结束时间，不包含该时刻；未传时为当前时间
page	int	否	页码，默认 1
page_size	int	否	每页数量，默认 20，最大 100

显式时间早于 retention.online_from 或跨越在线边界时返回“数据已归档”稳定错误，不会从对象存储读取部分结果。Integration 和风险查询最长连续 31 天。

全局事件 GET /audit/events

字段	类型/枚举	来源与用途
action	string	稳定动作编码，使用返回的 action_code
category	configuration/reliability/asset/security/identity/business	动作类别
actor_kind	account/personal_customer/openapi/system_task/scheduled_job/external_system	操作者类型
actor_id	string	与 actor_kind 共同定位操作者
source	admin_api/personal_api/openapi/worker/scheduler/callback	操作入口
result	success/failed/denied/partial/unknown	业务结果
risk	low/normal/high/critical	风险等级
scope_type	platform/shop/personal_customer	业务范围类型
scope_id	string	业务范围稳定 ID
resource_type	Registry 类型	资源类型
resource_id	string	资源内部稳定 ID
resource_key	string	资源业务稳定 Key
request_id	string	可选精确筛选；来自真实 HTTP 请求，不是必填入口
correlation_id	string	可选精确筛选业务链路
created_from/to/page/page_size	通用字段	时间和分页

事件详情、操作者和资源

接口	参数	说明
/audit/events/{event_id}	path event_id	来自事件列表或 investigation_refs.event_id
/audit/actors/{kind}/{id}/events	path kind/id；query action/result/risk/resource_type/resource_id/created_from/created_to/page/page_size	kind/id 来自 actor_ref；action 使用返回的稳定编码
/audit/resources/search	query resource_type/keyword/page/page_size	resource_type 仅 iot_card/device/shop/order/refund；keyword 为精确业务标识
/audit/resources/{resource_type}/{resource_id}/timeline	path resource_type/resource_id；query created_from/created_to/action/result/page/page_size	path 来自业务页面内部 ID、搜索结果或 resource_refs

资源搜索 keyword 规则：卡支持 ICCID/VirtualNo，设备支持 VirtualNo/IMEI/SN，店铺使用店铺编号，订单使用订单号，退款使用退款单号。

request 与 correlation 时间线

接口	参数	说明
/audit/requests/{request_id}/timeline	path request_id	来自 Event/Integration 返回字段、响应头或 Access Log；普通轮询为空时不调用
/audit/correlations/{correlation_id}/timeline	path correlation_id	来自 Event、Integration、Outbox/任务或业务详情稳定字段

这两个接口不接受分页，返回在线窗口内全部已持久化关联节点。request 查询会同时返回 access_log_lookup_request_id，供运维复制到 Access Log 检索；接口自身不扫描 Access Log。

资金时间线 GET /audit/finance/timeline

字段	类型	前端来源
shop_id	uint	店铺详情或资金概况
wallet_id	uint	代理主钱包或资产钱包详情
order_id/order_no	uint/string	订单列表或详情
payment_id/payment_no	uint/string	支付记录或已明确返回的支付单号
refund_id/refund_no	uint/string	退款列表或详情
recharge_id/recharge_no	uint/string	代理充值或个人资产充值
approval_instance_id	uint	审批实例
third_party_trade_no	string	已明确返回的第三方交易号
actor_kind/actor_id	enum/string	调查某操作者涉及的资金事实，必须成对提供
correlation_id	string	已有稳定业务链路时使用
created_from/to/page/page_size	通用字段	时间和分页

调用方至少提供一个稳定资金条件；同一业务的其他 ID 由服务端解析，不要求前端补齐。

风险接口

接口	参数	映射
/audit/risks/overview	created_from/created_to/risk/result/action/source	独立风险中心筛选
/audit/risks/events	上述字段 + page/page_size	risks[].code→risk、results[].code→result、actions[].code→action、sources[].code→source

Integration overview/list

overview 和 list 共用以下筛选；overview 另有 bucket=hour/day，list 另有 page/page_size。

字段	类型/枚举	来源与用途
integration_id	string	列表、通知 target 或 investigation_refs 返回的稳定 ID
provider	ctcc/cmcc/cucc/wechat_pay/alipay/fuiou/wecom/gateway	外部服务提供方
direction	inbound/outbound	入站或出站
operation	OpenAPI enum	外部操作稳定编码，使用列表/详情返回的 operation
result	pending/success/failed/unknown/not_found/invalid_payload/conflict/ignored/merged/rate_limited/completed/cancelled	原始结果
result_category	processing/succeeded/indeterminate/failed/not_sent	服务端从 result 派生的固定类别
external_id	string	外部系统业务或请求标识
resource_type/resource_id/resource_key	string	本地主要资源稳定引用
trigger_source/trigger_scene/trigger_series	string	触发来源、业务场景和显式尝试序列
state_changed	bool	是否改变本地业务状态
http_status	100～599	外部 HTTP 状态码
provider_code	string	外部服务稳定结果码
request_id/correlation_id	string	已有稳定链路字段时筛选；自动轮询 request_id 为空
created_from/to	通用字段	时间范围，最长 31 天

当前 operation 枚举为：realname_callback、realname_removal_callback、payment_precreate、payment_query、payment_callback、get_access_token、list_visible_members、list_visible_departments、get_template_detail、upload_approval_attachment、submit_approval、approval_callback、get_approval_detail、get_approval_info、query_realname_status、query_flow、query_card_status、query_device_info、set_speed_tier、stop_card、start_card、set_device_wifi、set_device_switch_mode、switch_device_card、reboot_device、reset_device。前端使用 OpenAPI 或接口返回值，不维护另一份中文到编码映射。

代理与企业主体活动

接口	resource_type	identifier	其他参数
/agent/resource-activities/{resource_type}/{identifier}	iot_card/device/asset_allocation_record/exchange_order/shop/enterprise	依次使用 ICCID、VirtualNo、分配单号、换货单号、店铺编号、企业编号	created_from/created_to/page/page_size
/enterprise/resource-activities/{resource_type}/{identifier}	仅 iot_card/device	卡用 ICCID，设备用 VirtualNo	created_from/created_to/page/page_size

代理店铺范围和企业 ID 只来自认证上下文，前端不能传 shop_id/enterprise_id 证明权限。

六、返回参数字典

统一响应与留存信息

字段	含义
code	统一响应码，成功为 0
msg	中文响应消息
data	本接口业务数据
timestamp	服务端响应时间
retention.online_from	PostgreSQL 当前可在线查询的最早时间
retention.archived_before	早于该时间的数据已归档，不可通过这些接口读取
retention.timezone	留存边界时区，当前为 Asia/Shanghai

EventPage、EventDetail 与 EventView

EventPage 返回 total/page/page_size/items[]/retention；EventDetail 返回单个 EventView 并附带 retention。

EventView 字段	含义/前端用法
event_id	稳定审计事件 ID，可打开事件详情
occurred_at/created_at	业务事实发生时间/审计记录写入时间
category	动作类别稳定编码
action_code/action_name	稳定动作编码/中文展示名；筛选使用 code
summary	中文事件摘要
actor_kind/actor_id/actor_name	操作者类型、稳定 ID、事件发生时名称快照
actor_shop_id/name	操作者所属店铺快照
actor_enterprise_id/name	操作者所属企业快照
source	admin_api、worker、scheduler、callback 等入口来源
request_path/request_method/ip_address/user_agent	HTTP 来源信息；Worker/Scheduler 可为空
scope_type/scope_id/scope_name	业务范围类型、ID 和名称快照
result/risk_level	结果和风险等级稳定编码
error_code/error_summary	失败或拒绝时的稳定错误码和脱敏摘要
request_id	有值才显示“请求链路”；自动轮询通常为空
correlation_id	有值显示“业务链路”
parent_event_id	直接父事件 ID
batch_total/success_count/fail_count	批量根事件计数；非批量为 0
metadata	已脱敏动作扩展字段，具体含义由 action_code 定义
content_hash	事件不可变内容摘要
resources[]	事件涉及的全部资源及各自快照
investigation_refs	前端跨视角跳转的唯一稳定来源

resources[] 字段：resource_type/resource_id/resource_key/display_name 定位资源；relation 为 primary/affected/reference；role 为资源业务角色；identity_snapshot 为事件发生时身份；before_data/after_data 为该资源变更前后数据；subject_visibility/subject_summary/subject_data 为代理或企业安全投影；sort_order/created_at 为展示顺序和资源关联记录写入时间。

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}。任一目标所需字段不完整时隐藏该入口。

ResourceSearchPage

返回 total/page/page_size/items[]/retention。候选项包含 resource_type/resource_id/resource_key/display_name/identity_snapshot/historical；historical=true 表示当前业务表未命中，只从在线历史事件快照解析，不代表资源当前仍存在。

LinkTimeline

字段	含义
request_id/correlation_id	本次查询使用的链路值，二者只会对应当前查询视角
access_log_lookup_request_id	可复制到 Access Log 的 request ID
nodes[]	按发生时间稳定升序的跨事实节点
retention	Audit 与 Integration 的共同在线边界

nodes[] 包含：record_source、node_id、occurred_at、code/title、result/result_name、summary、reference_only、request_id/correlation_id/parent_event_id、resources[]、investigation_refs、fidelity。

record_source 可能是 audit_event、integration_log、outbox_event；由事件资源派生的只读引用还可能是 asynq_task 或 domain_ledger_ref。reference_only=true 只表示引用，不代表该节点独立改变了业务状态。fidelity 包含 request_available、correlation_available、parent_event_available、direct_audit_link_available、stable_resource_available；false 时禁止猜测补齐。

FinanceTimelinePage

返回 total/page/page_size/items[]/retention。每个资金节点包含：

• record_source/node_id/occurred_at：事实来源、来源内稳定 ID、发生时间。
• code/title/result/result_name：来源内稳定编码和中文名称。
• amount/balance_before/balance_after/currency：金额和余额，单位分，人民币为 CNY；为空表示该节点不承载该金额。
• shop_id/wallet{resource_type,wallet_id}：店铺和钱包引用。
• amount_authority{authoritative,table,field,conflict_rule}：是否为权威金额及其数据库表字段；冲突时按 conflict_rule 展示。
• facts：该事实来源的安全结构化业务字段。
• investigation_refs：继续进入事件、资源、操作者、request、correlation 或 Integration。

RiskOverview 与 RiskEventPage

RiskOverview 返回：total、服务端选择的 bucket=hour/day、signals/risks/results/actions/sources 分布、trend[] 和 retention。所有分布项统一为 {code,name,count}，筛选使用 code、展示使用 name。

• signals[].code：high_risk/finance/security/failed/denied/partial/unknown。
• risks[].code：low/normal/high/critical。
• results[].code：success/failed/denied/partial/unknown。
• actions[].code：稳定 action_code。
• sources[].code：admin_api/personal_api/openapi/worker/scheduler/callback。
• trend[]：bucket_at/total/high_risk/finance/security/failed/denied/partial/unknown。

RiskEventPage 与 EventPage 结构相同，items[] 只包含固定风险集合内的 EventView。

IntegrationOverview、ListPage 和 Detail

IntegrationOverview 返回 total/anomaly_count/unknown_count/stale_pending_count/state_changed_count/average_duration_ms/p95_duration_ms/results/providers/directions/trend/retention。results[] 为 {code,name,category,count}，providers/directions 为 {code,name,count}，trend[] 为 {bucket_at,total,succeeded,processing,indeterminate,failed,not_sent}。分布 code 可原样回填 list 筛选；name 只用于展示。

Integration ListPage 返回 total/page/page_size/items[]/retention。每项包含：

• integration_id：详情入口。
• provider/provider_name、direction/direction_name、operation/operation_name：稳定编码和中文名。
• resource{type,id,key}：type/id 均存在时可进入资源时间线。
• result/result_name/result_category：原始结果、中文名和派生类别。
• duration_ms/state_changed/created_at：耗时、本地状态是否变化和创建时间。
• request_id/correlation_id：分别控制请求链路和业务链路入口；自动轮询 request_id 可为空。

Integration Detail 按分组返回：

分组	字段与用途
identity	integration_id/provider/provider_name/direction/direction_name/operation/operation_name/external_id
resource	type/id/key；type/id 齐全时进入资源时间线
trigger	source/scene/series/attempt；series 为空时不拼接其他重试
result	code/name/category/http_status/provider_code/provider_message/duration_ms/state_changed/recovery_strategy；本接口只展示，不执行恢复
content	已脱敏 request_summary/response_summary/metadata/content_hash
linkage	request_id/correlation_id/audit_event_id；稳定事件跳转优先使用 investigation_refs 中的 event_id
timestamps	scheduled_at/started_at/created_at/updated_at
attempts[]	同 series 的 integration_id/attempt/operation/operation_name/sent/result/result_name/result_category/duration_ms/state_changed/created_at
fidelity	trigger_series_available/attempt_sequence_reliable/correlation_available/resource_id_available/provider_message_fidelity
retention	在线留存边界

SubjectActivityPage

代理与企业安全活动返回 resource/total/page/page_size/items[]/retention。

• resource 与 related_resources[]：resource_type/resource_id/resource_key/display_name 安全摘要；主体前端不得据此调用平台 /audit/*。
• items[].action_code/action_name：安全动作编码和中文名。
• items[].subject_summary/subject_data：写入时生成的主体安全摘要和白名单业务字段，不是平台 before/after 删除字段后的结果。
• items[].result/occurred_at：结果和发生时间。
• 响应不包含平台 actor、risk、内部原因、before/after、Audit Event ID、request_id、correlation_id、Integration 内容或 investigation_refs。

七、跨视角只读接口

视角	接口	入参来源	响应重点
请求链路	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/personal_customer/openapi/system_task/scheduled_job/external_system。代理和企业活动响应不得包含 investigation_refs。

八、完整调用链

HTTP 同步业务操作

1. 前端调用现有业务写接口；可不传 X-Request-ID，服务端会生成并通过响应头返回。
2. HTTP 中间件建立 request_id，审计上下文初始设置 correlation_id=request_id。
3. 业务变更与 Audit Event 在同一事务提交，事件写入 request_id/correlation_id 和资源快照。
4. 前端从业务资源页用资源 ID 查看时间线，或从 EventView 的 request_id 查看该请求链路。
5. 请求时间线只返回已经落入 Audit、Integration、Outbox 的节点；Access Log 需另用 access_log_lookup_request_id 检索。

HTTP → Outbox → Asynq/Worker

1. HTTP 操作产生 request_id，业务确定或沿用 correlation_id。
2. 创建 Outbox 时，未显式传入的 request/correlation/parent 从审计上下文继承并写入 tb_outbox_event。
3. Relay 将三个字段随 envelope 交给消费者；需要继续入 Asynq 的任务在 payload 中显式携带。
4. Worker 恢复系统操作者并写子 Audit Event；有外部调用时另写 Integration Log。
5. 前端用 correlation 时间线查看跨进程链路；record_source 区分 Audit、Outbox、Integration 和任务引用，不能把 Outbox delivered 当作业务成功。

外部 Callback

1. Callback 同样经过 HTTP RequestID 中间件，因此会有 request_id。
2. Integration Log 先记录入站外部交互；correlation 可等于 request ID，也可使用 payment_no、审批 SPNo 等更稳定业务键。
3. Callback 实际改变本地业务事实时，以 external_system actor 写 Audit Event；没有状态变化时只保留 Integration Log。
4. 前端从 Integration detail 的 request/correlation/resource 引用继续调查。

自动轮询

1. Scheduler/Asynq 选择卡并执行 Worker，没有 HTTP request，因此不生成 request_id。
2. Worker 创建 Gateway Integration Log：integration_id=trigger_series=correlation_id，request_id=null。
3. Gateway 结果若改变内部事实，Audit Event 使用同一 correlation，actor 为 system_task，source 为 worker。
4. 前端从 Integration 调查中心、资源时间线或 correlation 时间线进入；隐藏“请求链路”。

人工即时刷新与手动轮询入队

• “人工即时刷新卡数据”在一个 HTTP 用例内直接执行 Gateway 查询：有 request_id，外部尝试可继承该 request/correlation，能从请求时间线串起。
• “手动触发轮询”先记录 HTTP 触发 Audit Event，因此触发命令有 request_id；但当前 Redis 手动队列只保存 card ID，后续 Worker 没有原 request/correlation，执行阶段按新的 Integration ID 建链。
• 因此当前不能仅凭 request_id 从“手动触发事件”自动跳到后续 Gateway 轮询尝试。前端分别展示手动任务进度、触发审计和资源/Integration 活动，不按时间拼接。若产品要求强关联，需要单独实施稳定 trigger/correlation 传播，不属于本文前端接入范围。

资产详情

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/*。