first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,91 @@
+## 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