first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,91 @@
+# 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 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:
+
+```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/`.