8.2 KiB
ADDED Requirements
Requirement: Permission-aware operations overview
The console SHALL provide an overview that derives server, Run endpoint, job, resource, AI provider, and audit summaries from Platform API responses permitted for the active session.
Scenario: Operator opens overview with available APIs
- WHEN the active session can read the overview and the required Platform APIs return data
- THEN the console shows real counts, resource measurements, active and failed job summaries, endpoint health, and actionable signals derived from those responses
Scenario: Session lacks a management capability
- WHEN a session can view an operational resource but lacks the capability required to mutate it
- THEN the console presents a read-only explanation and does not dispatch the mutation
Requirement: Independent module truth and recovery
Each overview and management data module MUST distinguish loading, ready-empty, ready-data, and unavailable states, and MUST provide scoped retry without treating an API failure as an empty or healthy result.
Scenario: Audit API fails while core overview succeeds
- WHEN server and job APIs succeed but the audit API fails
- THEN core health remains visible, audit signals are marked unavailable, and the page does not claim that there are no recent audit signals
Scenario: Failed module is retried
- WHEN an operator retries an unavailable module and its API succeeds
- THEN only that module transitions to ready data and its refresh timestamp is updated
Requirement: Real job and mutation progress
Long-running work MUST use Platform job identifiers and job states, while immediate mutations MUST remain pending until the Platform response returns and MUST never use timers or optimistic local success.
Scenario: Long-running server operation is queued
- WHEN a server operation returns a job identifier
- THEN the console polls the Platform job projection and shows queued, claimed, running, retrying, terminal success, or terminal failure from that projection
Scenario: Mutation is rejected
- WHEN the Platform rejects a plugin, user, server, or AI provider mutation
- THEN the previous resource state remains visible and the console shows the rejection with a retry or corrective action when applicable
Requirement: Confirmed disruptive operations
Persistent or disruptive resource state changes MUST require resource-specific confirmation and MUST prevent duplicate submission while a request is pending.
Scenario: Plugin state change is confirmed
- WHEN an authorized operator chooses install, enable, or disable and confirms the named plugin action
- THEN the console dispatches one Platform request, disables duplicate confirmation, and refreshes state from the persisted response
Scenario: Confirmation is cancelled
- WHEN an operator cancels a confirmation or presses Escape before submission
- THEN no mutation is dispatched and the current resource state is preserved
Requirement: Server operations workspace
Server management SHALL expose API telemetry availability, deterministic search/filter/sort, active and failed job counts, and recovery-oriented navigation without covering or reflowing server-card operational data.
Scenario: Metrics are unavailable
- WHEN the server list succeeds but metrics loading fails
- THEN server cards remain available, metrics are labeled unavailable rather than zero, and a scoped metrics retry is offered
Scenario: Server has active or failed jobs
- WHEN Platform jobs reference a visible server
- THEN the server working surface shows the real active or failed job count and lets the operator open the server detail or job progress workflow
Requirement: Plugin marketplace operations
The plugin marketplace SHALL use Platform list/detail/state responses, permission-gated commands, confirmation, action progress, and failure recovery without production fallback data.
Scenario: Plugin state response succeeds
- WHEN the Platform accepts a confirmed plugin state action
- THEN list and detail views update from the returned or refreshed Platform plugin state and the action result is traceable
Scenario: Plugin detail refresh fails
- WHEN the selected plugin summary exists but its detail API fails
- THEN the summary remains visible, detail is marked unavailable, and the operator can retry detail loading without reloading the page
Requirement: User management operations
User management SHALL render only Platform API data in normal operation and SHALL provide search, role/status filtering, create/edit/status/deactivate feedback, and API-scoped retry.
Scenario: User API fails in development
- WHEN the normal user list API fails in a development build
- THEN the page shows an unavailable state and does not replace the result with actionable sample users
Scenario: User filters are applied
- WHEN an authorized operator enters a query or selects role/status filters
- THEN the full-width user working surface shows only matching Platform users and keeps create/edit flows in dialogs
Requirement: AI provider operations
AI provider management SHALL provide scoped list retry, action-level busy states, confirmed status/retirement changes, persisted-response refresh, and safe key configuration presence.
Scenario: Provider load is retried
- WHEN the provider list fails and the operator retries
- THEN the page calls the provider list API again without a full browser reload and renders the returned state
Scenario: Provider status action is pending
- WHEN an authorized operator confirms enable, disable, or retire
- THEN only that provider action is disabled, duplicate submission is prevented, and success is shown only after a Platform response
Requirement: Session operation tray
The console SHALL expose a compact, theme-aware tray for current-session mutation records while clearly distinguishing it from durable Platform job and audit history.
Scenario: Operation fails
- WHEN a tracked mutation fails
- THEN the tray shows the intent, safe target label, failure reason, and diagnostic identifier without exposing forbidden values
Scenario: No session operations exist
- WHEN no mutation has been attempted in the current session
- THEN the tray remains compact and communicates that durable job and audit history is available on the relevant operational pages
Requirement: Theme, responsive, and secret safety
All new operations surfaces MUST use existing theme tokens and shared styles, MUST remain coherent in black-mecha and magical-girl themes at desktop and 390px, and MUST not render raw keys, tokens, secret values, host paths, PIDs, sockets, credentials, DSNs, RCON data, or direct Run endpoints.
Scenario: Theme changes
- WHEN an operator switches between black-mecha and magical-girl themes
- THEN overview modules, lists, confirmations, progress rows, and the operation tray update atomically through existing theme variables without page-local global decoration
Scenario: Narrow viewport renders operations surfaces
- WHEN the console is rendered at 390px width
- THEN controls and text remain within their containers, full-width working surfaces collapse deliberately, and no operational status or action is obscured
Scenario: Narrow viewport navigation stays out of page flow
- WHEN the console is rendered at 390px width with navigation closed
- THEN the sidebar, account strip, and icon rail do not consume page height, and a small theme-aware left-edge menu control remains available
Scenario: Operator opens and closes narrow navigation
- WHEN the operator activates the left-edge control or swipes right from within 28px of the viewport edge
- THEN an off-canvas vertical menu opens with icons and readable Chinese route labels in the existing order
- AND Escape, backdrop activation, route selection, or a leftward drawer swipe closes the menu
Scenario: Rendered output is scanned for forbidden fragments
- WHEN first-party pages are rendered with API-backed fixtures during verification
- THEN forbidden raw secret, path, process, socket, credential, DSN, RCON, and direct Run endpoint fragments are absent