first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,76 @@
+# platform
+
+Backend control plane for the game server management platform.
+
+## Responsibilities
+
+- Users, roles, permissions, sessions, and audit.
+- Game management plugin installation metadata and marketplace views.
+- Server instance records and lifecycle orchestration.
+- AI provider configuration and platform-mediated AI invocation.
+- Run registration, capabilities, jobs, artifacts, log stream metadata, and storage adapters.
+
+## Required Directory Plan
+
+Implementation should use dedicated directories for:
+
+- `api/`: route wiring and HTTP/gRPC adapters.
+- `dto/`: request and response structures.
+- `domain/`: business types and aggregates.
+- `model/`: database models only.
+- `repo/`: repository interfaces and persistence implementations.
+- `service/`: use cases and orchestration.
+- `protocol/`: run, plugin, artifact, log, and AI contracts.
+- `validator/`: validation rules.
+- `config/`: configuration structures and loading.
+- `shared/`: small shared helpers.
+
+Do not put DTOs, database models, or protocol structs inside handlers or service functions.
+
+## Development Baseline
+
+Tooling:
+
+- Go 1.25.1.
+- Module: `browser.local/platform`.
+
+Commands:
+
+```bash
+go test ./...
+go run ./cmd/platform
+```
+
+Runtime configuration:
+
+- `PLATFORM_ADDR`: local listen address, default `:8080`.
+- `PLATFORM_STORAGE_BACKEND`: storage backend, default `file`; use `memory` only for tests or disposable local runs.
+- `PLATFORM_MYSQL_DSN`: MySQL DSN used when `PLATFORM_STORAGE_BACKEND=mysql`, for example `platform:platform@tcp(127.0.0.1:3306)/platform?parseTime=true`.
+- `PLATFORM_DATA_DIR`: default platform data directory, default `.platform-data`.
+- `PLATFORM_METADATA_PATH`: file-backed metadata snapshot path, default `.platform-data/metadata.json`.
+- `PLATFORM_LOG_BODY_BACKEND`: log body backend, default follows metadata backend except MySQL uses `file`; supported values are `file` and `memory`.
+- `PLATFORM_LOG_DIR`: segmented log body directory, default `.platform-data/logs`.
+
+MySQL configuration example:
+
+```bash
+export PLATFORM_STORAGE_BACKEND=mysql
+export PLATFORM_MYSQL_DSN='platform:platform@tcp(127.0.0.1:3306)/platform?parseTime=true'
+export PLATFORM_LOG_BODY_BACKEND=file
+export PLATFORM_LOG_DIR=.platform-data/logs
+go run ./cmd/platform
+```
+
+MySQL is the platform metadata database here. It stores the platform metadata snapshot table and should later hold normalized users/plugins/servers/jobs/audit/log stream indexes. It is not the high-volume log body store; keep log bodies in segmented files locally, or add a future ClickHouse/Loki/OpenSearch/object-storage `LogBodyStore` adapter for production scale.
+
+For local direct debugging, copy `platform/.env.example` to `platform/.env`, edit the values, and run:
+
+```bash
+go run ./cmd/platform
+```
+
+The platform process automatically reads root `.env` and `platform/.env` before loading configuration. Explicitly exported process environment values still take precedence over values in those files.
+
+For Docker, the root `docker-compose.yml` sets platform data under `/data/platform` and mounts it through the `platform-data` named volume.
+
+Current executable behavior includes the platform API, local auth/session support, durable file-backed metadata, segmented log bodies, run control/job/log/artifact routes, plugin bridge dispatch, and platform-mediated AI invocation.