# Game Server Management Platform

This repository is the game server management platform workspace. It replaces the old SCUM-specific coupling with three browser-owned project roots:

- `platform/`: backend control plane for users, game management plugins, server instances, AI providers, jobs, artifacts, logs, and audit.
- `platform_web/`: management console frontend.
- `plugins/`: game management plugin workspace. A plugin defines how to create and manage one server type, and one installed plugin can create many server instances.

The machine-side executor source lives in the separate `git@git.npc0.com:admin343/run.git` repository. Local debug and Docker workflows can keep the editable source at `./run` as an ignored nested checkout, or use another path through `RUN_SOURCE_DIR` / legacy `RUN_REPO_DIR`. Local debug snapshots that source into `.local-debug` before building or starting run.

## Product Scope

The platform focuses on:

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

AI 提供商 means model providers such as OpenAI-compatible endpoints, GPT providers, Claude-compatible relays, local model gateways, or custom base URL/key/model configurations. It does not mean run executors, host providers, billing providers, or cloud vendors.

## Communication Model

The platform must not use one overloaded channel for everything. Run communication is split by workload:

- Control: hello, heartbeat, version, capabilities, capacity.
- Job: claim, ack, progress, result, cancel, reconcile.
- Logs: compressed batch ingest with sequence ack and local spool.
- Artifacts: chunked, resumable, checksummed, throttled file transfer.
- Game client bridge: optional in-game command and snapshot polling for games that require it.

Logs are historical data, not a UI-only stream. Browser realtime tail may use platform SSE/WebSocket later, but run-to-platform logs must use durable ingest semantics.

## Governance

Read `AGENTS.md` before changing code. Each subproject also has a local `AGENTS.md` with stricter rules for that area.

The bootstrap skeleton already includes fixed directories for backend DTOs/models/protocols, platform-owned run contracts, frontend API/routes/contracts, and plugin manifests/schemas/SDK files. `scripts/check-structure.sh` checks these required paths so future changes cannot silently drop or bypass them.

## Development Baseline

Current tool baseline:

- Go 1.25.1 for `platform/`. The external run repository uses the same Go baseline.
- Node 22.17.0 and npm 11.6.1 for `platform_web/` and `plugins/`.

Install JavaScript dependencies before the first full check:

```bash
(cd platform_web && npm install)
(cd plugins && npm install)
```

Run all baseline checks from the repository root:

```bash
scripts/check-all.sh
```

Run focused checks when working in one root:

```bash
(cd platform && go test ./...)
(cd platform_web && npm run typecheck && npm run test && npm run build)
(cd plugins && npm run typecheck && npm run test && npm run validate:manifest)
```

Run executor checks are owned by the separate run checkout:

```bash
(cd "${RUN_SOURCE_DIR:-${RUN_REPO_DIR:-./run}}" && go test ./...)
```

Run the API-backed local debug workspace when you need platform, run, platform_web, and the dev plugin fixture together:

```bash
git clone git@git.npc0.com:admin343/run.git run # once, if the ignored local checkout is missing
scripts/dev-start.sh
scripts/dev-smoke.sh
```

See `docs/local-debug-workspace.md` for ports, disposable data roots, log files, reset steps, smoke evidence, and the required browser walkthrough. This workflow treats frontend local auth fallback as a verification failure.
Use `LOCAL_DEBUG_SELF_START=true scripts/dev-smoke.sh` when you need the smoke command to own the temporary local stack for the duration of the verification.

For local debug, prefer the managed scripts because they snapshot run source into the closed `.local-debug` build bucket and start the bootstrap worker from the built binary:

```bash
scripts/dev-start.sh
```

## Docker Deployment

Use the root compose file for a local all-in-one deployment:

```bash
git clone git@git.npc0.com:admin343/run.git run # once, if the ignored local checkout is missing
docker compose up --build
```

Then open:

- Web console: `http://127.0.0.1:5173`
- Platform API health: `http://127.0.0.1:8080/healthz`

The compose deployment starts:

- `platform`: backend on container port `8080`, published as host port `8080`.
- `run`: worker mode executor built from `${RUN_REPO_DIR:-./run}` and connected to `http://platform:8080`.
- `platform-web`: built static console served by Nginx on container port `80`, published as host port `5173`.

Persistent Docker data lives in named volumes:

- `platform-data`: platform metadata and segmented log bodies.
- `run-data`: run worker workspace and local spool data.

The default Docker storage is file-backed:

```text
PLATFORM_METADATA_PATH=/data/platform/metadata.json
PLATFORM_LOG_BODY_BACKEND=file
PLATFORM_LOG_DIR=/data/platform/logs
RUN_WORKSPACE_ROOT=/data/run/workspace
RUN_SPOOL_ROOT=/data/run/spool
```

To use MySQL for platform metadata in Docker, edit the existing `platform.environment` block in `docker-compose.yml`:

```yaml
PLATFORM_STORAGE_BACKEND: mysql
PLATFORM_MYSQL_DSN: platform:platform@tcp(mysql:3306)/platform?parseTime=true
PLATFORM_LOG_BODY_BACKEND: file
```

Change the existing `PLATFORM_STORAGE_BACKEND: file` line to `mysql`, uncomment/add the `PLATFORM_MYSQL_DSN` line, then uncomment the `mysql` service and the `platform.depends_on.mysql` block in `docker-compose.yml`.

MySQL stores platform metadata only: users, plugins, servers, jobs, audit events, log stream cursors, and indexes. Log bodies stay in `PLATFORM_LOG_DIR` as segmented files unless a future `LogBodyStore` adapter such as ClickHouse/Loki/OpenSearch is configured. Do not store hundreds or thousands of servers' log lines as one MySQL row per line.

To change Docker ports, storage paths, MySQL DSN, run identity, or the external run checkout path, edit `docker-compose.yml` or set `RUN_REPO_DIR`. Do not put real secrets in committed compose files; use a local untracked `.env` or shell environment for machine-specific values.

## Local Debug Configuration

Local direct execution uses environment variables, not a hard-required config file. Example files are provided so you can copy and modify them:

```text
.env.example
platform/.env.example
platform_web/.env.example
```

Typical local debugging:

```bash
cp platform/.env.example platform/.env
cp platform_web/.env.example platform_web/.env

scripts/dev-start.sh
scripts/dev-smoke.sh
```

Most common edits:

- Platform port: `PLATFORM_ADDR=:8080`.
- Platform file persistence: `PLATFORM_STORAGE_BACKEND=file`, `PLATFORM_METADATA_PATH`, `PLATFORM_LOG_DIR`.
- Platform MySQL metadata: `PLATFORM_STORAGE_BACKEND=mysql`, `PLATFORM_MYSQL_DSN=platform:platform@tcp(127.0.0.1:3306)/platform?parseTime=true`.
- Log body persistence: `PLATFORM_LOG_BODY_BACKEND=file`, `PLATFORM_LOG_DIR`.
- Run editable source checkout: `RUN_SOURCE_DIR=./run` by default; legacy `RUN_REPO_DIR` is accepted as an alias; `run/` is ignored by the browser repository.
- Run closed build bucket: `RUN_BUILD_BUCKET_ROOT=.local-debug/run/build-buckets`.
- Run build source snapshot: `RUN_BUILD_SOURCE_ROOT=.local-debug/run/build-buckets/source/current`.
- Run bootstrap binary: `RUN_BOOTSTRAP_BIN=.local-debug/run/build-buckets/bootstrap/bin/run`.
- Run worker mode: `RUN_MODE=worker`.
- Run-to-platform URL: `RUN_PLATFORM_URL=http://127.0.0.1:8080` locally, `http://platform:8080` in Docker.
- Run local data: `RUN_WORKSPACE_ROOT`, `RUN_SPOOL_ROOT`.
- Frontend API: `VITE_PLATFORM_API_BASE_URL=/api/v1`.
- Vite dev proxy: `PLATFORM_API_PROXY=http://127.0.0.1:8080`.

For hundreds or thousands of servers, keep relational databases for platform metadata, stream state, indexes, retention policy, and audit. Do not store high-volume log bodies as one MySQL row per line; use a future `LogBodyStore` adapter for ClickHouse, Loki, OpenSearch/Elasticsearch, or object-storage segments.

The frontend shell touches first-party pages, so UI changes require a browser walkthrough at desktop and mobile widths.

Before claiming a change is complete, run:

```bash
scripts/check-structure.sh
openspec validate <change> --strict
```

If a change adds new required directories, contracts, generated artifacts, or architectural rules, update `scripts/check-structure.sh` in the same change.

## OpenSpec Stream

The bootstrap proposal and delivery stream live at:

```text
openspec/changes/bootstrap-game-server-platform-architecture/
openspec/changes/architecture-delivery-stream/
```

Use `openspec/changes/architecture-delivery-stream/delivery-plan.md` to pick the next implementation change.