docs: consolidate current architecture documentation
This commit is contained in:
@@ -1,66 +1,114 @@
|
||||
# Architecture Overview
|
||||
# core2026 아키텍처
|
||||
|
||||
This repository contains both the active legacy PHP game and an in-progress
|
||||
TypeScript rewrite. The legacy engine remains the source of truth while the
|
||||
monorepo plan is prepared alongside it.
|
||||
## 시스템 경계
|
||||
|
||||
## Project Naming
|
||||
`core2026`은 계정·profile 운영을 담당하는 gateway와 profile별 게임 런타임을
|
||||
분리합니다.
|
||||
|
||||
- Official name: 삼국지 모의전투 HiDCHe
|
||||
- Common nicknames: 삼모, 삼모전, 힏체섭
|
||||
- Short forms in code/docs: sammo, hidche
|
||||
- TypeScript rewrite working name: sammo-ts
|
||||
```text
|
||||
browser
|
||||
├─ gateway-frontend ── tRPC ── gateway-api
|
||||
│ ├─ gateway PostgreSQL
|
||||
│ ├─ Redis session
|
||||
│ └─ GatewayOrchestrator ── worktree / PM2
|
||||
└─ game-frontend ───── tRPC/SSE ─ game-api
|
||||
├─ profile PostgreSQL
|
||||
├─ Redis worker/fan-out
|
||||
└─ input_event ── game-engine
|
||||
├─ DB lease/fencing
|
||||
├─ in-memory world
|
||||
└─ transactional flush
|
||||
```
|
||||
|
||||
## Layers
|
||||
Gateway session과 game session token은 별도 수명을 가집니다. game API는
|
||||
token의 user, profile, role, sanction을 검증하고, 장수·국가 소유권은
|
||||
PostgreSQL 상태와 결합해 서버에서 결정합니다.
|
||||
|
||||
- Legacy runtime: PHP entry points under `legacy/` and `legacy/hwe/`
|
||||
- Legacy engine core: domain logic under `legacy/hwe/sammo/`
|
||||
- Legacy frontend: Vue/TypeScript under `legacy/hwe/ts/`
|
||||
- Rewrite (in progress): pnpm workspace monorepo under `packages/` and `app/`
|
||||
## 애플리케이션
|
||||
|
||||
## Current Implementation Notes
|
||||
### Gateway
|
||||
|
||||
- `packages/infra` is live with Prisma/Postgres connectors used by game services.
|
||||
- `app/game-engine` implements an in-memory turn daemon with DB flush hooks and Redis control transport.
|
||||
- `app/game-api` exposes tRPC endpoints for reserved turns, messages, and battle sims, communicating with the daemon via Redis.
|
||||
- Gateway/game frontends are still placeholders (not part of current runtime).
|
||||
- `app/gateway-frontend`는 가입, 로그인, 로비, 계정, 관리자 화면을 제공합니다.
|
||||
- `app/gateway-api/src/router.ts`는 인증·로비·계정 router를 조립합니다.
|
||||
- `app/gateway-api/src/adminRouter.ts`는 관리자 인증 뒤 사용자·profile·operation
|
||||
기능을 제공합니다.
|
||||
- `app/gateway-api/src/orchestrator/`는 DB operation queue, commit별 worktree,
|
||||
build, PM2 process와 예약 상태를 조정합니다.
|
||||
|
||||
## Legacy Data Migration Policy
|
||||
### Game
|
||||
|
||||
- Data under `legacy/` is migration-only and not used by the rewrite at runtime.
|
||||
- After DB migration completes, legacy data is no longer required.
|
||||
- `app/game-frontend`는 profile base path에서 실행하는 Vue SPA입니다.
|
||||
- `app/game-api/src/router.ts`는 auth, public, general, nation, turns, board,
|
||||
message, auction, tournament, archive 등 도메인 router를 조립합니다.
|
||||
- `app/game-api/src/realtime/`은 commit 이후 알림을 SSE로 전달합니다.
|
||||
- `app/game-api/src/daemon/`, `battleSim/`, `auction/`, `tournament/`는 각 worker
|
||||
transport와 scheduler를 소유합니다.
|
||||
- `app/game-engine/src/turn/turnDaemon.ts`는 world loader, 명령 registry,
|
||||
AI, 월간 action, persistence hook을 조립합니다.
|
||||
- `TurnDaemonLifecycle`은 clock, schedule, pause/resume/run command와 한 번의
|
||||
실행 transaction을 제어합니다.
|
||||
|
||||
## Data and State
|
||||
## 공유 package
|
||||
|
||||
- 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.
|
||||
### `packages/common`
|
||||
|
||||
## Legacy Docs
|
||||
프로세스 사이에 공유하는 타입, schema, 인증 token, 직렬화와 RNG가 있습니다.
|
||||
Gameplay 난수는 `LiteHashDRBG`, `RNG`, `RandUtil` 경로를 사용합니다.
|
||||
|
||||
- Legacy entities and DB schema overview: `docs/architecture/legacy-entities.md`
|
||||
- Legacy engine map: `docs/architecture/legacy-engine.md`
|
||||
- Postgres schema proposal (rewrite): `docs/architecture/postgres-schema.md`
|
||||
### `packages/logic`
|
||||
|
||||
## Cross-Cutting Policies
|
||||
DB와 서버 process에 종속되지 않는 게임 규칙을 소유합니다.
|
||||
|
||||
- No ad-hoc randomness for gameplay; use deterministic RNG
|
||||
- External JSON/data inputs must be validated with zod; name zod schemas with a `z` prefix.
|
||||
- Keep domain logic independent of endpoints or UI
|
||||
- Prefer clear Korean comments in core gameplay logic for maintainers
|
||||
- Test strategy and layering: `docs/testing-policy.md`
|
||||
- `actions/`: 장수·국가 command definition과 실행 결과
|
||||
- `constraints/`: 예약·실행 조건과 state view
|
||||
- `actionModules/`: trait·관직·병종·계승·item 효과 조립
|
||||
- `war/`: 전투 unit, phase, trigger와 결과
|
||||
- `scenario/`, `world/`: resource schema와 world 타입
|
||||
- `items/`, `crewType/`, `inheritance/`, `diplomacy/`: 도메인 catalog
|
||||
|
||||
## Runtime Processing (Outline)
|
||||
Command는 `GeneralActionDefinition` 또는 국가 command module로 args,
|
||||
constraint, turn metadata, 결과와 로그를 선언합니다. 런타임 context와
|
||||
persistence는 `app/game-engine`이 제공합니다.
|
||||
|
||||
This document links to detailed runtime behavior in `docs/architecture/runtime.md`.
|
||||
Use that document for turn daemon scheduling, API request handling, and
|
||||
persistence sequencing.
|
||||
### `packages/infra`
|
||||
|
||||
The turn daemon lifecycle and control contract are documented in
|
||||
`docs/architecture/turn-daemon-lifecycle.md`.
|
||||
`prisma/gateway.prisma`와 `prisma/game.prisma`가 영속 schema의 기준입니다.
|
||||
`src/gatewayPrisma.ts`, `src/gamePrisma.ts`, `src/postgres.ts`, `src/redis.ts`가
|
||||
연결과 client 생성을 담당합니다.
|
||||
|
||||
## Documentation TODOs
|
||||
## 데이터 소유권
|
||||
|
||||
- Pending follow-ups: `docs/architecture/todo.md`.
|
||||
| 데이터 | 기준 저장소 | 주요 접근 경로 |
|
||||
| ----------------------------- | ------------------------------------ | --------------------- |
|
||||
| 사용자·계정·profile·operation | gateway PostgreSQL | gateway API |
|
||||
| gateway session·flush signal | Redis | gateway API |
|
||||
| world·장수·국가·도시·턴·로그 | profile PostgreSQL | game API, game engine |
|
||||
| durable 입력과 실행 상태 | profile PostgreSQL `InputEvent` | game API, game engine |
|
||||
| turn daemon 소유권 | profile PostgreSQL `TurnDaemonLease` | game engine |
|
||||
| realtime 알림 | Redis와 SSE | game API |
|
||||
| scenario·map·unit set | `resources/` | game engine, build |
|
||||
| 이미지 | 외부 `/image/*` | Caddy |
|
||||
|
||||
게임 상태 mutation은 PostgreSQL transaction이 확정합니다. Redis 전달 성공을
|
||||
DB commit의 대체 조건으로 사용하지 않습니다.
|
||||
|
||||
## 시나리오와 profile
|
||||
|
||||
`profile`은 규칙·자산 계열이고 `scenario`는 게임 초기 데이터입니다.
|
||||
런타임 식별자는 `${profile}:${scenario}`입니다. Scenario JSON은
|
||||
`resources/scenario`에서 합성되고 zod parser를 거쳐 seeder와 runtime에
|
||||
전달됩니다. map, unit set, turn-command profile도 resource loader를 통해
|
||||
선택됩니다.
|
||||
|
||||
## 구현을 찾는 순서
|
||||
|
||||
1. frontend route와 store에서 사용자 흐름을 찾습니다.
|
||||
2. gateway/game tRPC router에서 input, auth, transaction을 찾습니다.
|
||||
3. engine command registry와 handler에서 실행 순서를 찾습니다.
|
||||
4. `packages/logic`에서 constraint, 계산, trigger를 찾습니다.
|
||||
5. Prisma schema, loader, dirty state, flush hook에서 저장 경계를 찾습니다.
|
||||
6. unit·integration·differential·Chromium fixture에서 보장 범위를 확인합니다.
|
||||
|
||||
ref 대응은 상위 작업공간의 `../docs/ref-core2026-mapping.md`를 사용합니다.
|
||||
현재 코드 경로가 문서의 근거이며, 보고서의 완료 표현만으로 구현 상태를
|
||||
판정하지 않습니다.
|
||||
|
||||
Reference in New Issue
Block a user