first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,93 @@
+## ADDED Requirements
+
+### Requirement: User actions have visible lifecycle feedback
+The platform web application SHALL show visible lifecycle feedback for user-triggered operations.
+
+#### Scenario: Button enters pending state
+- **WHEN** a user submits an operation from a button or form
+- **THEN** the initiating control shows a pending or loading state and prevents accidental duplicate submission until the operation state is known
+
+#### Scenario: Operation success is visible
+- **WHEN** a submitted operation completes successfully
+- **THEN** the UI shows a success result and provides relevant next actions such as viewing logs or operation history when available
+
+#### Scenario: Operation failure is visible
+- **WHEN** a submitted operation fails
+- **THEN** the UI shows a failure result with an error reason and relevant retry or diagnostic actions when available
+
+### Requirement: Operations are traceable
+The platform web application SHALL expose a traceable operation or job identity for operations that affect platform, run, plugin, server, or LLM systems.
+
+#### Scenario: Operation detail includes trace data
+- **WHEN** an operation is created or retrieved
+- **THEN** the UI can display its operation/job ID, target, requester, status, timestamps, and error reason when available
+
+#### Scenario: Failure includes diagnostic identifier
+- **WHEN** an operation or data load fails with a diagnostic identifier
+- **THEN** the UI displays the identifier or provides a copyable diagnostic summary for debugging
+
+### Requirement: One user intent maps to one visible business operation
+The platform web application SHALL present each user-triggered action as one visible business operation even if the backend performs multiple internal steps.
+
+#### Scenario: Complex action is tracked as one operation
+- **WHEN** a user triggers a complex action such as restart server, send gift, apply plugin control, or write configuration
+- **THEN** the UI displays one operation lifecycle for the user intent and tracks progress or result through one operation/job context
+
+#### Scenario: Multi-step backend failure is debuggable
+- **WHEN** an internal step of a complex action fails
+- **THEN** the operation result identifies the failing stage or error reason when that information is available
+
+### Requirement: Empty states are actionable
+The platform web application SHALL show actionable empty states instead of blank pages for expected no-data conditions.
+
+#### Scenario: Server list is empty for server administrator
+- **WHEN** a server administrator has no manageable servers
+- **THEN** the server list shows an empty state explaining that no manageable servers are available and provides a refresh action
+
+#### Scenario: Platform overview has no servers
+- **WHEN** a platform administrator opens the platform overview and no server instances exist
+- **THEN** the overview shows an empty state with a management-oriented next action rather than a blank page
+
+### Requirement: Loading states are scoped
+The platform web application SHALL use scoped loading states so one slow module does not blank unrelated content.
+
+#### Scenario: Dashboard module loads independently
+- **WHEN** one platform overview module is loading slowly
+- **THEN** the UI shows a loading state for that module while keeping already loaded modules visible
+
+#### Scenario: Server card metrics load independently
+- **WHEN** server metrics are still loading
+- **THEN** the server card remains visible with stable placeholders for pending metrics
+
+### Requirement: Errors identify affected scope
+The platform web application SHALL display errors with enough scope and recovery information for operators to act.
+
+#### Scenario: Module load error is localized
+- **WHEN** a dashboard module or server detail section fails to load
+- **THEN** the error is shown within the affected module or section with retry and diagnostic information when available
+
+#### Scenario: Full-page error preserves navigation
+- **WHEN** a full-page error prevents rendering the requested workspace
+- **THEN** the application preserves usable global navigation or a safe route back to an authorized workspace
+
+### Requirement: Dangerous actions require confirmation
+The platform web application SHALL require explicit confirmation for destructive or disruptive operations.
+
+#### Scenario: Restart or stop requires confirmation
+- **WHEN** a user initiates a disruptive server action such as stop or restart
+- **THEN** the UI asks for confirmation before submitting the operation
+
+#### Scenario: Configuration write requires diff confirmation
+- **WHEN** a user initiates a configuration write from manual edits or LLM output
+- **THEN** the UI requires the user to review and confirm the diff before submission
+
+### Requirement: AI and run safety boundaries are preserved
+The platform web application SHALL preserve platform AI provider and run communication safety boundaries in all redesigned interactions.
+
+#### Scenario: AI keys are never exposed to frontend
+- **WHEN** platform_web uses AI provider health or LLM assistance features
+- **THEN** raw AI keys and provider secrets are not exposed to platform_web or plugin pages
+
+#### Scenario: Run internals are not exposed to frontend
+- **WHEN** platform_web displays server operations, logs, artifacts, or diagnostics
+- **THEN** host paths, raw credentials, and direct run sockets are not exposed to platform_web or plugin pages
@@ -0,0 +1,71 @@
+## ADDED Requirements
+
+### Requirement: Role-based default workspace
+The platform web application SHALL route authenticated users to a default workspace based on their authorized role set.
+
+#### Scenario: Platform administrator lands on platform overview
+- **WHEN** an authenticated platform administrator opens the platform web application
+- **THEN** the application displays the platform overview as the default workspace
+
+#### Scenario: Server administrator lands on server list
+- **WHEN** an authenticated server administrator without platform administrator privileges opens the platform web application
+- **THEN** the application displays the server list as the default workspace
+
+#### Scenario: Server owner lands on server list
+- **WHEN** an authenticated server owner without platform administrator privileges opens the platform web application
+- **THEN** the application displays the server list as the default workspace
+
+### Requirement: Role-scoped navigation
+The platform web application SHALL render navigation entries only for areas the current user is authorized to use.
+
+#### Scenario: Platform administrator sees platform areas
+- **WHEN** a platform administrator views the desktop navigation
+- **THEN** the navigation includes platform overview, server management, plugin marketplace, user management, AI provider management, and system maintenance entries
+
+#### Scenario: Server administrator cannot see platform overview
+- **WHEN** a server administrator without platform administrator privileges views navigation
+- **THEN** the navigation does not include platform overview, user management, AI provider management, or system maintenance entries
+
+### Requirement: Platform overview first-screen health
+The platform overview SHALL present operational health information needed by platform administrators in the first screen without requiring navigation to secondary pages.
+
+#### Scenario: Platform overview shows required metrics
+- **WHEN** a platform administrator opens the platform overview
+- **THEN** the first screen shows server online/offline counts, game type distribution, CPU usage, memory usage, disk usage, and LLM connectivity health
+
+#### Scenario: Platform overview shows recent operational signals
+- **WHEN** recent logs, faults, or plugin update signals are available
+- **THEN** the platform overview displays a recent signal summary with entries that link to the relevant server, plugin, or AI provider context
+
+### Requirement: Server list first-screen operations
+The server list SHALL present the server status fields needed by server owners and server administrators in the first screen.
+
+#### Scenario: Server card shows required status
+- **WHEN** a server owner or server administrator views their server list
+- **THEN** each server card shows online/offline state, player count, TPS, latency, CPU usage, memory usage, and disk usage when available
+
+#### Scenario: Server list supports search and status filtering
+- **WHEN** a server owner or server administrator needs to find a server
+- **THEN** the server list provides search and status filtering controls without requiring access to platform overview
+
+### Requirement: Themeable game-style workspace
+The platform web application SHALL support a colorful anime/game visual style while preserving operational readability.
+
+#### Scenario: User-uploaded background is applied safely
+- **WHEN** a user applies an uploaded background image
+- **THEN** content panels, controls, logs, forms, and metric text remain readable through contrast surfaces or overlays
+
+#### Scenario: Status is not color-only
+- **WHEN** server, LLM, plugin, or operation status is displayed
+- **THEN** the status is represented with text or iconography in addition to color
+
+### Requirement: Responsive role workspace
+The platform web application SHALL adapt role-specific workspaces for narrow screens without removing essential first-screen information.
+
+#### Scenario: Platform overview on narrow screen
+- **WHEN** a platform administrator opens the platform overview on a narrow screen
+- **THEN** online/offline server counts, resource load, LLM health, and recent operational signals remain reachable from the initial vertical flow
+
+#### Scenario: Server list on narrow screen
+- **WHEN** a server owner or server administrator opens the server list on a narrow screen
+- **THEN** the application displays single-column server cards with search, status filtering, and server status fields available without horizontal scrolling
@@ -0,0 +1,78 @@
+## ADDED Requirements
+
+### Requirement: Server detail operations workspace
+The server detail page SHALL serve as the primary workspace for day-to-day management of a single server.
+
+#### Scenario: Server detail exposes core sections
+- **WHEN** an authorized server owner, server administrator, or platform administrator opens a server detail page
+- **THEN** the page provides access to overview, logs, configuration, plugin controls, LLM configuration assistance, and operation history for that server
+
+#### Scenario: Server detail header shows live status
+- **WHEN** server status data is available
+- **THEN** the server detail header shows online/offline state, player count, TPS, latency, CPU usage, memory usage, and disk usage
+
+### Requirement: Plugin controls are grouped inside server detail
+The server detail page SHALL display plugin control surfaces grouped by plugin for the selected server.
+
+#### Scenario: Server plugin controls are visible by plugin
+- **WHEN** a server has manageable plugins installed
+- **THEN** the plugin controls section displays each plugin as a separate group with that plugin's available controls for the selected server
+
+#### Scenario: Plugin marketplace is not the daily control surface
+- **WHEN** a user needs to run a plugin action for a specific server
+- **THEN** the user can perform the action from that server's detail page without first navigating to the plugin marketplace
+
+### Requirement: Per-server plugin isolation
+The system SHALL treat plugin controls, state, configuration, and operation history as scoped to a server instance.
+
+#### Scenario: Same plugin on multiple servers is isolated
+- **WHEN** two servers use the same plugin
+- **THEN** each server detail page shows independent plugin state, configuration, actions, and operation history for that server
+
+#### Scenario: Plugin action target is unambiguous
+- **WHEN** a user submits a plugin action from a server detail page
+- **THEN** the action target is the selected server and selected plugin group shown in the current page context
+
+### Requirement: Logs are filterable and inspectable
+The server detail logs section SHALL allow users to locate and inspect relevant logs for the selected server.
+
+#### Scenario: Logs support common filters
+- **WHEN** a user opens server logs
+- **THEN** the logs section provides filters for level, keyword, time range, and source where data is available
+
+#### Scenario: Log detail preserves context
+- **WHEN** a user opens a log entry detail
+- **THEN** the detail view shows the log content, timestamp, level, source, and relevant surrounding context or diagnostics when available
+
+### Requirement: Configuration edits are reviewable
+The server detail configuration section SHALL require review of changes before dispatching any server-side write job.
+
+#### Scenario: Manual configuration edit shows diff
+- **WHEN** a user edits server configuration and prepares to save
+- **THEN** the UI shows a reviewable diff before the write operation can be submitted
+
+#### Scenario: Configuration write targets selected server
+- **WHEN** a user confirms a configuration diff
+- **THEN** the resulting write operation targets only the selected server context
+
+### Requirement: LLM configuration assistance is scoped to server detail
+LLM configuration assistance SHALL operate within an explicit server context and produce recommendations or diffs for review.
+
+#### Scenario: LLM suggestion produces reviewable output
+- **WHEN** a user asks the LLM assistant to adjust server configuration
+- **THEN** the assistant returns a recommendation or diff for the selected server without silently dispatching a write job
+
+#### Scenario: LLM write requires confirmation
+- **WHEN** a user accepts an LLM-generated configuration diff
+- **THEN** the platform dispatches a write operation only after explicit user confirmation
+
+### Requirement: Mobile server detail remains operable
+The server detail workspace SHALL adapt to narrow screens using focused navigation patterns.
+
+#### Scenario: Server detail tabs remain usable on narrow screen
+- **WHEN** a user opens server detail on a narrow screen
+- **THEN** overview, logs, configuration, plugin controls, LLM assistance, and operation history remain reachable through compact tabs or equivalent navigation
+
+#### Scenario: Plugin groups collapse on narrow screen
+- **WHEN** a user opens plugin controls on a narrow screen
+- **THEN** plugin groups can be collapsed or expanded without losing the selected server context
@@ -0,0 +1,108 @@
+## ADDED Requirements
+
+### Requirement: Authentication entry flows
+The platform web application SHALL provide clear registration and login flows before users enter authenticated workspaces.
+
+#### Scenario: User registers an account
+- **WHEN** a visitor submits the registration form with valid identity fields
+- **THEN** the platform creates or requests creation of a user account without granting platform administrator privileges by default
+
+#### Scenario: User logs in
+- **WHEN** a user submits valid login credentials
+- **THEN** the application establishes the current session and routes the user to the role-appropriate default workspace
+
+#### Scenario: Authentication failure is visible
+- **WHEN** registration or login fails
+- **THEN** the form shows a scoped error with a retry path and does not leave the user on a blank page
+
+### Requirement: Platform administrator user management
+The platform web application SHALL allow platform administrators to create and manage users from the user management area.
+
+#### Scenario: Platform administrator creates a user
+- **WHEN** a platform administrator submits valid user details and role assignments
+- **THEN** the platform creates the user and shows a visible success result with the created user's status
+
+#### Scenario: Platform administrator manages users
+- **WHEN** a platform administrator opens user management
+- **THEN** the page shows users, status, roles, contact/profile summary, and available management actions
+
+#### Scenario: Server-only user cannot manage users
+- **WHEN** a server owner or server administrator without user management capability opens navigation
+- **THEN** user management is not shown and direct access redirects to that user's authorized default workspace
+
+### Requirement: Current user profile settings
+The platform web application SHALL expose current-user profile settings from the user's avatar or account menu.
+
+#### Scenario: User opens profile from avatar
+- **WHEN** an authenticated user selects their avatar or account menu
+- **THEN** the application provides access to profile settings without requiring user management permissions
+
+#### Scenario: User edits contact details
+- **WHEN** an authenticated user updates allowed personal fields
+- **THEN** the profile settings support display name, avatar, phone, QQ, and other bounded contact fields when available
+
+#### Scenario: Profile save has visible result
+- **WHEN** a profile update is submitted
+- **THEN** the UI shows pending, success, or failure feedback and preserves the user's entered values on recoverable failure
+
+### Requirement: Per-user theme preferences
+The platform web application SHALL let authenticated users configure their own interface theme and background preferences.
+
+#### Scenario: User chooses from multiple magical palettes
+- **WHEN** a user opens theme settings
+- **THEN** the application offers multiple named color palettes based on strawberry pink, lavender purple, mint green, milk yellow, icy blue, white highlights, and bright gold accents
+
+#### Scenario: Palette choice is applied immediately
+- **WHEN** a user selects a theme palette
+- **THEN** the workspace updates its surfaces, buttons, highlights, status accents, and decorative effects without requiring a page reload
+
+#### Scenario: User uploads a background
+- **WHEN** a user uploads a background image from profile or theme settings
+- **THEN** the application applies the background to the workspace with contrast surfaces that keep text, controls, logs, and forms readable
+
+#### Scenario: User chooses a built-in magical desktop
+- **WHEN** a user opens theme settings without uploading a custom background
+- **THEN** the application offers original built-in desktop presets with moon, sparkle, ribbon, magic-circle, crystal, candy, or aurora motifs that render behind translucent workspace surfaces
+
+#### Scenario: Uploaded background takes precedence
+- **WHEN** a user has both a built-in magical desktop preset and an uploaded background image
+- **THEN** the uploaded background is shown as the workspace desktop while preserving the selected preset for fallback after the upload is removed
+
+#### Scenario: Theme is scoped to current user
+- **WHEN** a user changes theme settings while authenticated
+- **THEN** the preference is associated with that user and does not change another user's workspace theme
+
+#### Scenario: Theme remains usable without profile API
+- **WHEN** backend profile preference APIs are unavailable
+- **THEN** the frontend may persist theme settings locally and labels the state clearly enough that users are not misled about cross-device persistence
+
+### Requirement: Cute game visual style remains operational
+The platform web application SHALL use an original cute anime/game visual style without sacrificing operator clarity.
+
+#### Scenario: Magical-girl materials are visible
+- **WHEN** the workspace renders default UI surfaces
+- **THEN** buttons, panels, dialogs, and account/theme controls use pastel gradients, crystal-moonlight transparent surfaces, glossy jelly controls, white and icy-blue rim highlights, diamond-like borders, candy-color glow, built-in magical desktop imagery, and lightweight shadows rather than dead black, flat white cards, or heavy dark saturated themes
+
+#### Scenario: Background remains visibly part of the interface
+- **WHEN** a default or user-uploaded background is present
+- **THEN** major dashboard cards, side navigation, profile controls, and dialogs remain translucent enough for the background to be visible while preserving readable text contrast
+
+#### Scenario: Magical motifs support the interface
+- **WHEN** decorative UI elements are shown
+- **THEN** they use original hearts, stars, moons, sparkles, ribbons, frosted crystal borders, or magic-circle inspired patterns without replacing operational labels or hiding status text
+
+#### Scenario: Magical ultimate effects are globally coordinated
+- **WHEN** the authenticated workspace renders ambient magical decoration
+- **THEN** magical ultimate effects are provided by a shared theme-aware global layer rather than page-local fixed decorative DOM elements
+
+#### Scenario: Common chrome uses cute icons
+- **WHEN** users view navigation, account settings, theme controls, refresh actions, and non-dangerous page commands
+- **THEN** the UI uses cute magical icons such as hearts, moons, stars, candy, dessert, or magic wands while preserving familiar warning icons for destructive or failed operations
+
+#### Scenario: Visual style uses original motifs
+- **WHEN** the platform ships default visual elements
+- **THEN** they use original colors, shapes, icons, and UI motifs rather than bundled recognizable third-party character art
+
+#### Scenario: Colorful panels remain readable
+- **WHEN** saturated blocks, gradients, or user backgrounds are visible
+- **THEN** operational text, metrics, form controls, errors, and operation results meet readable contrast and do not overlap