108 lines
5.6 KiB
Markdown
108 lines
5.6 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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, and log workflows.
|
|
|
|
Server list and server detail surfaces expose runtime actions through platform APIs:
|
|
|
|
- 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.
|
|
- generate and download plugin-declared client-manager packages, including SCUM-style companion managers.
|
|
- reset the current client-manager key separately from the run key.
|
|
- 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/client-manager keys, FTP passwords, database DSNs, RCON passwords, host paths, direct run sockets, backend storage URLs, or large inline log bodies.
|
|
|
|
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.
|
|
4. In 服务器管理, verify the server card action menu contains runtime actions without turning the whole card into an accidental click target.
|
|
5. In a server detail route, verify the overview renders the 运行分发 section, action availability reasons, dependency/log controls, and safe redacted refs only.
|
|
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 uses the repository local debug stack:
|
|
|
|
```bash
|
|
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/`.
|