one-pipe-system/openspec/changes/add-audit-chain-frontend-integration/specs/audit-chain-frontend-integration/spec.md

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