browser/platform_web

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 API-backed management console with the required first-party page routes. Server management now includes platform-mediated lifecycle, config, administrator, runtime distribution, dependency, log workflows, and plugin-declared server detail pages.

Server list surfaces expose runtime package actions through platform APIs, while server detail keeps day-to-day operations plugin-native and platform-mediated:

• generate run packages for selected OS/architecture targets.
• download the latest authorized run package.
• push a self-update job to an online run endpoint when the endpoint reports run.self-update.
• reset the current run key, which invalidates older run packages until regenerated.
• use plugin-declared remote access actions such as RCON through Platform bridge envelopes.
• request dependency checks and typed dependency install jobs.
• open live server log stream metadata and request historical log backfill jobs.

These screens show safe availability reasons, run online/offline status, job/build/dependency progress, artifact IDs, checksums, key generations, fingerprints, and redacted secret://runtime-keys/.../current refs. They must not render raw run or component keys, FTP passwords, database DSNs, RCON passwords, host paths, direct run sockets, backend storage URLs, or large inline log bodies. Log bodies are displayed verbatim when the plugin declares them; the browser does not redact or reinterpret them.

Manual UI smoke checklist:

1. Start npm run dev.
2. Open the local Vite URL.
3. Verify 首页、服务器管理、插件市场、用户管理、AI 提供商管理 render without visible overlap on desktop and mobile widths.
4. In 服务器管理, verify the server card action menu contains runtime actions as a compact anchored dropdown/popover. It must not become a tall vertical button tower, reflow the card, cover server metrics/progress bars/status badges, or turn the whole card into an accidental click target.
5. In a server detail route, verify plugin-declared pages render before built-in sections and that no manual 运行配置绑定, generic 运行操作 tab, or generic 插件控制 tab appears.
6. Switch black mecha and magical-girl themes when UI styling changed; runtime controls must keep the shared translucent console surfaces and avoid nested double frames.

Automated browser acceptance remains available for deeper local debug verification:

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/.

Runtime Workspace

Dedicated Run package, dependency, and plugin-declared operations live in server-list runtime actions or plugin pages, and the browser polls active jobs without fabricating later phases.

The UI keeps the black-mecha and magical-girl crystal-moonlight console materials and uses shared panel/command tokens. It renders no raw key, token, secret ref/value, host path, PID, socket, credential, DSN, RCON password, or Run endpoint address. 401/403 responses remain platform auth/capability errors, not local fallback success.