feat: 审计链路

2026-08-07 18:33:37 +08:00
parent fa3d7088f9
commit b8b2854aa6
54 changed files with 5448 additions and 12 deletions
--- a/openspec/changes/add-audit-chain-frontend-integration/design.md
+++ b/openspec/changes/add-audit-chain-frontend-integration/design.md
@@ -0,0 +1,53 @@
+## Context
+
+本次变更横跨平台、代理和企业三类主体以及资产、订单、退款、钱包、通知等多个业务页面。OpenAPI 将关联关系明确建模为 `investigation_refs`、`linkage` 和稳定资源引用，并区分平台内部 ID 与代理/企业可见的业务标识。前端必须保持这些边界，不能为了补齐跳转而从名称、时间或摘要推断关联关系。
+
+仓库目前没有已归档的基线 specs，但存在通知中心和旧资产操作日志的活跃变更。本提案建立独立的审计链路能力，通过明确的依赖点与它们集成，不复制或覆盖其已有要求。
+
+## Goals / Non-Goals
+
+- Goals: 按 OpenAPI 实现 16 个只读接口的类型、查询、页面和跨视角跳转契约。
+- Goals: 为平台、代理和企业提供符合各自权限与数据投影的业务审计入口。
+- Goals: 统一分页、RFC3339 时间范围、枚举展示、在线保留窗口和错误处理。
+- Non-Goals: 不修改后端接口、数据库、日志采集或保留策略。
+- Non-Goals: 不提供恢复、重试、修改、删除、处置、封禁、任意全文搜索或导出。
+- Non-Goals: 不替换现有资产操作日志组件，也不修改 C/H5 端。
+
+## Decisions
+
+- Decision: 新增独立审计 API 模块和共享类型，按平台审计、主体活动、资金、风险、Integration、链路时间线分组暴露查询函数；统一保留服务端响应包装和 nullable 字段。
+- Decision: 平台业务入口使用响应中的内部稳定 ID。卡、设备、店铺、企业、订单和退款分别使用对应 `resource_type` 与 `response.data.id`；钱包通过资金时间线的 `wallet_id` 进入。
+- Decision: 代理与企业入口使用响应中的稳定业务标识。卡使用 `iccid`，设备使用 `virtual_no`；代理的分配、换货、店铺和企业使用接口文档指定的业务编号。缺少稳定标识时隐藏入口。
+- Decision: 前端只转发后端返回的调查引用。事件的 `event_id`、`actor_ref`、`resource_refs`、`request_id`、`correlation_id`、`integration_refs`，以及 Integration 的 `linkage`/`resource` 是跨视角导航的唯一数据来源。
+- Decision: `request_id` 可以来自调查引用、Integration、或用户从 Access Log 明确粘贴；`correlation_id` 和 `integration_id` 只能来自接口返回的稳定字段。前端不使用 UUID 或其他方式生成这些 ID。
+- Decision: 对不存在、为空或 `fidelity=false` 的引用隐藏对应跳转，禁止按名称、时间、摘要或相邻记录猜测缺失关系。
+- Decision: 资源搜索严格使用 `resource_type + keyword` 精确查询，并把选中项的 `resource_type/resource_id` 原样传给资源时间线。`historical=true` 只作为历史快照命中提示。
+- Decision: 列表和时间线统一消费 `page`、`page_size`、`total` 并保留 `retention` 语义。时间筛选发送含时区的 RFC3339 值，`created_to` 按接口定义为不包含该时刻；页面不展示全局在线窗口提示，也不提供归档查询假入口。
+- Decision: 所有枚举筛选提交稳定 code，并优先展示后端 `*_name`。`action`、Integration `operation` 等开放编码必须直接来自响应，不能从中文文案反推。
+- Decision: 资金金额按分展示转换，权威性只认 `amount_authority.authoritative=true` 指向的业务字段；前端不得合并冲突金额或自行计算余额。
+- Decision: 代理与企业活动共用展示外壳但使用独立 API。企业页面只展示主体安全投影，不引入平台操作者、风险、内部原因或 before/after 字段。
+- Decision: 通知目标仅在 `available=true`、`target_type=integration_log` 且 `target_key` 非空时跳转，并将 `target_key` 原样作为 Integration 详情的 `integration_id`。其他情况保留通知正文并提示目标不可用。
+- Decision: 权限以最终菜单/按钮权限编码和服务端鉴权共同控制。平台、代理、企业不展示不属于其主体的审计入口，`401/403` 继续走共享认证与无权处理。
+
+## Risks / Trade-offs
+
+- 最终菜单与按钮权限编码尚未体现在 OpenAPI 中；实施前必须确认，否则只能依赖服务端 `403`，无法做到准确的入口隐藏。
+- 审计事件和 Integration 模型字段较多；通过共享详情/时间线组件和严格类型避免各业务页重复实现，但不抽象为可以执行任意端点的动态页面。
+- 在线保留窗口外的数据不可由这些接口查询；空状态使用“当前查询无记录”的中性表达，避免将空数据误报为无历史事件。
+- 活跃通知中心变更也会修改通知导航；实施时需在其最新状态上追加 `integration_log` 规则，避免覆盖既有白名单映射。
+- 旧资产操作日志与新审计中心含义相邻但数据源不同；两个入口并存并清晰命名，避免误将旧日志能力删除。
+
+## Migration Plan
+
+1. 确认平台、代理、企业的菜单和按钮权限编码，以及审计中心路由归属。
+2. 建立 OpenAPI 对齐的类型、API 模块和共享只读展示组件。
+3. 按平台审计、资金、风险、Integration、主体活动顺序接入页面。
+4. 在业务页面与通知导航中增加稳定引用入口。
+5. 完成角色、数据隔离、空引用、保留窗口、错误和跨视角跳转验收。
+6. 若上线异常，隐藏新增路由与入口；现有业务接口和旧操作日志不受影响。
+
+## Open Questions
+
+- 平台审计中心、风险中心、Integration、代理资源活动和企业资源活动的最终菜单及按钮权限编码分别是什么？
+- 审计中心是作为一级菜单，还是归入现有系统管理/运维菜单？
+- OpenAPI 未包含 `GET /api/admin/notifications/{id}/target` 的完整响应 schema；是否继续以活跃通知中心变更定义的 `available/target_type/target_id/target_key` 为最终契约？
--- a/openspec/changes/add-audit-chain-frontend-integration/proposal.md
+++ b/openspec/changes/add-audit-chain-frontend-integration/proposal.md
@@ -0,0 +1,38 @@
+# Change: 新增审计链路前端接入能力
+
+## Why
+
+八月迭代新增了审计事件、请求与业务链路、资金调查、风险调查、外部集成交互以及代理/企业资源活动共 16 个只读接口。当前前端尚无统一的审计调查页面、接口类型和业务入口，无法可靠消费后端返回的稳定调查引用，也容易错误地由名称、时间或页面数据自行拼接链路标识。
+
+## What Changes
+
+- 新增平台审计事件列表、详情、操作者时间线、资源精确搜索和资源时间线能力。
+- 新增请求链路与业务关联链路时间线，并只使用接口返回或用户从 Access Log 粘贴的稳定 `request_id`、`correlation_id`。
+- 新增资金调查时间线、风险总览与明细、Integration 总览/列表/详情页面。
+- 新增代理和企业资源活动入口，并按主体支持范围使用稳定业务标识和后端安全投影。
+- 在卡、设备、店铺、企业、订单、退款和钱包相关列表/详情页增加角色匹配的「审计记录」入口。
+- 接入通知目标到 Integration 详情的受控跳转：仅接受可用的 `integration_log` 目标。
+- 统一使用后端返回的名称、状态、保留窗口语义和调查引用；禁止前端猜测或生成 `request_id`、`correlation_id`、`integration_id`。
+- 所有新增能力均为只读调查能力，不增加恢复、修改、删除、处置、封禁或导出操作。
+
+## Impact
+
+- Affected specs: `audit-chain-frontend-integration`
+- Affected code:
+  - `src/api/modules/` 下新增审计接口模块
+  - `src/types/api/` 下新增审计接口类型
+  - `src/views/` 下审计中心、风险中心、Integration 和时间线页面
+  - 卡、设备、店铺、企业、订单、退款、钱包相关列表/详情页
+  - 路由、菜单、权限控制及通知目标导航
+- API contracts:
+  - `GET /api/admin/audit/*`
+  - `GET /api/admin/agent/resource-activities/{resource_type}/{identifier}`
+  - `GET /api/admin/enterprise/resource-activities/{resource_type}/{identifier}`
+  - `GET /api/admin/notifications/{id}/target`
+- Dependencies:
+  - 与活跃变更 `update-admin-notification-center-api` 的受控通知目标协议保持一致
+  - 与活跃变更 `update-admin-asset-device-signal-and-audit-logs` 的旧资产操作日志展示并存；本变更不替换旧日志接口
+- Source of truth:
+  - `docs/产品迭代8月份/审计链路接口变更整理文档.md`
+  - `docs/产品迭代8月份/默认模块.openapi.json`
+- Breaking changes: 无；现有业务接口路径保持不变
--- a/openspec/changes/add-audit-chain-frontend-integration/specs/audit-chain-frontend-integration/spec.md
+++ b/openspec/changes/add-audit-chain-frontend-integration/specs/audit-chain-frontend-integration/spec.md
@@ -0,0 +1,207 @@
+## ADDED Requirements
+
+### Requirement: Platform Audit Event Investigation
+
+The admin frontend SHALL provide platform audit event list and detail views using `GET /api/admin/audit/events` and `GET /api/admin/audit/events/{event_id}`. It SHALL preserve the documented event, actor, scope, resource, result, risk, request and investigation-reference fields, use stable codes for filters, and prefer backend display names.
+
+#### Scenario: Filter and inspect audit events
+
+- **WHEN** an authorized platform user filters audit events by documented time, action, category, actor, source, result, risk, scope, resource or linkage parameters
+- **THEN** the frontend MUST send the documented parameter names and stable code values
+- **AND** it MUST render the paginated `items`, `total`, `page`, `page_size` and `retention` response
+
+#### Scenario: Open an event detail
+
+- **WHEN** the user opens an event returned by the list or another investigation reference
+- **THEN** the frontend MUST pass its `event_id` unchanged to the detail endpoint
+- **AND** it MUST display backend snapshots and names without replacing historical values with current account or resource names
+
+### Requirement: Stable Investigation Reference Navigation
+
+The frontend SHALL navigate between audit views only through stable identifiers returned by the APIs. `investigation_refs.actor_ref`, `resource_refs`, `request_id`, `correlation_id`, `integration_refs`, Integration `linkage`, and stable Integration `resource` references SHALL be the authoritative navigation sources.
+
+#### Scenario: Navigate through a returned reference
+
+- **WHEN** an audit or Integration response contains a non-empty supported investigation reference
+- **THEN** the frontend MUST pass the returned identifier and type unchanged to the corresponding actor, resource, request, correlation or Integration view
+
+#### Scenario: A reference is unavailable or unreliable
+
+- **WHEN** the required reference is empty, absent, unsupported, or its linkage `fidelity` indicates that a relationship is unavailable
+- **THEN** the frontend MUST hide or disable the related navigation action
+- **AND** it MUST NOT infer a relationship from names, timestamps, summaries, adjacent rows or resource text
+
+#### Scenario: Link identifiers are not generated by the frontend
+
+- **WHEN** the frontend needs a `correlation_id` or `integration_id`
+- **THEN** it MUST use a value returned by an API
+- **AND** it MUST NOT generate, concatenate or guess the identifier
+
+### Requirement: Actor, Resource, and Link Timelines
+
+The admin frontend SHALL provide actor-event, resource-event, request-link and correlation-link timelines through the documented endpoints. It SHALL support an explicitly pasted Access Log `request_id`, while all other navigation values SHALL come from returned stable references.
+
+#### Scenario: Inspect actor behavior
+
+- **WHEN** a user follows `actor_ref.kind/id` or opens an account by its stable ID
+- **THEN** the frontend MUST call `/api/admin/audit/actors/{kind}/{id}/events`
+- **AND** action and resource filters MUST use stable values returned by audit data
+
+#### Scenario: Select an exact resource result
+
+- **WHEN** a user searches with a supported `resource_type` and exact `keyword` and selects a result
+- **THEN** the frontend MUST pass `items[].resource_type/resource_id` unchanged to the resource timeline
+- **AND** it MUST identify `historical=true` as a historical-snapshot match
+
+#### Scenario: Query a request copied from Access Log
+
+- **WHEN** a platform user explicitly pastes a request ID from Access Log
+- **THEN** the frontend MAY query `/api/admin/audit/requests/{request_id}/timeline` with that exact value
+- **AND** it MUST NOT claim that the endpoint scans Access Log or archived object storage
+
+### Requirement: Retention, Pagination, and Time Semantics
+
+All audit list and timeline views SHALL use the documented pagination and `retention` contract. Time filters SHALL be RFC3339 timestamps with timezone information, and `created_to` SHALL be treated as an exclusive upper bound.
+
+#### Scenario: Respect the online retention window without a global prompt
+
+- **WHEN** a response contains `retention.online_from`, `archived_before` and `timezone`
+- **THEN** the frontend MUST preserve the retention semantics in its data contract without displaying a global online-window banner
+- **AND** it MUST NOT interpret an empty online result as proof that no historical event exists
+
+#### Scenario: Page through a timeline
+
+- **WHEN** the user changes page or page size
+- **THEN** the frontend MUST use `page` and `page_size`, respect the maximum page size of 100, and preserve the active filters
+
+### Requirement: Finance Investigation Timeline
+
+The admin frontend SHALL query `GET /api/admin/audit/finance/timeline` with any documented stable finance condition, including shop, wallet, order, payment, refund, recharge, approval, third-party trade, actor or correlation identifiers. Monetary values SHALL remain integer fen in application data, and authority SHALL follow `amount_authority`.
+
+#### Scenario: Open finance history from a business record
+
+- **WHEN** a user opens finance history from an order, refund, recharge, wallet or shop with a stable backend ID
+- **THEN** the frontend MUST send the matching documented query parameter
+- **AND** it MUST allow the server to complete related facts instead of assembling a local timeline
+
+#### Scenario: Display an authoritative amount
+
+- **WHEN** a finance node returns an amount and `amount_authority.authoritative=true`
+- **THEN** the frontend MUST treat the referenced table and field as authoritative
+- **AND** it MUST only convert integer fen for presentation and MUST NOT reconcile conflicting facts locally
+
+### Requirement: Risk Investigation
+
+The admin frontend SHALL provide risk overview and event-detail views using `/api/admin/audit/risks/overview` and `/api/admin/audit/risks/events`. Filters SHALL use codes returned in overview collections, and the selected time range SHALL not exceed 31 days.
+
+#### Scenario: Drill down from a risk summary
+
+- **WHEN** a user selects a risk, result, action, source or signal represented by the overview
+- **THEN** the frontend MUST use the returned stable code for the supported event-list filter
+- **AND** backend `name` values MUST be used only for display
+
+#### Scenario: Select a range longer than 31 days
+
+- **WHEN** the user attempts to query more than 31 days
+- **THEN** the frontend MUST prevent submission and explain the maximum range
+
+### Requirement: External Integration Investigation
+
+The admin frontend SHALL provide Integration overview, list and detail views through the documented endpoints. It SHALL preserve provider, direction, operation, raw result, derived result category, duration, state-change, trigger, resource, linkage, attempt, content-summary, fidelity and retention fields.
+
+#### Scenario: Apply overview filters to the list
+
+- **WHEN** a user selects an overview provider, direction or result
+- **THEN** the frontend MUST map `providers[].code` to `provider`, `directions[].code` to `direction`, `results[].code` to `result`, and `results[].category` to `result_category`
+- **AND** it MUST use `name` only as display text
+
+#### Scenario: Display Integration trend categories
+
+- **WHEN** the overview returns trend points
+- **THEN** the frontend MUST preserve the five categories `processing`, `succeeded`, `indeterminate`, `failed` and `not_sent`
+- **AND** it MUST use only the documented `hour` or `day` bucket
+
+#### Scenario: Inspect an Integration detail
+
+- **WHEN** a user opens an `integration_id` returned by a list, event reference or notification target
+- **THEN** the frontend MUST query the detail with that value unchanged
+- **AND** it MUST present the capability as read-only without recovery, modification, deletion or export actions
+
+### Requirement: Role-Specific Resource Activity
+
+The frontend SHALL use the agent and enterprise resource-activity endpoints according to the authenticated subject. Agent activity SHALL support `iot_card`, `device`, `asset_allocation_record`, `exchange_order`, `shop` and `enterprise`; enterprise activity SHALL support only authorized `iot_card` and `device` resources.
+
+#### Scenario: Open an agent resource activity
+
+- **WHEN** an agent opens activity for a supported resource
+- **THEN** the frontend MUST use ICCID for a card, VirtualNo for a device, or the documented stable business number for another supported resource
+- **AND** it MUST NOT send or infer the agent identity or shop scope as query data
+
+#### Scenario: Open enterprise asset activity
+
+- **WHEN** an enterprise user opens an authorized card or device activity
+- **THEN** the frontend MUST use ICCID or VirtualNo with the enterprise endpoint
+- **AND** it MUST render only the subject-safe projection without platform actor, risk, internal reason or before/after fields
+
+#### Scenario: A stable subject identifier is missing
+
+- **WHEN** a business response does not contain the required ICCID, VirtualNo or stable business number
+- **THEN** the frontend MUST hide the activity entry
+- **AND** it MUST NOT substitute a display name or internal identifier intended for another subject
+
+### Requirement: Business Audit Entries
+
+The frontend SHALL add role-appropriate audit entries to card, device, shop, enterprise, order, refund and wallet list/detail contexts without changing existing business API URLs. Platform entries SHALL use backend internal IDs; agent and enterprise entries SHALL use their documented stable business identifiers.
+
+#### Scenario: Open platform asset or business history
+
+- **WHEN** a platform user opens audit history from a card, device, shop, enterprise, order or refund record
+- **THEN** the frontend MUST use the corresponding `resource_type` and backend `response.data.id` with the resource timeline
+
+#### Scenario: Open wallet or transaction history
+
+- **WHEN** a user opens audit history for a wallet, order or refund with a stable ID
+- **THEN** the frontend MUST offer the applicable finance timeline query
+- **AND** the resource timeline MAY also be offered only when a stable resource reference is available
+
+#### Scenario: Preserve existing operation logs
+
+- **WHEN** new audit entries are introduced on asset pages
+- **THEN** existing asset operation-log features MUST remain available
+- **AND** the UI MUST distinguish the existing operation logs from the new cross-system audit investigation
+
+### Requirement: Controlled Notification Integration Target
+
+The frontend SHALL resolve a notification through `GET /api/admin/notifications/{id}/target` before opening an Integration detail. It SHALL open the detail only when the target is available, has `target_type=integration_log`, and contains a non-empty `target_key`.
+
+#### Scenario: Open an Integration notification
+
+- **WHEN** target resolution returns `available=true`, `target_type=integration_log`, and a non-empty `target_key`
+- **THEN** the frontend MUST pass `target_key` unchanged as the Integration `integration_id`
+- **AND** it MUST open the controlled internal Integration detail route
+
+#### Scenario: Notification target cannot be used
+
+- **WHEN** the target is unavailable, has another type, lacks `target_key`, or maps to no registered route
+- **THEN** the frontend MUST not navigate or execute an arbitrary URL
+- **AND** it MUST preserve the notification content and show a safe unavailable-target message
+
+### Requirement: Audit Authorization and Read-Only Boundary
+
+The frontend SHALL enforce the final platform, agent and enterprise route and action permissions, while preserving backend authentication, authorization and data-isolation enforcement. All capabilities in this change SHALL remain read-only.
+
+#### Scenario: A subject lacks audit permission
+
+- **WHEN** the current subject lacks the configured permission for an audit page or business entry
+- **THEN** the frontend MUST hide or disable that page or entry and MUST NOT call the endpoint as a fallback
+
+#### Scenario: An audit request is rejected
+
+- **WHEN** an endpoint returns `400`, `401`, `403` or `500`
+- **THEN** the frontend MUST use shared validation, authentication, authorization and server-error handling
+- **AND** it MUST preserve the current investigation state when retrying would be unsafe or misleading
+
+#### Scenario: A user inspects an audit record
+
+- **WHEN** any audit, risk, finance, Integration or subject-activity view is displayed
+- **THEN** the UI MUST NOT provide mutation, recovery, deletion, risk-disposition, blocking or export actions
--- a/openspec/changes/add-audit-chain-frontend-integration/tasks.md
+++ b/openspec/changes/add-audit-chain-frontend-integration/tasks.md
@@ -0,0 +1,44 @@
+## 1. Contract and Shared Infrastructure
+
+- [x] 1.1 根据 `默认模块.openapi.json` 建立审计事件、调查引用、资源、保留窗口、链路节点、资金节点、风险和 Integration 的 TypeScript 类型。
+- [x] 1.2 新增平台审计、主体资源活动、资金、风险、Integration 和链路时间线 API 方法，保持文档参数名、枚举和 nullable 语义。
+- [x] 1.3 建立共享的分页、RFC3339 时间范围、保留窗口、枚举名称和 API 错误展示能力。
+- [x] 1.4 建立只读事件详情、资源摘要、调查引用和时间线节点组件，不提供写操作或导出能力。
+
+## 2. Platform Audit Center
+
+- [x] 2.1 实现审计事件列表及文档定义的时间、动作、类别、操作者、来源、结果、风险、范围、资源和链路筛选。
+- [x] 2.2 实现事件详情，展示事件、操作者、资源快照、结果、风险和元数据，并按非空 `investigation_refs` 提供跳转。
+- [x] 2.3 实现操作者行为时间线，使用 `actor_ref.kind/id` 和稳定 code 筛选。
+- [x] 2.4 实现资源精确搜索及资源时间线，原样使用选中项的 `resource_type/resource_id` 并提示历史快照命中。
+- [x] 2.5 实现请求和业务关联时间线，支持从返回引用进入，以及明确粘贴 Access Log `request_id` 的查询入口。
+
+## 3. Specialized Investigations
+
+- [x] 3.1 实现资金调查时间线和全部文档筛选条件，以分为数据单位并展示金额权威来源。
+- [x] 3.2 实现风险总览和风险事件明细，按总览返回的稳定 code 回填筛选，并限制最长 31 天时间范围。
+- [x] 3.3 实现 Integration 总览、列表和详情，覆盖 provider、direction、result、result_category、趋势、尝试、内容摘要、保真度和关联字段。
+- [x] 3.4 实现各调查视角之间基于 `investigation_refs`、`linkage` 和稳定资源引用的受控跳转。
+
+## 4. Subject Activity and Business Entries
+
+- [x] 4.1 实现代理资源活动页面，支持卡、设备、资产分配记录、换货单、店铺和企业的稳定业务标识。
+- [x] 4.2 实现企业资源活动页面，仅支持当前授权卡和设备并只渲染主体安全投影。
+- [x] 4.3 在卡、设备、店铺、企业、订单、退款和钱包列表/详情增加角色匹配的「审计记录」入口。
+- [x] 4.4 缺少内部 ID、ICCID、VirtualNo 或业务编号时隐藏入口，不使用页面文本或其他字段推断。
+- [x] 4.5 保留现有资产操作日志入口，并通过命名与说明区分旧操作日志和新审计调查能力。
+
+## 5. Notification, Routes, and Permissions
+
+- [x] 5.1 增加审计中心、风险中心、Integration 和共享时间线的路由与菜单配置。
+- [x] 5.2 接入最终确认的平台、代理、企业菜单/按钮权限编码，隐藏越权页面和业务入口。
+- [x] 5.3 在通知目标导航中仅对可用 `integration_log` 目标开放 Integration 详情，并原样使用 `target_key`。
+- [x] 5.4 对未知、不可用或缺失目标保留安全提示，不执行任意 URL 或推测跳转。
+
+## 6. Verification
+
+- [ ] 6.1 为 API 参数序列化、枚举、nullable 字段、分页和 RFC3339 时间范围增加单元测试。
+- [ ] 6.2 为稳定引用跳转、空引用隐藏、`fidelity=false`、通知 Integration 目标和禁止生成链路 ID 增加测试。
+- [ ] 6.3 验证平台、代理、企业角色可见性、服务端数据隔离、企业安全投影以及 `401/403/400/500` 处理。
+- [ ] 6.4 验证保留窗口、空数据、最长 31 天风险查询、资金金额单位和 Integration 五类趋势状态。
+- [ ] 6.5 完成 16 个接口的联调回归，并确认现有业务 URL、通知中心和旧资产操作日志未被破坏。
--- a/openspec/changes/align-audit-cross-view-navigation/design.md
+++ b/openspec/changes/align-audit-cross-view-navigation/design.md
@@ -0,0 +1,52 @@
+## Context
+
+审计调查横跨平台、代理和企业三种身份，以及事件、资源、请求、业务链路、资金和外部交互等多种事实视角。后端通过内部资源 ID、主体安全 identifier、`investigation_refs`、Integration `linkage` 和 `fidelity` 明确表达可导航关系；前端的职责是原样传递这些稳定引用，而不是补全关系。
+
+现有实现已经形成 `AuditInvestigationDrawer`、`AuditResourceSearchDialog` 和全局控制器，但业务页面仍需逐一核对入口覆盖、角色映射和降级规则。本设计将导航判断集中到共享目标解析层，展示仍由只读组件负责。
+
+## Goals / Non-Goals
+
+- Goals: 用一个类型安全的目标模型表达所有允许的审计调查入口。
+- Goals: 完成文档中资产、组织、账号、交易、资金和调查节点的导航矩阵。
+- Goals: 保证平台、代理和企业仅调用各自允许的接口，并隐藏缺少稳定参数的入口。
+- Goals: 使用弹窗/右侧抽屉承载续查，锁定底层滚动并支持分页与空状态。
+- Non-Goals: 不修改后端链路生成、数据库、留存或授权规则。
+- Non-Goals: 不提供恢复、重试、处置、封禁、修改、删除或导出。
+- Non-Goals: 不把旧 operation log 合并进新审计链路。
+- Non-Goals: 不从 Access Log、历史队列、自由文本或时间邻近关系自动发现链路。
+
+## Decisions
+
+- Decision: 使用判别联合类型描述 `event/actor/resource/request/correlation/finance/integration/agent/enterprise` 调查目标；调用方只能提交该目标模型，不能提交任意 URL。
+- Decision: 使用全局调查宿主承载共享抽屉和精确资源弹窗。业务页面操作只负责构造目标，不各自维护弹窗、加载和滚动状态。
+- Decision: 独立的审计中心列表与详情可以保留路由；跨视角时间线和关联详情使用抽屉。移除旧时间线路由、别名和所有指向它的跳转。
+- Decision: 平台资源入口优先使用业务响应中的内部稳定 ID。只有调用上下文没有资源 ID、但明确持有 `iot_card/device/shop/order/refund` 的业务 Key 时，才进入精确资源搜索。
+- Decision: 精确资源搜索不展示 `resource_id` 或身份快照中的内部关联 ID。候选项只展示按资源类型白名单选择的业务字段；选中后在内部原样使用返回的 `resource_type/resource_id`。
+- Decision: 代理使用 ICCID、VirtualNo、分配单号、换货单号、店铺编号或企业编号；企业只使用当前授权卡的 ICCID 或设备 VirtualNo。主体身份和范围不作为前端参数。
+- Decision: `investigation_refs` 是调查节点续查的权威来源。字段缺失、目标与当前详情相同或 `fidelity=false` 时隐藏对应操作。
+- Decision: 请求和业务链路 ID 默认不展示原值；仅在明确的超级管理员开发调查上下文中允许复制真实 request ID，且不得由前端生成。
+- Decision: 资金目标只提交一个已知稳定条件，其他订单、支付、退款、充值和钱包关联由服务端解析；金额始终按分保存在应用数据中。
+- Decision: `401/403`、授权撤销或主体资源不存在时显示中性“活动不可用”，不回退平台接口、精确资源搜索或旧 operation log。
+- Decision: 所有抽屉使用 `append-to-body`、modal 和 scroll lock，关闭后销毁内容；分页切换保留目标和筛选，切换目标时清空旧数据。
+
+## Risks / Trade-offs
+
+- 业务页面数量多，容易出现入口漏接或使用错误字段。通过集中目标解析函数和表驱动测试覆盖文档矩阵。
+- 全局抽屉减少重复代码，但必须防止上一目标的数据闪现。打开新目标前先清空状态，并以当前请求标识忽略过期响应。
+- 精确资源搜索结果来自当前表或历史快照；仅展示白名单字段会减少调试信息，但可以避免泄露内部 ID 和不稳定结构。
+- 本变更与 `add-audit-chain-frontend-integration` 修改同一组件目录。实施前必须以其最新状态为基线，避免覆盖已完成的 UI 调整。
+
+## Migration Plan
+
+1. 固化共享调查目标类型、控制器和角色解析函数，并为现有入口提供兼容适配。
+2. 将仍指向旧时间线路由的入口切换为全局调查宿主，确认无引用后删除旧页面、路由和别名。
+3. 按文档矩阵依次接入资产组织页、账号交易页、资金页和调查节点续查。
+4. 收紧精确搜索触发条件、主体视角和空标识降级规则。
+5. 完成角色矩阵、参数原样传递、禁止推断、弹窗滚动和过期请求测试。
+6. 若出现回归，可按业务模块隐藏新入口；不恢复任意 URL 跳转或 ID 推断逻辑。
+
+## Open Questions
+
+- 账号、代理充值、资产分配、换货、店铺资金概况等尚未接入页面的最终按钮权限是否沿用资源时间线/资金时间线权限，还是增加业务入口专用权限？
+- 超级管理员是否需要一个显式的 Access Log request ID 粘贴入口；若不需要，前端应完全移除手工 request 查询。
+- `historical=true` 在产品要求隐藏“匹配来源”后，是否仍需用非字段式的警告图标提示资源可能已删除？
--- a/openspec/changes/align-audit-cross-view-navigation/implementation-audit.md
+++ b/openspec/changes/align-audit-cross-view-navigation/implementation-audit.md
@@ -0,0 +1,41 @@
+## 实施差异核对
+
+### 已接入矩阵
+
+| 来源 | 平台视角 | 代理视角 | 企业视角 | 稳定字段 |
+| --- | --- | --- | --- | --- |
+| IoT 卡列表/统一资产详情 | 资源时间线 | 主体活动 | 主体活动 | `id` / `iccid` |
+| 设备列表/统一资产详情 | 资源时间线 | 主体活动 | 主体活动 | `id` / `virtual_no` |
+| 设备绑定卡 | 卡资源时间线、绑定资源时间线 | 卡主体活动 | 卡主体活动 | `card_id` / `iccid` |
+| 资产分配列表/详情 | 分配记录、资产资源时间线 | 分配活动 | 不提供 | `id`、`asset_id` / `allocation_no` |
+| 换货列表/详情 | 换货记录、旧/新资产时间线 | 换货活动 | 不提供 | `id`、资产 ID / `exchange_no` |
+| 店铺列表 | 店铺资源、店铺资金链路 | 店铺活动 | 不提供 | `id` / `shop_no` |
+| 企业列表 | 企业资源 | 企业活动 | 不提供 | `id` / `enterprise_no` |
+| 账号列表 | 账号资源 | 不提供 | 不提供 | `id` |
+| 订单列表/详情 | 订单资源、订单资金链路 | 不提供 | 不提供 | `id`、`order_id` |
+| 退款列表/详情 | 退款资源、退款资金链路、审批资源 | 不提供 | 不提供 | `id`、`refund_id`、`approval_instance_id` |
+| 代理充值列表/详情 | 充值资源、充值资金链路、审批资源 | 不提供 | 不提供 | `id`、`recharge_id`、`approval_instance_id` |
+| 资产钱包 | 钱包资金链路、资产资源 | 不提供 | 不提供 | `wallet_id`、`asset_type + asset_id` |
+| 店铺资金概况 | 店铺资金链路 | 不提供 | 不提供 | `shop_id` |
+
+所有入口先独立校验自身权限和完整参数；一个入口缺字段不会隐藏同一行的其他有效入口。平台资源只使用非零内部 ID，代理和企业活动只使用文档规定的业务标识。
+
+### 共享调查与降级
+
+- 事件、操作者、资源、请求、业务链路、资金、Integration、代理活动和企业活动均由全局调查宿主打开。
+- 精确注册资源只在调查引用缺少 `resource_id`、但包含受支持类型及业务 Key 时出现；业务列表已有内部 ID 时不再提供搜索按钮。
+- 精确搜索限制为 `iot_card/device/shop/order/refund`，候选项不显示 Registry ID 或快照内部关联 ID。
+- 目标切换会清空旧内容并忽略过期响应；关闭会销毁内容，抽屉和弹窗锁定底层滚动。
+- 缺字段、空白值、零值、不支持的主体资源类型和撤销授权均不推断或回退到其他视角。
+
+### 受响应字段限制的入口
+
+- 钱包流水响应只有 `asset_identifier`，没有完整的 `asset_type + asset_id`，因此不从流水行推断资产审计目标。
+- 当前路由中没有独立的账号详情和店铺详情页面，对应入口保留在列表。
+- 风险/链路/资金节点抽屉内部不增加继续调查按钮：产品要求移除弹窗内无意义按钮；事件详情仍使用权威 `investigation_refs` 提供跨视角入口。
+
+### 路由核对
+
+- 独立的审计事件和外部交互列表/详情路由保留。
+- 操作者、资源、请求、业务链路、资金及主体活动不再使用独立时间线路由或任意 URL 跳转。
+- 审计中心顶级菜单排列在财务管理之后。
--- a/openspec/changes/align-audit-cross-view-navigation/proposal.md
+++ b/openspec/changes/align-audit-cross-view-navigation/proposal.md
@@ -0,0 +1,40 @@
+# Change: 对齐审计跨视角调查与前端导航契约
+
+## Why
+
+现有审计中心已经接入事件、资源、链路、资金、风险和外部交互等只读查询，但业务页面入口、调查节点续查、平台/代理/企业视角以及缺失标识时的降级行为仍缺少统一约束。若各页面继续自行拼装目标参数，容易把内部 ID、业务 Key、主体安全标识或链路 ID 混用，并产生越权回退、错误串链和重复页面。
+
+本变更以《跨视角调查与前端导航契约.md》为导航事实来源，在现有 `add-audit-chain-frontend-integration` 能力之上建立统一的跨视角导航规范和复用组件。
+
+## What Changes
+
+- 建立统一的审计调查目标模型和导航控制器，覆盖事件详情、操作者行为、资源审计、请求链路、业务链路、资金链路、外部交互以及代理/企业资源活动。
+- 调查时间线、链路和外部交互续查统一使用可复用抽屉或弹窗，不再新增独立时间线跳转页面；同一目标不重复打开自身详情。
+- 按“内部稳定 ID → 主体安全业务标识 → 返回的调查引用 → 精确资源搜索 → 隐藏入口”的顺序解析入口，禁止从名称、摘要、时间、编号前缀或邻近记录推断关联。
+- 对齐资产、组织、账号、订单、退款、充值、钱包和资金页面的逐行入口矩阵，并按平台、代理、企业身份选择不同接口和参数。
+- 平台仅在缺少内部资源 ID、但持有允许搜索的 Registry Key 时调用精确资源搜索；零命中或多命中均保留用户选择，不自动猜测。
+- 所有弹窗和抽屉只显示业务可读字段，内部资源 ID、request/correlation 等技术标识仅作为查询参数使用，除明确的开发调查场景外不直接展示。
+- 统一处理空引用、`fidelity=false`、历史快照、授权撤销、归档窗口和接口拒绝，不回退旧日志、平台接口或其他主体接口。
+- 补充跨页面入口矩阵、参数映射、角色隔离和禁止推断的自动化测试。
+
+## Impact
+
+- Affected specs: `audit-cross-view-navigation`
+- Depends on: `add-audit-chain-frontend-integration`
+- Affected code:
+  - `src/components/business/audit/` 调查抽屉、精确资源弹窗和全局导航控制器
+  - `src/utils/business/auditNavigation.ts` 角色与目标解析
+  - 审计事件、风险、外部交互页面的调查入口
+  - 卡、设备、设备卡槽、统一资产、分配、换货、店铺、企业、账号、订单、退款、充值、钱包及资金列表/详情
+  - 路由、权限和通知目标导航
+- API contracts:
+  - `GET /api/admin/audit/*`
+  - `GET /api/admin/agent/resource-activities/{resource_type}/{identifier}`
+  - `GET /api/admin/enterprise/resource-activities/{resource_type}/{identifier}`
+  - 现有业务列表与详情接口返回的稳定字段
+- Source of truth:
+  - `docs/产品迭代8月份/跨视角调查与前端导航契约.md`
+  - `docs/产品迭代8月份/默认模块.openapi.json`
+- Breaking changes:
+  - 移除旧的独立审计时间线路由及其导航方式，统一改为抽屉/弹窗调查。
+  - 入口缺少契约要求的稳定标识时将被隐藏，不再容忍前端推断或降级调用其他视角接口。
--- a/openspec/changes/align-audit-cross-view-navigation/specs/audit-cross-view-navigation/spec.md
+++ b/openspec/changes/align-audit-cross-view-navigation/specs/audit-cross-view-navigation/spec.md
@@ -0,0 +1,124 @@
+## ADDED Requirements
+
+### Requirement: Shared Cross-View Investigation Surface
+
+The frontend SHALL open actor, resource, request, correlation, finance, Integration, agent-activity and enterprise-activity investigations through reusable modal or drawer components. It SHALL NOT require a standalone timeline route for these cross-view investigations.
+
+#### Scenario: Open an investigation from a business row
+
+- **WHEN** an authorized user selects an audit or activity action from a supported business row
+- **THEN** the frontend MUST construct a typed investigation target from the row's documented stable fields
+- **AND** it MUST open the shared investigation surface without navigating to a standalone timeline page
+
+#### Scenario: Replace an open investigation target
+
+- **WHEN** the user opens a second investigation after another target was loaded
+- **THEN** the shared surface MUST clear stale content before loading the new target
+- **AND** a late response from the previous target MUST NOT replace the current result
+
+### Requirement: Deterministic Investigation Target Resolution
+
+The frontend SHALL resolve investigation targets in this order: a platform internal stable ID for a platform resource timeline, a documented subject-safe business identifier for agent or enterprise activity, an explicit API investigation reference, an exact Registry resource-key search when no internal resource ID exists, or no entry. It SHALL NOT infer a target from display text or proximity.
+
+#### Scenario: A platform resource ID is available
+
+- **WHEN** a platform business response contains the documented non-zero internal resource ID
+- **THEN** the frontend MUST call the resource timeline with the mapped resource type and that ID
+- **AND** it MUST NOT search by the display name or business Key to replace the available ID
+
+#### Scenario: Only a supported Registry Key is available
+
+- **WHEN** a platform investigation reference contains a supported resource type and business Key but no resource ID
+- **THEN** the frontend MUST use the exact resource search endpoint
+- **AND** zero or multiple matches MUST remain unresolved until the user makes an explicit choice
+
+#### Scenario: No stable target exists
+
+- **WHEN** the required internal ID, subject identifier or explicit investigation reference is missing
+- **THEN** the frontend MUST hide or disable the entry
+- **AND** it MUST NOT infer a relationship from a name, summary, timestamp, identifier prefix, adjacent record or current-account profile
+
+### Requirement: Exact Registered Resource Selection
+
+The frontend SHALL support exact Registry lookup only for `iot_card`, `device`, `shop`, `order` and `refund`. It SHALL pass the selected candidate's returned `resource_type/resource_id` unchanged to the resource timeline while keeping internal identifiers out of the presentation.
+
+#### Scenario: Present an exact resource candidate
+
+- **WHEN** exact lookup returns a candidate with `identity_snapshot`
+- **THEN** the frontend MUST display only a resource-type-specific whitelist of business-readable fields
+- **AND** it MUST NOT display `resource_id` or snapshot fields that are internal IDs or internal foreign keys
+
+#### Scenario: Select a historical candidate
+
+- **WHEN** a user selects a candidate with `historical=true` and a stable returned resource ID
+- **THEN** the frontend MUST use the returned type and ID without modification
+- **AND** it MUST NOT claim that the resource still exists in the current business table
+
+### Requirement: Role-Isolated Resource Activity Navigation
+
+The frontend SHALL choose platform, agent or enterprise resource investigation APIs solely from the authenticated subject and the documented source-page fields. Agent and enterprise navigation SHALL NOT fall back to platform audit or Registry search.
+
+#### Scenario: Open agent activity
+
+- **WHEN** an agent opens a supported card, device, allocation, exchange, shop or enterprise activity
+- **THEN** the frontend MUST use the documented ICCID, VirtualNo or business number with the agent activity endpoint
+- **AND** it MUST NOT send agent identity or shop scope as proof of authorization
+
+#### Scenario: Open enterprise activity
+
+- **WHEN** an enterprise user opens activity for a currently authorized card or device
+- **THEN** the frontend MUST use ICCID or VirtualNo with the enterprise activity endpoint
+- **AND** it MUST NOT use the enterprise route parameter or a platform internal ID as authorization evidence
+
+#### Scenario: Subject activity becomes unavailable
+
+- **WHEN** authorization is revoked, the resource is out of scope, or the subject endpoint rejects access
+- **THEN** the frontend MUST present an activity-unavailable state
+- **AND** it MUST NOT retry through a platform endpoint, Registry search or legacy operation log
+
+### Requirement: Business and Finance Entry Matrix
+
+The frontend SHALL implement the documented row-level navigation matrix for asset, organization, account, order, refund, recharge, wallet and fund-summary contexts. Each action SHALL be independently visible only when its complete stable parameter set and required permission are available.
+
+#### Scenario: Open resource and finance investigations independently
+
+- **WHEN** a business record contains both a resource ID and a stable finance condition
+- **THEN** the frontend MUST offer the applicable resource audit and finance investigation actions independently
+- **AND** failure or absence of one parameter set MUST NOT suppress the other valid action
+
+#### Scenario: Let the server resolve finance relationships
+
+- **WHEN** the frontend opens finance history from an order, refund, recharge, wallet or shop
+- **THEN** it MUST submit only the stable condition explicitly returned by the source business API
+- **AND** it MUST NOT derive or supplement payment, refund, wallet, approval or third-party identifiers from text or number prefixes
+
+### Requirement: Investigation Reference Continuation
+
+The frontend SHALL treat `investigation_refs` and documented Integration references as the authoritative sources for continuing from audit, risk, finance and link nodes. It SHALL expose only actions whose complete required reference is present and reliable.
+
+#### Scenario: Continue from a complete reference
+
+- **WHEN** a node contains a complete actor, resource, request, correlation or Integration reference
+- **THEN** the frontend MUST pass its type and identifier unchanged to the matching shared investigation surface
+
+#### Scenario: Suppress unavailable or self-referential navigation
+
+- **WHEN** a reference is incomplete, its fidelity is false, or its event target is the detail already being displayed
+- **THEN** the frontend MUST hide the corresponding action
+- **AND** it MUST NOT create a substitute identifier or reopen the same detail
+
+### Requirement: Read-Only Presentation and Scroll Isolation
+
+All shared investigation surfaces SHALL remain read-only, hide non-business internal identifiers by default, and isolate modal scrolling from the underlying page.
+
+#### Scenario: Display an investigation surface
+
+- **WHEN** a modal or drawer is open
+- **THEN** it MUST use a modal overlay, append to the document body, and lock underlying-page scrolling
+- **AND** it MUST remain usable within its own scroll container at supported viewport sizes
+
+#### Scenario: Inspect a read-only result
+
+- **WHEN** audit, activity, finance, link or Integration data is displayed
+- **THEN** the UI MUST NOT expose mutation, recovery, retry, deletion, disposition, blocking or export actions
+- **AND** raw internal IDs MUST be retained only as navigation parameters unless an explicitly authorized developer-investigation workflow requires display
--- a/openspec/changes/align-audit-cross-view-navigation/tasks.md
+++ b/openspec/changes/align-audit-cross-view-navigation/tasks.md
@@ -0,0 +1,44 @@
+## 1. Contract Audit and Shared Navigation
+
+- [ ] 1.1 建立文档导航矩阵与当前页面入口的差异清单，覆盖资产组织、账号交易、资金和调查节点。
+- [ ] 1.2 完善共享调查目标判别联合类型，覆盖事件、操作者、资源、请求、业务链路、资金、Integration、代理和企业活动。
+- [ ] 1.3 将共享导航控制器改为唯一弹窗/抽屉打开入口，并处理目标切换、请求竞态、分页和关闭清理。
+- [ ] 1.4 全局搜索并移除旧时间线路由、路由别名、页面和任意 URL 式审计跳转。
+
+## 2. Stable Reference and Search Rules
+
+- [ ] 2.1 实现平台内部 ID、主体业务 identifier、调查引用、资源 Key 搜索和隐藏入口的优先级解析。
+- [ ] 2.2 收紧精确资源搜索，仅允许 `iot_card/device/shop/order/refund` 和文档规定的精确业务 Key。
+- [ ] 2.3 精确资源结果只展示资源类型白名单业务字段，隐藏 `resource_id` 及快照内部关联 ID，并原样使用返回目标打开资源时间线。
+- [ ] 2.4 对零命中、多命中、历史快照和缺少稳定资源 ID 分别提供不推断的降级状态。
+- [ ] 2.5 对空引用、同目标引用和 `fidelity=false` 隐藏对应调查操作。
+
+## 3. Asset and Organization Entry Matrix
+
+- [ ] 3.1 对齐卡、设备、设备卡槽和统一资产详情的平台/代理/企业入口与稳定字段映射。
+- [ ] 3.2 对齐资产分配、换货、店铺和企业列表/详情入口及角色范围。
+- [ ] 3.3 对齐企业卡和企业设备列表入口，确保企业只调用主体活动接口且不使用路由企业 ID 证明授权。
+- [ ] 3.4 缺少内部 ID、ICCID、VirtualNo 或业务编号时隐藏对应入口，不回退其他视角。
+
+## 4. Account, Transaction, and Finance Entry Matrix
+
+- [ ] 4.1 接入账号、店铺、企业、订单和退款的资源审计入口。
+- [ ] 4.2 接入订单、退款、代理充值、资产钱包、店铺资金概况和钱包流水的资金链路入口。
+- [ ] 4.3 对审批实例、钱包资源和流水资产引用实行独立字段完整性判断，缺少一组字段不影响其他有效入口。
+- [ ] 4.4 资金查询仅传入当前业务返回的稳定条件，不由前端补齐 Payment、Refund、钱包或第三方流水关联。
+
+## 5. Investigation Node Continuation
+
+- [ ] 5.1 从风险、事件、资源、链路、资金和 Integration 节点按 `investigation_refs` 打开共享调查抽屉。
+- [ ] 5.2 支持事件、操作者、资源、请求、业务链路和外部交互的非空引用，并抑制跳回当前详情的无意义入口。
+- [ ] 5.3 请求/业务链路节点保留 `record_source` 和 `reference_only` 事实边界，不把投递成功展示为业务成功。
+- [ ] 5.4 通知 Integration 目标继续使用受控 target 解析，不接受任意 URL 或数据库主键替代稳定 Integration ID。
+
+## 6. Authorization, Presentation, and Verification
+
+- [ ] 6.1 按平台、代理、企业及按钮权限验证所有入口可见性和接口选择。
+- [ ] 6.2 验证抽屉 append-to-body、遮罩、底层滚动锁定、关闭销毁、分页和移动端布局。
+- [ ] 6.3 为目标解析、参数原样传递、空值隐藏、同目标抑制、`fidelity=false` 和禁止推断增加单元测试。
+- [ ] 6.4 为文档中资产组织和账号资金导航矩阵增加表驱动测试。
+- [ ] 6.5 验证 `400/401/403/404/500`、授权撤销、历史快照、归档窗口和过期异步响应处理。
+- [ ] 6.6 回归现有审计中心、风险中心、外部交互、通知导航和旧 operation log，确认只读边界未被破坏。