feat: 审计链路

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` 在产品要求隐藏“匹配来源”后，是否仍需用非字段式的警告图标提示资源可能已删除？

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 跳转。
+- 审计中心顶级菜单排列在财务管理之后。

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:
+  - 移除旧的独立审计时间线路由及其导航方式，统一改为抽屉/弹窗调查。
+  - 入口缺少契约要求的稳定标识时将被隐藏，不再容忍前端推断或降级调用其他视角接口。

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

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，确认只读边界未被破坏。