208 lines
12 KiB
Markdown
208 lines
12 KiB
Markdown
## 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
|