browser/openspec/changes/implement-platform-web-console-shell/specs/platform-web-console-shell/spec.md

ADDED Requirements

Requirement: Console shell supports first-party route navigation

The frontend SHALL provide a route-aware console shell for 首页、服务器管理、插件市场、用户管理、AI 提供商管理 with stable active-page state and refresh-safe URL hash handling.

Scenario: User opens a first-party route hash

• WHEN the browser opens the app with a hash for a known first-party page
• THEN the shell renders that page and marks the corresponding navigation item as current

Scenario: User selects navigation item

• WHEN the user selects a first-party navigation item
• THEN the shell updates the active page and URL hash without a full page reload

Scenario: User opens unknown route hash

• WHEN the browser opens the app with an unknown hash
• THEN the shell falls back to 首页 without rendering an invalid page

Requirement: First-party pages provide operational surfaces

The frontend SHALL render useful operational surfaces for every required first-party area using typed local view contracts and safe fallback data.

Scenario: Home page renders platform overview

• WHEN 首页 is active
• THEN the page shows platform health, server/plugin/user/provider summary sections, and next-action context without exposing secrets

Scenario: Server management page renders instance overview

• WHEN 服务器管理 is active
• THEN the page shows server instance status, run endpoint context, lifecycle action affordances, and pending job/log indicators without dispatching unimplemented workflows

Scenario: Plugin marketplace page renders installed plugin catalog

• WHEN 插件市场 is active
• THEN the page shows installed plugin metadata, permissions, bridge readiness, and validation status without commerce or cloud-host sales features

Scenario: User management page renders user and role overview

• WHEN 用户管理 is active
• THEN the page shows user status, role assignment context, and access-review indicators using frontend-owned contracts

Requirement: Frontend API client exposes shell resource contracts

The frontend SHALL define API types and client methods for shell pages using existing platform API endpoints and without casual cross-root imports.

Scenario: Client lists game plugins

• WHEN shell code requests game plugin data
• THEN the API client uses a named frontend contract for /api/v1/game-plugins

Scenario: Client lists server instances

• WHEN shell code requests server instance data
• THEN the API client uses a named frontend contract for /api/v1/server-instances

Scenario: Client authorizes plugin bridge action

• WHEN shell code requests bridge authorization
• THEN the API client uses a named frontend contract for /api/v1/plugin-bridge/authorize and does not include raw credentials

Requirement: Console shell is testable and visually accepted

The frontend SHALL include route/page tests, pass TypeScript/build validation, and complete a browser walkthrough before the change is complete.

Scenario: Automated tests cover required pages

• WHEN frontend tests run
• THEN they verify required navigation entries and representative content for each first-party page

Scenario: Browser walkthrough validates shell usability

• WHEN the browser walkthrough runs against the built or dev frontend
• THEN desktop and mobile views show coherent navigation, readable content, and no obvious overlap or blank page

Requirement: Console shell preserves security boundaries

The frontend SHALL not expose raw AI keys, run credentials, host paths, direct sockets, or storage backend credentials in shell pages, API contracts, or fallback data.

Scenario: Page content renders provider credentials

• WHEN AI provider or plugin data includes credential references
• THEN the frontend shows only safe references such as secret://, vault://, or env:// and never raw key material

Scenario: Plugin bridge context is rendered

• WHEN plugin bridge readiness appears in shell pages
• THEN the frontend shows permissions and action readiness without exposing raw run or platform auth internals