112 lines
6.6 KiB
Markdown
112 lines
6.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, 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/client-manager 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:
|
|
|
|
```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/`.
|
|
# Client Manager workspace
|
|
|
|
Client Manager lifecycle remains a typed Platform installation projection, but it is not exposed as a generic server-detail tab. Dedicated package/dependency actions live in server-list runtime actions or plugin-declared 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.
|