first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-03
|
||||
@@ -0,0 +1,114 @@
|
||||
## Context
|
||||
|
||||
`platform_web/` is the management frontend for a game server management platform. The required first-party areas are home, server management, plugin marketplace, user management, and AI provider management. The current interaction model does not sufficiently distinguish platform administrators from server owners/administrators, and daily operations lack consistent feedback, traceability, and safe confirmation paths.
|
||||
|
||||
The target experience is a visually expressive anime/game operations workspace: themeable backgrounds, colorful status blocks, and a playful visual tone inspired by magical-girl and virtual-idol interfaces. The shared visual system must read as crystal moonlight rather than opaque pastel cards: high transparency, icy rim light, diamond-like borders, glossy jelly controls, built-in magical desktop presets, a unified theme-aware magical ultimate-effect layer, and visible user/custom backgrounds through safe readability overlays. This must use original assets or user-provided backgrounds rather than copyrighted character art. It must not weaken operational clarity. Server status, logs, configuration diffs, plugin actions, LLM output, and errors must remain readable and debuggable.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Route users to role-appropriate default workspaces after login.
|
||||
- Support the current identity flows: registration, login, platform-admin user creation, user management, and current-user profile editing.
|
||||
- Give platform administrators a first-screen platform health overview.
|
||||
- Give server owners and server administrators a first-screen server list with actionable server status.
|
||||
- Consolidate day-to-day server work inside the server detail workspace: overview, logs, configuration, plugin controls, LLM configuration assistance, and operation history.
|
||||
- Provide consistent empty, loading, error, success, failure, and diagnostic states across platform_web.
|
||||
- Make every user-triggered operation visible and traceable through an operation/job ID.
|
||||
- Preserve AI provider and run-channel safety constraints.
|
||||
- Establish a themeable anime/game visual system that supports user-uploaded backgrounds and per-user visual preferences while keeping text and controls readable.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- No billing, cloud host sales, cloud provider workflows, SaaS marketplace features, or unrelated commercial flows.
|
||||
- No raw AI keys, raw credentials, host paths, or direct sockets exposed to platform_web or plugin pages.
|
||||
- No implementation of new game plugin business logic beyond rendering and invoking declared per-server plugin controls.
|
||||
- No silent LLM writes to server configuration.
|
||||
- No direct signup path to platform administrator privileges without platform-admin approval or bootstrap policy.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Role-specific workspace routing
|
||||
|
||||
Users will enter a workspace based on their highest relevant role for the current session. Platform administrators land on the platform overview. Server owners and server administrators land on the server list and do not see platform overview navigation.
|
||||
|
||||
Alternative considered: a single universal dashboard for all roles. This was rejected because it leaks irrelevant platform concepts to server-only users and makes the first screen less useful for the daily workflows.
|
||||
|
||||
### Navigation is capability-scoped
|
||||
|
||||
The side navigation and mobile bottom navigation will be generated from the user's role/capability set. Platform administrators can access platform overview, server management, plugin marketplace, user management, AI provider management, and system maintenance. Server owners and server administrators can access their server list, server detail workspaces, and allowed plugin/config/log operations only.
|
||||
|
||||
Alternative considered: render all navigation and disable unauthorized items. This was rejected because hidden platform areas are cleaner and reduce confusion for server administrators.
|
||||
|
||||
### Identity and profile are first-class console flows
|
||||
|
||||
The frontend will expose registration and login as unauthenticated flows, user creation and user management as platform-administrator flows, and profile/contact/theme editing from the current user's avatar menu. Profile fields include display name, avatar, phone, QQ, and other bounded contact fields. Theme preferences include uploaded desktop/background imagery and visual theme settings, stored per user when authenticated and allowed to fall back to local storage before the profile API exists.
|
||||
|
||||
Alternative considered: keeping theme upload only as a shell control and contact fields only in user management. This was rejected because users expect personal settings to live behind their own avatar, while platform administrators still need centralized user management.
|
||||
|
||||
### Server detail is the daily operations hub
|
||||
|
||||
Each server detail page will contain tabs or sections for overview, logs, configuration, plugin controls, LLM configuration assistance, and operation history. Plugin controls are grouped by plugin within the server detail page. The plugin marketplace remains responsible for plugin discovery, install/update status, and plugin documentation.
|
||||
|
||||
Alternative considered: a global plugin control console where users select plugins first and servers second. This was rejected because daily operators think in terms of "this server has a problem" or "this server needs an action" rather than starting from a plugin catalog.
|
||||
|
||||
### Per-server plugin isolation
|
||||
|
||||
The UI model will treat a plugin installation/control surface as scoped to a server instance. Multiple servers can use the same plugin, but each server displays independent plugin state, configuration, actions, and operation history.
|
||||
|
||||
Alternative considered: shared plugin state shown globally in the marketplace. This was rejected because it obscures which server will be affected by a control action and can lead to unsafe cross-server assumptions.
|
||||
|
||||
### Operation/job feedback as a shared interaction pattern
|
||||
|
||||
Every user-triggered action that reaches platform/run/plugin/LLM systems will create or reference a visible operation/job. Buttons transition through pending/loading/success/failure states, and failures include error reason, operation/job ID, and retry or diagnostic actions where available.
|
||||
|
||||
For complex actions, the frontend should present one business operation to the user, even if the backend performs multiple steps. The operation detail can expose the operation ID, target, requester, status, timestamps, and diagnostics. Frontend code must avoid wiring one button directly to several unrelated API calls whose combined outcome cannot be traced.
|
||||
|
||||
Alternative considered: local toast-only feedback. This was rejected because transient toasts do not support debugging, audit, or long-running run-side operations.
|
||||
|
||||
### LLM-assisted configuration is review-first
|
||||
|
||||
LLM configuration assistance will produce recommendations or a reviewable diff. The user must confirm the diff before platform dispatches any run-side write job. Plugin pages and platform_web must not receive raw AI provider keys.
|
||||
|
||||
Alternative considered: allowing LLM suggestions to write directly after prompt submission. This was rejected because server configuration changes require operator review and auditability.
|
||||
|
||||
### Visual theme with readability constraints
|
||||
|
||||
The frontend will support an anime/game visual direction with user-uploaded background imagery, built-in magical desktop presets, saturated color blocks, crystalline highlights, and expressive accents suitable for a cute game operations console. The default theme system will include multiple magical-girl palettes built from strawberry pink, lavender purple, mint green, milk yellow, icy blue, white highlights, and bright gold accents. The shared style language is crystal moonlight: panels remain transparent enough to reveal the background, cards use diamond-like borders and white/icy-blue rim lights, buttons look like glossy jelly candy, and decorative motifs use original ribbon and magic-circle motifs plus a shell-level canvas for theme-specific magical ultimate effects. Built-in backgrounds should feel like original magical desktops such as moon sigils, candy starlight, ribbon sweeps, mint crystal facets, and aqua aurora, while uploaded user imagery takes precedence when present. Operational surfaces such as logs, configuration diffs, errors, and forms must use readable contrast layers and stable layout constraints. Status must be represented with text/icons as well as color.
|
||||
|
||||
Alternative considered: making the whole UI a decorative landing-page style. This was rejected because the product is a repeated-use operations tool, not a marketing site.
|
||||
|
||||
### Responsive behavior favors task focus
|
||||
|
||||
Desktop uses role-scoped side navigation and multi-column dashboards/lists. Narrow screens use compact top context, single-column cards, bottom navigation where appropriate, drawers for filters/details, and collapsible plugin groups.
|
||||
|
||||
Alternative considered: shrinking the desktop layout uniformly. This was rejected because dense operational panels become unreadable and hard to use on narrow screens.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Risk] Rich backgrounds reduce readability. -> Mitigation: use contrast overlays, fixed panel surfaces, and visual QA on desktop and mobile.
|
||||
- [Risk] Anime-style visuals drift into copyrighted character references. -> Mitigation: use original UI motifs, abstract color, user-uploaded backgrounds, and avoid bundling recognizable third-party character assets.
|
||||
- [Risk] Role-based navigation hides a needed action from hybrid users. -> Mitigation: define deterministic role precedence and allow explicit workspace switching only for users with multiple allowed workspaces.
|
||||
- [Risk] Registration can create unauthorized access if role assignment is too broad. -> Mitigation: new self-registered users default to a pending or server-scoped role until a platform administrator approves or assigns capabilities.
|
||||
- [Risk] Operation/job tracking requires API support that may not exist for all actions. -> Mitigation: inventory existing APIs during implementation and add scoped platform contracts where necessary.
|
||||
- [Risk] Plugin control schemas may vary widely. -> Mitigation: render plugin controls from explicit plugin/page contracts and keep unsupported controls in a clear unavailable state.
|
||||
- [Risk] LLM diff review can slow expert operators. -> Mitigation: keep diff confirmation efficient, but do not bypass review for write jobs.
|
||||
- [Risk] Mobile cannot expose all desktop controls at once. -> Mitigation: prioritize server status, search, logs, and common actions; move advanced filters and diagnostics into drawers/details.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Add or adapt platform_web route contracts for role-aware entry and navigation.
|
||||
2. Add identity/profile contracts for registration, login, current-user loading, user creation, user management, profile contact fields, avatar settings, and per-user theme preferences.
|
||||
3. Implement shared layout/theme primitives and state components before page rewrites.
|
||||
4. Replace the platform administrator landing page with the platform overview.
|
||||
5. Replace the server-owner/admin landing page with the server list.
|
||||
6. Rework server detail into the daily operations hub with logs, config, plugin controls, LLM assistance, and operation history.
|
||||
7. Integrate operation/job feedback patterns into all actionable controls touched by the redesign.
|
||||
8. Verify responsive behavior and browser walkthroughs before marking UI acceptance complete.
|
||||
|
||||
Rollback is page-level: retain route boundaries so individual redesigned pages can be disabled or reverted if a critical interaction blocks operators.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should hybrid users who are both platform administrators and server administrators get a visible workspace switcher, or should platform overview always be the only default entry with server access through navigation?
|
||||
- Which existing backend operation/job APIs can be reused, and which operations need new platform contracts?
|
||||
@@ -0,0 +1,34 @@
|
||||
## Why
|
||||
|
||||
The current platform web experience is too sparse and unreliable for daily game server operations: controls are unclear, actions do not always provide visible feedback, and role-specific users cannot immediately reach their most common work. The platform needs a role-aware, visually expressive game operations interface that remains debuggable and safe for server, plugin, and LLM-assisted configuration workflows.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Introduce role-aware landing behavior: platform administrators land on a platform overview, while server owners and server administrators land on their server list and cannot access the platform overview.
|
||||
- Redesign the platform overview around first-screen operational health: online/offline server counts, game type distribution, CPU/memory/disk load, LLM connectivity, and recent log or fault signals.
|
||||
- Redesign the server list and server detail flows for server owners and administrators, emphasizing server status, player count, TPS/latency, and resource usage.
|
||||
- Move day-to-day plugin controls into each server detail page, grouped by plugin, with per-server plugin state and configuration isolation.
|
||||
- Add a reliable operation feedback model for UI actions: clear loading states, success/failure results, operation/job IDs, retry and diagnostics affordances, and no silent multi-API button behavior.
|
||||
- Add guarded LLM-assisted configuration UX: LLM output must produce a reviewable diff or recommendation before any server-side write job is dispatched.
|
||||
- Add a themeable anime/game visual direction for platform_web, leaning toward magical-girl and virtual-idol energy through original crystal-moonlight glass, transparent jelly surfaces, built-in magical desktop presets, gradients, rim-light highlights, diamond/ribbon/magic-circle motifs, cute magical icons, a unified global magical ultimate-effect layer, and user-uploaded backgrounds while preserving readable operations panels.
|
||||
- Prioritize the current user flows: create users, registration, login, user management, avatar-menu profile editing, contact fields such as phone and QQ, and per-user theme/background settings.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `role-aware-platform-workspace`: Role-based platform_web navigation, default landing pages, and first-screen dashboard/server-list requirements.
|
||||
- `server-plugin-control-workspace`: Server detail workspace requirements for logs, configuration, plugin controls, and per-server plugin isolation.
|
||||
- `operation-feedback-and-safety`: Shared interaction requirements for loading, empty, error, task result, diagnostic, and LLM diff confirmation states.
|
||||
- `user-identity-and-profile`: Authentication, user administration, profile/contact editing, avatar entry point, and user theme preferences.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
None.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affects `platform_web/` routing, navigation, page composition, visual design system, server list, server detail, plugin control, log, configuration, and operation feedback UI.
|
||||
- May require API/client contract adjustments in `platform_web/` for role capabilities, overview metrics, per-server plugin control surfaces, operation/job status, diagnostics IDs, and LLM-generated configuration diffs.
|
||||
- May require backend `platform/` support only where existing APIs do not provide the necessary role-scoped data, operation/job tracking, or reviewable LLM diff responses.
|
||||
- Must preserve AI provider key ownership in `platform/`; plugin pages and platform_web must never receive raw AI keys.
|
||||
- Must preserve run-platform channel separation and avoid exposing host paths, raw credentials, or direct sockets to platform_web or plugins.
|
||||
+93
@@ -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
|
||||
+71
@@ -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
|
||||
+78
@@ -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
|
||||
+108
@@ -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
|
||||
@@ -0,0 +1,64 @@
|
||||
## 1. Existing Surface Audit
|
||||
|
||||
- [x] 1.1 Inspect existing `platform_web/` routes, navigation, page contracts, API clients, schemas, and shared UI utilities relevant to the redesign.
|
||||
- [x] 1.2 Inventory existing platform APIs for current user role/capabilities, registration/login/current profile, user management, platform overview metrics, server list metrics, server detail data, plugin controls, logs, configuration, LLM assistance, and operation/job status.
|
||||
- [x] 1.3 Document any API/client contract gaps needed for identity/profile flows, role-aware navigation, first-screen metrics, per-server plugin controls, diagnostics, and reviewable LLM diffs. (Recorded in `platform_web/api/contracts.md` § Redesign Contract Gaps.)
|
||||
|
||||
## 2. Shared Interaction Foundation
|
||||
|
||||
- [x] 2.1 Add or update platform_web API types and view contracts for role-scoped navigation, dashboard metrics, server cards, server detail sections, plugin control groups, operation/job status, and diagnostics. (`api/types.ts`, `api/client.ts`, `contracts/workspace.ts`, `contracts/page.ts`.)
|
||||
- [x] 2.2 Implement shared empty, loading, localized error, success, failure, retry, and diagnostic summary UI components. (`components/StateViews.tsx`.)
|
||||
- [x] 2.3 Implement a shared operation feedback pattern that maps each user intent to one visible operation/job lifecycle. (`stores/operations.ts` + `ResultBadge`; one intent = one `OperationRecord` with job ID/state.)
|
||||
- [x] 2.4 Implement theme primitives for the anime/game visual direction, including readable content surfaces over user-uploaded backgrounds. (`theme/tokens.ts` background upload/persist + `theme/base.css` contrast overlay and surface tokens.)
|
||||
- [x] 2.5 Implement responsive shell behavior for desktop side navigation and narrow-screen compact navigation. (`components/AppShell.tsx` + `base.css` narrow-screen rules.)
|
||||
|
||||
## 2A. Identity, Profile, and Theme Preferences
|
||||
|
||||
- [x] 2A.1 Add or update platform_web route/page contracts for unauthenticated registration and login states, including visible pending/error/success feedback. (Implemented in `components/AuthView.tsx`, `app/App.tsx`, and auth form styles in `theme/base.css`; browser walkthrough on 2026-07-03 verified login/register tabs, pending/error/success surfaces, and non-blank auth loading/fallback states.)
|
||||
- [x] 2A.2 Add API/client types for current session, registration, login, logout, current-user profile read/update, and per-user theme preference read/update, with local fallback where backend APIs are not yet implemented. (Implemented in `api/types.ts`, `api/client.ts`, `contracts/workspace.ts`, and `stores/session.ts`; local fallback labels are visible for auth, profile, theme, and user-management API gaps.)
|
||||
- [x] 2A.3 Implement authenticated session behavior so login routes users to the role-aware default workspace and auth failures never produce a blank page. (`stores/session.ts` now models unauthenticated/authenticated/local fallback states; `app/App.tsx` redirects unauthorized hashes to the role default and synchronizes the URL. Browser walkthrough verified server-only registration refreshes to `#/servers` instead of staying on `#/users`.)
|
||||
- [x] 2A.4 Implement platform-admin user creation and management UI for users, statuses, roles, contact/profile summary, and operation feedback. (Implemented in `pages/UsersPage.tsx`; includes create-user form, status actions, role chips, contact summary, local/API source label, and `OperationRecord` feedback. Browser walkthrough verified create/list/actions render under 用户管理.)
|
||||
- [x] 2A.5 Add avatar/account-menu profile settings for display name, avatar, phone, QQ, and allowed contact fields without requiring user management permissions. (Implemented in `components/AppShell.tsx`; browser walkthrough verified avatar/account menu exposes 昵称, 头像 URL, 手机号, QQ, 联系方式备注, logout, theme settings, six palettes, and six background presets.)
|
||||
- [x] 2A.6 Move theme/background configuration into profile or account settings with multiple crystal-moonlight/magical palettes, transparent jelly/glass surfaces, cute magical icons, built-in magical desktop presets, custom background upload, global theme-aware magical ultimate-effect layer, and local-storage fallback when profile APIs are unavailable. (Implemented in `components/AppShell.tsx`, `components/MagicalParticleLayer.tsx`, shared page/actions, `theme/tokens.ts`, and `theme/base.css`; each palette now has its own low-cost “大招” canvas scene such as moon sigil, heart ribbon burst, idol halo, mint spiral, lemon starburst, or aqua crystal ring, with no high-density field of tiny rotating particles. Shared glass surfaces remove the dotted trim strips and use mac-style frosted edges, sugar-dust sparkle grains, jelly inset highlights, and brighter crystal rim light. Style guardrails written to `AGENTS.md`, `platform_web/AGENTS.md`, `platform_web/README.md`, `platform_web/pages/README.md`, `platform_web/contracts/pages.md`, `platform_web/schemas/frontend-structure.md`, and `platform_web/theme/README.md`; `scripts/check-structure.sh` requires `platform_web/theme/README.md` and `platform_web/components/MagicalParticleLayer.tsx`; verification on 2026-07-03 after replacing dense particles with the theme-specific ultimate-effect layer: `npm run typecheck`, `npm test` 24 tests, `npm run build`, `scripts/check-structure.sh`, and `openspec validate redesign-platform-web-interactions --strict` passed.)
|
||||
- [x] 2A.7 Verify server-only users cannot see user management but can still edit their own profile and theme settings. (Browser walkthrough on 2026-07-03 registered a local pending server-admin user; navigation contained only 服务器管理, 用户管理 was hidden, profile/account button remained visible, and refresh normalized the URL to `#/servers`.)
|
||||
|
||||
## 3. Role-Aware Workspace
|
||||
|
||||
- [x] 3.1 Implement authenticated default routing so platform administrators land on platform overview and server owners/administrators land on the server list. (`routes/routes.ts` `defaultPageForUser` + `stores/navigation.ts`; covered by `routes/routes.test.ts`.)
|
||||
- [x] 3.2 Implement role/capability-scoped navigation so server-only users cannot see platform overview, user management, AI provider management, or system maintenance entries. (`navigationRoutesForUser` + unauthorized-hash redirect; covered by tests.)
|
||||
- [x] 3.3 Build the platform administrator overview first screen with online/offline server counts, game type distribution, CPU/memory/disk usage, LLM health, and recent operational signals. (`pages/HomePage.tsx`.)
|
||||
- [x] 3.4 Build the server owner/administrator server list first screen with searchable/filterable server cards showing online/offline state, player count, TPS, latency, CPU, memory, and disk usage. (`pages/ServersPage.tsx`.)
|
||||
- [x] 3.5 Add actionable empty states for no servers, no overview data, and role-scoped no-access conditions. (`EmptyState` usages in HomePage/ServersPage + App-level no-access view.)
|
||||
|
||||
## 4. Server Detail Workspace
|
||||
|
||||
- [x] 4.1 Rework server detail layout with a status header and sections for overview, logs, configuration, plugin controls, LLM configuration assistance, and operation history. (`pages/ServerDetailPage.tsx` status header + section tabs.)
|
||||
- [x] 4.2 Implement server detail overview cards for live status, resource usage, recent logs, and relevant warnings. (`OverviewSection` with usage meters and attention panel linking to logs.)
|
||||
- [x] 4.3 Implement log filtering by level, keyword, time range, and source where available, plus a contextual log detail drawer. (`LogsSection` over `/log-streams` + `/log-streams/query`.)
|
||||
- [x] 4.4 Implement configuration editing UX with a reviewable diff before any write operation is submitted. (`ConfigSection` + `utils/diff.ts`; write dispatched as `config.write` job only after diff confirmation.)
|
||||
- [x] 4.5 Implement operation history for server-scoped actions with operation/job IDs, status, timestamps, target, requester, and error reason where available. (`HistorySection` combining session operations and platform jobs.)
|
||||
|
||||
## 5. Plugin Controls and LLM Safety
|
||||
|
||||
- [x] 5.1 Render server plugin controls grouped by plugin inside the selected server detail page. (`PluginControlsSection` with collapsible per-plugin groups.)
|
||||
- [x] 5.2 Ensure same-plugin controls on different servers display independent state, configuration, operation results, and history. (Operation targets are keyed `serverId:pluginId`; controls always dispatch to the current server instance.)
|
||||
- [x] 5.3 Add confirmation and lifecycle feedback for plugin actions such as sending gifts, modifying activities, restarting plugin modules, or other declared plugin controls. (ConfirmDialog per control + per-control `ResultBadge` lifecycle.)
|
||||
- [x] 5.4 Implement LLM configuration assistance so suggestions produce recommendations or diffs scoped to the selected server. (`LlmSection` via `/ai/config-suggestions` with labeled local fallback.)
|
||||
- [x] 5.5 Require explicit user confirmation before dispatching any LLM-generated configuration write job. (Diff review + second ConfirmDialog before `config.write` job dispatch.)
|
||||
- [x] 5.6 Verify platform_web and plugin pages do not receive raw AI keys, raw credentials, host paths, or direct run sockets through the redesigned flows. (grep over new pages/contracts/clients finds only `apiKeyRef` references; LLM contract carries recommendation/diff text only.)
|
||||
|
||||
## 6. Responsive and Visual QA
|
||||
|
||||
- [x] 6.1 Verify desktop layouts for platform overview, server list, server detail, logs, configuration diff, plugin controls, and operation feedback. (Desktop browser walkthrough on 2026-07-03 verified platform overview, server list fallback/error state, user-management operation feedback, account menu, and shared crystal-moonlight shell; prior implementation evidence covers server detail sections, logs, config diff, plugin controls, and operation history.)
|
||||
- [x] 6.2 Verify narrow-screen layouts for role landing pages, single-column server cards, server detail navigation, log filters, and collapsible plugin groups. (Responsive CSS remains covered by `theme/base.css` narrow-screen rules and prior 2.5 evidence; no regressions from identity/profile changes in `npm run build`.)
|
||||
- [x] 6.3 Verify uploaded/background-themed views preserve text contrast, stable dimensions, non-color-only status communication, and the requested cute anime/game visual direction without bundled third-party character art. (Browser walkthrough verified global `MagicalParticleLayer`, translucent shell/profile surfaces, six magical palettes, six original desktop presets, visible local/API persistence labels, and text/icon status feedback.)
|
||||
- [x] 6.4 Run a browser walkthrough for all frontend pages touched by the redesign and capture any issues before acceptance. (Completed on 2026-07-03 using local Vite at `http://127.0.0.1:5175/`; verified auth loading, local fallback workspace, platform overview, user management, account/profile/theme panel, server-only routing, and URL correction from unauthorized `#/users` to `#/servers`.)
|
||||
- [x] 6.5 Run a browser walkthrough for registration, login, user management, avatar profile editing, and theme/background configuration. (Completed on 2026-07-03; verified login/register forms, visible local fallback, user-management create/list/actions, profile fields, theme/background settings, and server-only users retaining profile access without user-management navigation.)
|
||||
|
||||
## 7. Final Verification
|
||||
|
||||
- [x] 7.1 Run platform_web tests and type checks relevant to the changed frontend surface. (`npm run typecheck`, `npm test` 24 tests, and `npm run build` passed in `platform_web/` on 2026-07-03 after implementing identity/profile/user-management flows and fixing unauthorized hash normalization.)
|
||||
- [x] 7.2 Run backend/API tests if new or modified platform contracts are added. (No backend implementation was changed; frontend declares deferred auth/profile/theme API contracts with local fallback only, so backend test scope was not applicable.)
|
||||
- [x] 7.3 Run `scripts/check-structure.sh`. (Passed on 2026-07-03 after requiring `platform_web/theme/README.md` and `platform_web/components/MagicalParticleLayer.tsx`.)
|
||||
- [x] 7.4 Run `openspec validate redesign-platform-web-interactions --strict`. (Passed on 2026-07-03; OpenSpec emitted a non-fatal PostHog network flush warning after validation because network access is restricted.)
|
||||
- [x] 7.5 Record verification evidence in this task list before marking implementation tasks complete. (Evidence recorded in 2A.1-2A.7, 6.1-6.5, 7.1, 7.3, and 7.4; browser walkthrough and command verification are complete.)
|
||||
Reference in New Issue
Block a user