From 4eac1e45ba164a9ae5e4a5b46eebdcdb5130c036 Mon Sep 17 00:00:00 2001 From: Hide_D Date: Sat, 27 Dec 2025 05:46:15 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20AGENTS.md,=20README.md,=20and=20archite?= =?UTF-8?q?cture=20documents=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?= =?UTF-8?q?=ED=95=98=EC=97=AC=20=EC=84=9C=EB=B2=84+=EC=8B=9C=EB=82=98?= =?UTF-8?q?=EB=A6=AC=EC=98=A4=20=ED=94=84=EB=A1=9C=ED=8C=8C=EC=9D=BC=20?= =?UTF-8?q?=EA=B0=9C=EB=85=90=20=EC=A0=95=EB=A6=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 20 +++++++++++--------- README.md | 12 +++++++----- docs/architecture/overview.md | 2 ++ docs/architecture/postgres-schema.md | 4 +++- docs/architecture/rewrite-plan.md | 7 ++++--- docs/architecture/runtime.md | 15 ++++++++------- docs/architecture/turn-daemon-lifecycle.md | 4 ++-- 7 files changed, 37 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bdec352..3688b54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,8 +34,8 @@ - `/app/gateway-frontend`: Gateway UI application. - `/app/gateway-api`: Gateway backend service. - `/app/game-frontend`: Game UI application. -- `/app/game-api`: Game backend service per server profile. -- `/app/game-engine`: Game engine / turn daemon per server profile. +- `/app/game-api`: Game backend service per server+scenario profile. +- `/app/game-engine`: Game engine / turn daemon per server+scenario profile. - `/tools/build-scripts`: build and deployment scripts. ## Planned Runtime & Tooling @@ -48,7 +48,7 @@ - Data: PostgreSQL; sessions backed by Redis. - Testing: Vitest. - Package manager: pnpm (workspace-based monorepo). -- Build output: server builds emitted to `/dist/{serverName}` per profile. +- Build output: server builds emitted to `/dist/{profileName}` per profile. ## Suggested Monorepo Scripts (Proposal) These are placeholders to align teams; adjust once packages exist. @@ -62,15 +62,17 @@ These are placeholders to align teams; adjust once packages exist. - `pnpm --filter ./app/game-engine dev`: run a single service by filter. ## Build Profiles (Proposal) -- Server builds should accept a profile (scenario, server variant) as an explicit input. -- Recommended pattern: a `tools/build-scripts` runner invoked by pnpm, e.g. `pnpm build:server --profile che`. -- Prefer environment variables for CI/CD (`PROFILE=che pnpm build:server`) and a small wrapper script for local usage. -- Build output stays in `/dist/{serverName}` per profile to keep deployments predictable. +- A build profile is a server+scenario pair; scenario selection is required even if a default exists. +- Server builds should accept a profile (server variant) plus an explicit scenario file input. +- Recommended pattern: a `tools/build-scripts` runner invoked by pnpm, e.g. `pnpm build:server --profile che --scenario default`. +- Prefer environment variables for CI/CD (`PROFILE=che SCENARIO=default pnpm build:server`) and a small wrapper script for local usage. +- Build output stays in `/dist/{profileName}` per profile to keep deployments predictable. - Profile selection can target different git branches or specific commits; server operators decide the compatibility baseline. -- Profiles should allow scenario selection and include the matching unit pack in the build output. +- The scenario file determines unit sets and DB settings that must be prepared before build output is emitted. ## Server Profiles (Planned) -- `che`, `kwe`, `pwe`, `twe`, `nya`, `pya` +- Server IDs: `che`, `kwe`, `pwe`, `twe`, `nya`, `pya` +- Each build/run profile combines a server ID with a scenario selection. ## Game Domain Notes (Behavioral Context) - Turn-based multiplayer loop with configurable tick length (historically 120/60/30/20/10/5/2/1 min; experimental day/night schedules). diff --git a/README.md b/README.md index 76a0e2e..3f6aa47 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ ## 목표 - 레거시 PHP 기반 런타임을 TypeScript 기반 모노레포로 전환 - 게임 로직을 순수 모듈로 분리하고 API/엔진/프론트를 서비스 단위로 구성 -- 프로파일(시나리오/서버 변형)별 빌드 및 배포 흐름 정립 +- 서버+시나리오 프로파일별 빌드 및 배포 흐름 정립 ## 구조 - `legacy/`: 현재 운영 중인 PHP 런타임 @@ -28,12 +28,14 @@ - `pnpm -r build` - `pnpm -r dev` - 서버 빌드 - - `pnpm build:server -- --profile ` - - 예: `pnpm build:server -- --profile che` + - `pnpm build:server -- --profile --scenario ` + - 예: `pnpm build:server -- --profile che --scenario default` ## 빌드 프로파일(예정) -- `che`, `kwe`, `pwe`, `twe`, `nya`, `pya` -- 빌드 출력: `/dist/{serverName}` +- 프로파일은 서버+시나리오 조합이며, 시나리오 파일 지정은 필수(기본값은 별도 정의). +- 시나리오 파일에 따라 유닛 세트, DB 세팅 등의 사전 준비가 달라짐. +- 서버 ID: `che`, `kwe`, `pwe`, `twe`, `nya`, `pya` +- 빌드 출력: `/dist/{profileName}` ## 난수 정책 (Verifiable RNG) 게임 로직에 영향을 주는 모든 난수는 재현 가능해야 합니다. diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 2d2a21e..22c8802 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -28,6 +28,8 @@ monorepo plan is prepared alongside it. - PHP engine owns authoritative gameplay state today - Scenario and unit pack data are loaded from `legacy/hwe/scenario/` - Deterministic RNG is required for gameplay outcomes +- Build/runtime profiles are server+scenario pairs; scenario selection is required + because it drives unit sets and DB settings. ## Legacy Docs diff --git a/docs/architecture/postgres-schema.md b/docs/architecture/postgres-schema.md index 7211a08..e47415f 100644 --- a/docs/architecture/postgres-schema.md +++ b/docs/architecture/postgres-schema.md @@ -11,7 +11,9 @@ fields. Use this as the starting point for Prisma models and migrations. - Keep JSONB values as objects (not arrays or scalars). - Use partial or expression indexes when a JSONB key becomes a hot filter. - If multiple server profiles live in one database, add `server_id` to every - table and index it; otherwise, use one database per profile. + table and index it; otherwise, use one database per profile. Scenario + selection is still required at build/runtime, but does not change the DB + partitioning baseline. ## Meta Policy (Reset) diff --git a/docs/architecture/rewrite-plan.md b/docs/architecture/rewrite-plan.md index 498eff7..9e927fc 100644 --- a/docs/architecture/rewrite-plan.md +++ b/docs/architecture/rewrite-plan.md @@ -10,8 +10,8 @@ Vue 3 frontends. - `/app/gateway-frontend`: gateway UI - `/app/gateway-api`: gateway service - `/app/game-frontend`: game UI -- `/app/game-api`: game backend per server profile -- `/app/game-engine`: turn daemon per server profile +- `/app/game-api`: game backend per server+scenario profile +- `/app/game-engine`: turn daemon per server+scenario profile - `/tools/build-scripts`: build and deployment scripts ## Runtime Stack (Planned) @@ -43,4 +43,5 @@ The shared constraint contract (daemon vs API precheck split) is documented in ## Profiles (Planned) -- `che`, `kwe`, `pwe`, `twe`, `nya`, `pya` +- Profiles are server+scenario pairs; scenario selection is required for build/runtime. +- Server IDs: `che`, `kwe`, `pwe`, `twe`, `nya`, `pya` diff --git a/docs/architecture/runtime.md b/docs/architecture/runtime.md index 07ce7a1..a1be1e4 100644 --- a/docs/architecture/runtime.md +++ b/docs/architecture/runtime.md @@ -1,13 +1,14 @@ # Runtime and Build Profiles -Build outputs should be emitted to `/dist/{serverName}` per profile to keep -deployments predictable. +Build outputs should be emitted to `/dist/{profileName}` per profile to keep +deployments predictable. Profiles are server+scenario pairs, and scenario +selection is required because it drives unit sets and DB settings. ## Suggested Build Pattern - Wrapper script under `tools/build-scripts` -- `pnpm build:server --profile che` -- CI-friendly: `PROFILE=che pnpm build:server` +- `pnpm build:server --profile che --scenario default` +- CI-friendly: `PROFILE=che SCENARIO=default pnpm build:server` ## Deterministic RNG Policy @@ -44,7 +45,7 @@ replay while pub/sub keeps live updates simple and low-latency. ### Operational Notes -- Stream keys should be namespaced per server profile. +- Stream keys should be namespaced per server+scenario profile. - Use bounded stream length (`MAXLEN`) to cap storage. - API server should guard against duplicate processing by `requestId`. - When the daemon is busy, API queues new mutations to stream and responds @@ -70,10 +71,10 @@ also supports local ID/password login for users who cannot use Kakao. - Gateway handles login and owns primary sessions in Redis. - Game servers may run different branches; treat Gateway as a central SSO - authority that issues session tokens for each server profile. + authority that issues session tokens for each server+scenario profile. - API servers validate tokens against Redis and accept sessions issued by Gateway without re-authentication. -- Session tokens should be scoped by server profile to avoid cross-server leaks. +- Session tokens should be scoped by server+scenario profile to avoid cross-server leaks. ### Operational Notes diff --git a/docs/architecture/turn-daemon-lifecycle.md b/docs/architecture/turn-daemon-lifecycle.md index 14f957d..02e5ca5 100644 --- a/docs/architecture/turn-daemon-lifecycle.md +++ b/docs/architecture/turn-daemon-lifecycle.md @@ -6,7 +6,7 @@ from the API server. ## Assumptions -- One daemon process per server profile. +- One daemon process per server+scenario profile. - API server is the only ingress for user/admin requests. - The daemon is the only component that mutates gameplay state. @@ -111,7 +111,7 @@ Admin controls should toggle `paused`, trigger manual run, and request catch-up. ```json { - "profile": "che", + "profile": "che:default", "state": "idle", "running": false, "paused": false,