browser/platform_web/README.md

platform_web

Management console frontend for the game server management platform.

Required Pages

• 首页
• 服务器管理
• 插件市场
• 用户管理
• AI 提供商管理

Required Directory Plan

Implementation should use dedicated directories for:

• api/: platform API clients and API DTO types.
• routes/: route definitions and guards.
• pages/: page-level views.
• components/: reusable UI components.
• stores/: state stores.
• contracts/: frontend page, plugin page bridge, and bridge contracts.
• schemas/: frontend validation schemas.
• theme/: design tokens and styling primitives.
• utils/: shared frontend helpers.

Plugin page must be hosted by platform_web with safe platform context and without raw credentials.

Visual Direction

The management console uses a unified game-operations visual system with two first-party themes. The default theme is black mecha: dark cockpit panels, cyan scanner light, angular clipped frames, tactical grid lines, and amber energy accents. The optional theme is magical-girl: pink jelly glass, gold star frames, ribbon glow, and visible magic-circle motifs. It must not drift into a generic opaque SaaS dashboard.

Style guarantees for future changes:

• Use theme/tokens.ts for palettes, built-in background presets, storage keys, and theme application helpers.
• Use theme/base.css shared classes for shell, navigation, cards, panels, tables, drawers, dialogs, command buttons, status pills, logs, diffs, plugin groups, and operation history.
• Major surfaces stay translucent so the selected desktop/background remains visible while text remains readable.
• Built-in desktops are original CSS/generated motif backgrounds. User-uploaded backgrounds are supported and take visual precedence over the selected preset.
• Global ultimate motion is owned by components/MagicalParticleLayer.tsx; each theme should render one visible low-cost effect, such as a mecha scanner/core or magical-girl magic circle, rather than many tiny rotating particles. Do not add page-local fixed decorative spans or backdrop CSS.
• Keep operational clarity: status is text/icon plus color, logs and diffs stay high contrast, and operation feedback remains traceable.
• Read theme/README.md before changing style tokens or adding a new shared surface pattern.

Development Baseline

Tooling:

• Node 22.17.0.
• npm 11.6.1.
• Vite 7, React 19, TypeScript 5.

Commands:

npm install
npm run dev
npm run typecheck
npm run test
npm run acceptance:browser
npm run build
npm run preview

Runtime configuration:

• VITE_PLATFORM_API_BASE_URL: platform API base URL, default /api/v1.
• PLATFORM_API_PROXY: Vite dev-server proxy target for /api/v1 and /healthz, default http://127.0.0.1:8080.
• VITE_ENABLE_LOCAL_AUTH_FALLBACK: enables local development auth fallback when set to true.

For local direct debugging, copy platform_web/.env.example to platform_web/.env, edit the values, and run:

npm run dev

For Docker, the web console is built with VITE_PLATFORM_API_BASE_URL=/api/v1 and served by Nginx. Nginx proxies /api/v1 and /healthz to the platform compose service, so browser code never needs a direct backend container address.

Current UI behavior is a browser-verifiable console shell with the required first-party page routes. Data-backed workflows, plugin page hosting, and API integration belong to later OpenSpec changes.

Browser walkthrough baseline:

1. Start npm run dev.
2. Open the local Vite URL.
3. Verify 首页、服务器管理、插件市场、用户管理、AI 提供商管理 render without visible overlap on desktop and mobile widths.

Automated browser acceptance uses the repository local debug stack:

LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance ../scripts/browser-acceptance.sh

This command verifies the API-backed local debug console path, first-party route markers, plugin/server operation proof, fallback rejection, and forbidden-fragment scans. It writes evidence under <LOCAL_DEBUG_ROOT>/browser-acceptance/.