codex와 함께하는 AGENTS.md 작성하기

AGENTS.md

@@ -1,5 +1,9 @@
 # Repository Guidelines
 
+## Project Goal (Rewrite)
+- This repository is transitioning from the legacy PHP codebase to a TypeScript-based monorepo using pnpm workspaces.
+- The legacy game remains the current active source under `legacy/` while the rewrite is prepared alongside it.
+
 ## Project Structure & Module Organization
 - `legacy/` contains the application source. This is the active codebase.
 - PHP entry points live under `legacy/` and `legacy/hwe/` (for example `legacy/index.php`, `legacy/hwe/index.php`).
@@ -19,6 +23,56 @@
 - Tests: PHPUnit in `legacy/tests/`, TypeScript tests in `legacy/hwe/test-ts/`.
 - Static data/assets: scenarios in `legacy/hwe/scenario/`, templates in `legacy/hwe/templates/`.
 
+## Legacy Endpoint Patterns
+- JSON API handlers: `legacy/hwe/j_*.php`.
+- Vue multi-entry pages: `legacy/hwe/v_*.php`.
+- Legacy PHP + jQuery pages: `legacy/hwe/b_*.php` with POST handlers in `legacy/hwe/c_*.php`.
+- Modern API router: `legacy/hwe/api.php` accepts a path argument and dispatches to `legacy/hwe/API/` modules.
+
+## Planned Monorepo Layout (TypeScript Rewrite)
+- `/packages/common`: shared utilities and type definitions.
+- `/packages/logic`: pure game logic with DI/interfaces for external dependencies.
+- `/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.
+- `/tools/build-scripts`: build and deployment scripts.
+
+## Planned Runtime & Tooling
+- Backend: Node.js + Fastify, with Prisma ORM.
+- API: tRPC + zod.
+- Frontend: Vue 3, Pinia, Vue Router, TailwindCSS, Vite.
+- Data: PostgreSQL; sessions backed by Redis.
+- Testing: Vitest.
+- Package manager: pnpm (workspace-based monorepo).
+- Build output: server builds emitted to `/dist/{serverName}` per profile.
+
+## Suggested Monorepo Scripts (Proposal)
+These are placeholders to align teams; adjust once packages exist.
+- `pnpm install`: install all workspace dependencies.
+- `pnpm -r lint`: lint all packages.
+- `pnpm -r test`: run all unit tests.
+- `pnpm -r build`: build all packages/apps.
+- `pnpm -r dev`: run dev servers where applicable.
+- `pnpm --filter ./app/game-engine dev`: run a single service by filter.
+
+## Server Profiles (Planned)
+- `che`, `kwe`, `pwe`, `twe`, `nya`, `pya`
+
+## 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).
+- Core stats: leadership, strength, intelligence with effects on internal affairs and combat.
+- Traits and modifiers apply via the Trigger system, evaluated by priority; "attempt" then "execute".
+- Scenarios define maps, NPCs, initial resources; scenario loading separated to allow future modding.
+- "Unit packs" bundle unit graphics, audio, and special effects per scenario.
+
+## Randomness Policy (Verifiable RNG)
+- All game-impacting randomness must be verifiable and reproducible from a deterministic seed.
+- Prefer reusing the existing TypeScript implementations: `legacy/hwe/ts/util/LiteHashDRBG.ts` and `legacy/hwe/ts/util/RNG.ts` with minimal or no changes.
+- Seed composition should include a hidden base seed plus action context (action type, time, actor, target) so results can be re-validated later.
+- Do not introduce ad-hoc randomness in game logic; allow non-deterministic randomness only for non-gameplay, cosmetic, or UI-only cases.
+
 ## Build, Test, and Development Commands
 Run commands from `legacy/` unless noted.
 - `composer install` installs PHP dependencies.
@@ -32,12 +86,14 @@ Run commands from `legacy/` unless noted.
 - `npm run test-ts` runs TypeScript tests only.
 
 ## Coding Style & Naming Conventions
-- Indentation: 4 spaces, no tabs; line length ~120
-- PHP modules follow PSR-4 in `legacy/src/sammo/`.
-- Legacy endpoints are named by role: JSON handlers `legacy/hwe/j_*.php`, views `legacy/hwe/v_*.php`, admin pages `legacy/hwe/_admin*.php`.
-- Vue components use PascalCase filenames (e.g., `legacy/hwe/ts/components/MapViewer.vue`).
+- Follow repo lint/format configuration once it exists; keep diffs consistent within a file.
+- Indentation: 4 spaces for TypeScript, JSON, and Vue SFCs.
+- Prefer explicit types for public APIs; avoid `any` and narrow `unknown`.
+- Vue components: PascalCase filenames; composables use `useX` naming.
+- Use `camelCase` for variables/functions and `PascalCase` for classes/types.
+- Legacy concepts may use Korean identifiers; preserve Korean naming when it improves maintainability.
+- Hybrid naming is acceptable (e.g., `use전투규칙`, `use도시상태`) when the prefix is conventional but the domain term is Korean.
 
 ## Commit & Pull Request Guidelines
 - Git history is minimal and does not define a strict convention; use short, imperative messages (e.g., "Fix map cache loading").
 - PRs should include a concise description, testing notes/commands, and screenshots for UI changes.
-- Avoid committing secrets; use templates in `legacy/f_install/templates/` and settings files under `legacy/hwe/d_setting/` as references.

tmp_guide.md

@@ -12,8 +12,55 @@
   - 시도해보진 않았지만, 1분 미만의 턴 시간도 고려해보긴 하였음.
   - 단 NPC 턴의 경우 CPU 부하가 있어서, 기존 php 기반 서버에서는 1분 미만의 턴 시간은 불가능했음. 이론상으로 잘 최적화된다면 30초 서버같은 것도 가능은 할 것으로 예상함.
 - 장수의 경우 현재 통솔, 무력, 지력의 3가지 스탯을 가지고 있음.
-
+  - 통솔의 경우 통솔 관련 내정, 그리고 전쟁 시 병력의 최대 숫자에 영향을 줌.
+    - 훈련, 사기진작과 같은 커맨드는 통솔 스탯과 현재 보유중인 병력 수에 영향을 받음. 통솔이 높고, 병력 수가 적다면 훈련, 사기진작 커맨드로 올라가는 수치는 비교적 높음.
+  - 무력의 경우 무력관련 내정, 무장 병종의 공격력, 방어력에 영향을 줌.
+  - 지력의 경우 지력관련 내정, 지장 병종의 공격력, 방어력에 영향을 주며, 지장 병종의 특수 스킬인 '책략'의 시도 확률에 영향을 줌.
+- 각 행동에 영향을 줄 수 있는 다양한 요소가 있음
+  - 국가의 성향.
+  - 장수의 성격, 내정 특기(내특), 전술 특기(전특)
+  - 병종의 특성
+  - 소속 도시의 특성
+  - 보유중인 아이템
+  - 수뇌 특성
+  - 기타 등
+- 이들 요소는 로직 내에서 Trigger 라는 시스템으로 운용되며, 내부적으로 특정 조건이 만족하는지 선행 검사하는 로직, 다른 로직에서 다른 로직이 평가중인 경우 추가로 참여하며, 최종 결과에 따라 로직이 실행되는 구조를 가짐
+  - 'A 시도', 'A 실행' 형태가 되며, 일반적으로 시도가 우선순위가 높고, 실행이 후순위임.
+  - Trigger 는 여러개가 동시에 평가될 수 있으며, 이 경우 우선순위에 따라 순차적으로 평가됨.
+- 각각의 게임은 '시나리오' 라는 형태로 구성되며, 시나리오에 따라 맵, 도시 배치, NPC 장수 및 국가 배치, 초기 자원 등이 결정됨.
+  - 시나리오는 고정된 형태로 제공되며, 현재는 유저가 직접 시나리오를 제작하는 기능은 없음.
+    - 패치로 시나리오가 추가되거나 변경될 수는 있음.
+  - 단 향후 모드 지원을 고려하여, 시나리오 로딩 및 규칙 적용 부분은 별도의 모듈로 분리되어 있음.
+- 또한 '유닛 팩'(병종 타입) 이라는 형태로, 장수 및 병종의 그래픽 리소스, 음성 리소스, 일부 특수 효과 등이 묶여서 제공됨.
+  - 시나리오마다 유닛 팩이 다를 수 있음.
 
 ## 기술 스택
 - DBMS의 경우 기존에는 MariaDB(MySQL)을 기반으로 하였으나, 재작성 이후에는 PostgreSQL을 기반으로 할 예정임.
--
+- 세션의 경우 PHP에서는 file 기반이었으나, 재작성 이후에는 Redis 기반으로 할 예정임.
+- 백엔드는 Node.js 기반의 Fastify 프레임워크를 사용할 예정임.
+  - ORM으로는 Prisma를 사용할 예정임.
+  - 대부분은 API 서버로만 동작하며, 일부 서버는 SSR도 담당할 예정임.
+  - API 서버로는 tRPC와 zod를 사용할 예정임.
+- 번들러로는 Vite를 사용할 예정임.
+- 프론트엔드는 Vue 3 기반으로 작성할 예정임.
+  - 상태 관리는 Pinia를 사용할 예정임.
+  - 라우팅은 Vue Router를 사용할 예정임.
+  - 스타일링은 TailwindCSS를 사용할 예정임.
+- 테스트 프레임워크는 Vitest를 사용할 예정임.
+- 패키지 매니저는 pnpm을 사용할 예정임.
+- 개념적으로 Gateway와 각각의 서버(che, kwe, pwe, twe, nya, pya)가 있음.
+  - 각각의 서버는 클라이언트, API 서버, 게임 엔진 서버(턴 데몬)으로 구성됨.
+  - 단 서버의 경우 기본적으로 backward compatibility를 유지하는 별도의 브랜치, 혹은 프리뷰 서버로 각각이 운영될 수 있음.
+  - 이를 위해 실제 서버는 프로파일을 이용한 서버 빌드를 통해 `/dist/{서버이름}` 형태로 빌드된 후, 서버가 구동될 것임
+
+
+
+## 폴더 구성
+- `/packages/common`: 공통 유틸리티, 타입 정의 등이 위치함.
+- `/packages/logic`: 게임 로직이 위치함. DB 등의 요소는 포함하지 않으며, 순수 게임 로직만 포함함. DB가 필요하다면 DI 혹은 Interface로만 제공될 것임.
+- `/app/gateway-frontend`: Gateway 프론트엔드 애플리케이션이 위치함.
+- `/app/gateway-api`: Gateway 백엔드 애플리케이션이 위치함. 
+- `/app/game-frontend`: 게임 프론트엔드 애플리케이션이 위치함.
+- `/app/game-api`: 각각의 게임 서버 백엔드 애플리케이션이 위치함.
+- `/app/game-engine`: 각각의 게임 서버 게임 엔진(턴 데몬) 애플리케이션이 위치함.
+- `/tools/build-scripts`: 빌드 스크립트가 위치함.