first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-03
@@ -0,0 +1,71 @@
+## Context
+
+`platform_web/` already contains the required first-party navigation entries and a working AI provider management page. The other first-party areas still use thin metric-only placeholders, and the shell owns only hash replacement without a reusable page model, status surface, or acceptance-focused layout.
+
+This change keeps implementation inside `platform_web/` and prepares the frontend for later server-management workflows. It uses existing Vite, React, TypeScript, local contracts, and fallback data patterns; it does not add backend behavior or cross-root imports.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make the console shell route-aware, accessible, and stable across refresh/hash navigation.
+- Give every required first-party area a useful operational page surface rather than a bare metric placeholder.
+- Keep API contracts and page contracts in dedicated frontend directories.
+- Add frontend client methods for currently available platform resources used by shell pages.
+- Add tests covering route/page behavior and page-level rendering.
+- Validate the UI with build/test commands and browser walkthrough evidence.
+
+**Non-Goals:**
+
+- Do not implement full server create/start/stop workflows; that is the next queued change.
+- Do not add billing, cloud host sales, provider marketplace, or unrelated SaaS behavior.
+- Do not expose raw AI keys, run credentials, host paths, storage backend credentials, or direct run sockets.
+- Do not introduce a router dependency unless existing hash navigation becomes insufficient.
+- Do not change backend platform APIs in this change.
+
+## Decisions
+
+### Decision 1: Keep hash routing for the shell baseline
+
+The app will continue to use hash-based navigation, but route resolution will be centralized in `routes/` and `stores/`. This keeps the console deployable as a static frontend while preserving direct links and refresh behavior.
+
+Alternative considered: add React Router now. Rejected because the current routing needs are simple and adding a dependency before workflow pages exist would increase surface area without improving the backlog item.
+
+### Decision 2: Use local page view contracts for first-party pages
+
+Each page will consume typed view contracts from `contracts/` and local-safe seed data until backend workflow APIs exist. Page components remain focused on rendering and local interactions, not hidden shared business types.
+
+Alternative considered: place page-specific types inside page components. Rejected because repository rules require frontend page roots to keep view contracts in fixed directories.
+
+### Decision 3: Extend the frontend API client only for existing backend endpoints
+
+The frontend client will add typed methods for health, game plugins, server instances, and bridge authorization where backend endpoints already exist. Pages may fall back to local data if APIs are unavailable.
+
+Alternative considered: create mock-only page data without API client expansion. Rejected because later workflow pages need a stable client surface and tests should exercise named contracts.
+
+### Decision 4: Design the shell for dense operational scanning
+
+The shell will prioritize compact navigation, status chips, tables/lists, and action strips over marketing-style presentation. The visual system should remain consistent with existing AI provider management styling.
+
+Alternative considered: add a landing-page style dashboard. Rejected because this is an operational game server management console, not a product marketing site.
+
+## Risks / Trade-offs
+
+- [Risk] Pages can imply workflows that are not implemented yet. Mitigation: label actions as planning/local status and avoid dispatching run jobs.
+- [Risk] Local fallback data can drift from backend contracts. Mitigation: keep frontend API types explicit and covered by tests.
+- [Risk] Hash routing can become limiting later. Mitigation: centralize route parsing so a future router can replace the implementation without changing page contracts.
+- [Risk] A richer shell may introduce responsive layout regressions. Mitigation: run build/tests and a browser walkthrough at desktop and mobile widths.
+
+## Migration Plan
+
+1. Add console shell view contracts, route helpers, API types/client methods, and tests.
+2. Expand first-party pages with operational sections and local-safe fallback data.
+3. Update shell styling for desktop and mobile responsive navigation/content.
+4. Run frontend tests/build/typecheck, structure validation, strict OpenSpec validation, and browser walkthrough.
+
+Rollback is contained to `platform_web/` and this OpenSpec change: remove the new page contracts/client methods/page rendering changes and return to the previous placeholder shell.
+
+## Open Questions
+
+- Whether a later workflow change should replace hash routing with a full router after server management forms and nested pages are introduced.
+- Whether dashboard summaries should eventually come from a dedicated backend summary endpoint or compose existing list endpoints.
@@ -0,0 +1,27 @@
+## Why
+
+The management frontend has the required first-party navigation and a deeper AI provider page, but the console shell still behaves like a static page switcher with placeholder pages. This change turns `platform_web/` into a durable management console foundation for the next server-management workflows.
+
+## What Changes
+
+- Add a route-aware console shell with stable navigation state, page metadata, and accessible active-page behavior.
+- Add richer first-party page surfaces for 首页、服务器管理、插件市场、用户管理、AI 提供商管理 using local-safe data until backend workflow APIs are introduced.
+- Add frontend API types/client methods needed by shell pages for game plugins, server instances, and health/status summaries without exposing raw credentials or run internals.
+- Add page/view contracts, schemas, and utilities that keep page components free of hidden shared business types.
+- Add route/page tests, frontend build coverage, and a browser walkthrough for the console shell.
+
+## Capabilities
+
+### New Capabilities
+
+- `platform-web-console-shell`: Defines the first-party frontend console shell, navigation behavior, page contracts, API client surface, and visual acceptance expectations for the management console.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- `platform_web/`: app shell, route definitions, page registry, page contracts, API types/client methods, schemas/utilities, first-party pages, tests, and styling.
+- OpenSpec artifacts and validation for the new `platform-web-console-shell` capability.
+- No backend behavior changes are required in this change; pages may use existing API endpoints with local fallback data.
@@ -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
@@ -0,0 +1,40 @@
+## 1. Shell Routing and Contracts
+
+- [x] 1.1 Add route helper contracts for resolving known hashes, fallback routes, and page metadata.
+- [x] 1.2 Add shell view contracts for dashboard summaries, server instances, plugins, users, and provider status.
+- [x] 1.3 Extend frontend API types and client methods for game plugins, server instances, health, and plugin bridge authorization.
+
+## 2. First-Party Page Implementation
+
+- [x] 2.1 Expand 首页 into an operational overview with health, server, plugin, user, and AI provider summary sections.
+- [x] 2.2 Expand 服务器管理 into an instance/run/job/log overview without dispatching unimplemented lifecycle workflows.
+- [x] 2.3 Expand 插件市场 into an installed plugin catalog with permissions, bridge readiness, and validation state.
+- [x] 2.4 Expand 用户管理 into a user/role/access-review overview using frontend-owned contracts.
+- [x] 2.5 Keep AI 提供商管理 compatible with the updated shell and shared page contracts.
+
+## 3. Styling and Responsive Shell
+
+- [x] 3.1 Update shell/page styling for dense operational layouts, responsive navigation, and accessible active states.
+- [x] 3.2 Ensure page content avoids raw secret, host path, direct socket, and run credential display.
+
+## 4. Tests and Browser Walkthrough
+
+- [x] 4.1 Add route helper and API client tests for shell resource contracts.
+- [x] 4.2 Add page rendering tests for each required first-party page.
+- [x] 4.3 Run `cd platform_web && npm test`.
+- [x] 4.4 Run `cd platform_web && npm run build`.
+- [x] 4.5 Run browser walkthrough for desktop and mobile shell views.
+
+## 5. Verification
+
+- [x] 5.1 Run `scripts/check-structure.sh`.
+- [x] 5.2 Run `openspec validate implement-platform-web-console-shell --strict`.
+- [x] 5.3 Record verification evidence in this task file before marking verification tasks complete.
+
+## Evidence
+
+- `cd platform_web && npm test`: passed on 2026-07-03; Vitest reported 6 files and 14 tests passing.
+- `cd platform_web && npm run build`: passed on 2026-07-03; TypeScript no-emit and Vite production build completed.
+- Browser walkthrough: passed on 2026-07-03 using local Chrome CDP against `http://127.0.0.1:5174/`; checked 首页、服务器管理、插件市场、用户管理、AI 提供商管理 at desktop 1440x1000 and mobile 390x844 with no missing target content or page-level horizontal overflow. Screenshots were written under `/tmp/platform-web-console-shell-walkthrough/`.
+- `scripts/check-structure.sh`: passed on 2026-07-03 with `structure check passed`.
+- `openspec validate implement-platform-web-console-shell --strict`: passed on 2026-07-03 with `Change 'implement-platform-web-console-shell' is valid`.