docs: consolidate current architecture documentation
This commit is contained in:
@@ -1,106 +1,62 @@
|
||||
# 도메인 로직과 핵심 클래스
|
||||
# 도메인과 조립 지점
|
||||
|
||||
## 핵심 entity
|
||||
## World entity
|
||||
|
||||
`packages/logic/src/domain/entities.ts`가 HTTP나 Prisma row에 종속되지 않은 `General`, `City`, `Nation`,
|
||||
`Troop`, diplomacy와 trigger 상태를 정의합니다. engine 전용 `TurnGeneral`, `TurnWorldState`,
|
||||
`TurnEvent`는 `app/game-engine/src/turn/types.ts`에서 실행 시간·예약 턴·월간 상태를 더합니다.
|
||||
`packages/logic/src/domain/entities.ts`와 `world/types.ts`가 장수, 국가, 도시,
|
||||
부대, 외교와 trigger state의 런타임 타입을 정의합니다. Prisma row는
|
||||
`app/game-engine/src/turn/worldLoader.ts`가 이 타입으로 변환합니다.
|
||||
`InMemoryTurnWorld`가 조회와 mutation을 제공하고 `EngineStateManager`가
|
||||
transaction snapshot과 dirty state를 관리합니다.
|
||||
|
||||
| entity | 핵심 책임 |
|
||||
| ------- | -------------------------------------------------------------------------- |
|
||||
| General | 능력치, 경험·공헌, 소속·도시·부대, 병력·훈련·사기, 자원, 특기·아이템, meta |
|
||||
| City | 소유 국가, 규모, 인구·농업·상업·치안, 수비·성벽, 보급·전선 상태 |
|
||||
| Nation | 수도, 국고·군량, 등급·국가 타입, 기술과 국가 meta |
|
||||
| Troop | 부대장·구성원과 부대 상태 |
|
||||
| World | 현재 연·월, 최근 턴 시각, scenario config/meta와 전체 entity collection |
|
||||
## Command
|
||||
|
||||
Prisma row를 곧바로 게임 규칙에 넘기지 않습니다. `worldLoader.ts`와 API의 row mapper가 DB 표현을 domain
|
||||
표현으로 바꾸고, flush 계층이 반대 변환을 담당합니다.
|
||||
장수 command는 `GeneralActionDefinition`으로 다음 계약을 가집니다.
|
||||
|
||||
## 명령 정의
|
||||
- key와 사용자 표시 이름
|
||||
- raw args parser
|
||||
- 예약, 최소, 실행 constraint
|
||||
- 실패 문구 formatter
|
||||
- pre/post turn과 stack metadata
|
||||
- state patch, log와 side effect를 담는 실행 결과
|
||||
|
||||
`GeneralActionDefinition`은 장수·국가 예약 명령이 공유하는 계약입니다.
|
||||
국가 command는 `packages/logic/src/actions/turn/nation`의 module과
|
||||
`app/game-engine/src/turn/reservedTurnCommands.ts`에서 같은 실행 context에
|
||||
연결됩니다. `commandRegistry.ts`와 command profile이 profile별 가용 명령을
|
||||
결정합니다.
|
||||
|
||||
- `key`, `name`: 저장 key와 화면 표시명
|
||||
- `parseArgs`: 외부 입력을 실행 인자로 변환
|
||||
- `buildPermissionConstraints`: 예약 입력 자체를 허용할지 판단
|
||||
- `buildMinConstraints`: command table에서 현재 가능한지 사전 판단
|
||||
- `buildConstraints`: 실행 시점의 전체 조건
|
||||
- `getPreReqTurn`, `getPostReqTurn`: 연속 실행과 재사용 대기
|
||||
- `resolve`: domain state와 effect를 계산
|
||||
## Constraint
|
||||
|
||||
각 파일의 `commandSpec`은 category, 인자 필요 여부, schema와 definition factory를 등록합니다.
|
||||
`GENERAL_TURN_COMMAND_KEYS`, `NATION_TURN_COMMAND_KEYS`가 전체 key 집합이며, `TurnCommandProfile`이
|
||||
profile별 subset을 선택합니다.
|
||||
`packages/logic/src/constraints`는 `ConstraintContext`와 `StateView`를 받아
|
||||
예약·실행 조건을 평가합니다. API가 client 입력을 검증하는 단계와 daemon이
|
||||
실행 직전 world 상태를 검사하는 단계는 분리합니다. 실패 결과는 ref 문구,
|
||||
turn 소비와 side effect 계약을 보존합니다.
|
||||
|
||||
## Constraint 시스템
|
||||
## Action module
|
||||
|
||||
`packages/logic/src/constraints`는 “무엇이 필요한가”와 “현재 view가 무엇을 알고 있는가”를 분리합니다.
|
||||
`ConstraintContext`에는 actor, city, nation, args, env와 평가 mode가 있고 `StateView`가 entity와 대상
|
||||
정보를 제공합니다.
|
||||
`loadActionModuleBundle()`은 국가 특성, 관직, 내정 특기, 전투 특기, 성격,
|
||||
병종, 계승, scenario slot, item 순서로 module을 조립합니다. 계산 fold,
|
||||
priority trigger와 의미 event는 각각 다른 interface를 사용합니다.
|
||||
[행동 모듈 프로토콜](../architecture/action-module-protocol.md)을 따라 주세요.
|
||||
|
||||
평가 결과는 다음 셋입니다.
|
||||
## 주요 클래스
|
||||
|
||||
- `allow`: 현재 정보로 조건을 만족합니다.
|
||||
- `deny`: 이유가 확정된 실패입니다.
|
||||
- `unknown`: 대상 입력이나 추가 state가 없어 아직 판정할 수 없습니다.
|
||||
| 클래스·함수 | 책임 |
|
||||
| ------------------------- | -------------------------------------------------- |
|
||||
| `GatewayOrchestrator` | profile operation과 process reconciliation |
|
||||
| `createGameApiServer` | game transport, context, router와 worker lifecycle |
|
||||
| `DatabaseTurnDaemonLease` | profile별 lease, heartbeat와 fencing |
|
||||
| `TurnDaemonLifecycle` | schedule, pause/resume/run/shutdown loop |
|
||||
| `InMemoryTurnWorld` | turn 실행 중 world state와 dirty tracking |
|
||||
| `EngineStateManager` | snapshot, transaction flush와 rollback restore |
|
||||
| `ReservedTurnHandler` | revision·lease 기반 예약 명령 claim과 실행 |
|
||||
| `GeneralActionPipeline` | action module 계산·trigger·event 실행 |
|
||||
| `WarEngine` | 전투 phase, RNG, 상태와 log 결과 |
|
||||
|
||||
API command table은 `unknown`의 missing requirement가 대상 입력뿐이면 `needsInput`, 그 밖이면
|
||||
`unknown`으로 보여 줍니다. 예약 뒤 실제 실행에서는 전체 context로 다시 판단합니다.
|
||||
## 명령 추가
|
||||
|
||||
## 핵심 클래스와 조립 지점
|
||||
|
||||
### TurnDaemonLifecycle
|
||||
|
||||
`app/game-engine/src/lifecycle/turnDaemonLifecycle.ts`에 있습니다. clock, control queue, hook과 run budget을
|
||||
조정하며 pause/resume/manual/scheduled run의 상태 전이를 소유합니다.
|
||||
|
||||
### DatabaseTurnDaemonLease
|
||||
|
||||
`app/game-engine/src/lifecycle/databaseTurnDaemonLease.ts`에 있습니다. profile별 단일 active owner와 fencing을
|
||||
관리합니다. daemon 계산이 맞아도 lease를 잃었다면 결과를 저장하면 안 됩니다.
|
||||
|
||||
### InMemoryTurnWorld
|
||||
|
||||
`app/game-engine/src/turn/inMemoryWorld.ts`에 있습니다. entity map, dirty/create/delete set, log, message,
|
||||
event, checkpoint와 월 변경을 소유합니다. `peekDirtyState()`는 저장할 변경을 보여 주고 성공한 flush 뒤
|
||||
정리됩니다.
|
||||
|
||||
### EngineStateManager
|
||||
|
||||
`app/game-engine/src/turn/engineStateManager.ts`에 있습니다. world와 예약 턴 store 같은 mutable participant를
|
||||
등록하고 계산 단위의 capture/restore/transaction을 제공합니다. PostgreSQL transaction을 대신하지 않고
|
||||
실패한 계산의 메모리 rollback을 담당합니다.
|
||||
|
||||
### InMemoryReservedTurnStore와 ReservedTurnHandler
|
||||
|
||||
`reservedTurnStore.ts`는 장수 30칸·국가 12칸 예약 queue를 메모리에 유지합니다.
|
||||
`reservedTurnHandler.ts`는 명령 loading, constraint, action context, AI fallback, progress/cooldown,
|
||||
효과·로그와 queue rotation을 연결합니다.
|
||||
|
||||
### GeneralActionPipeline과 trigger module
|
||||
|
||||
`packages/logic/src/actions/engine.ts`, `triggers/*`는 명령 본체 전후의 특기·아이템·국가 특성 효과를
|
||||
일정한 우선순위로 적용합니다. 같은 module 목록이라도 실행 순서가 결과와 RNG 소비를 바꿀 수 있습니다.
|
||||
|
||||
### WarEngine
|
||||
|
||||
`packages/logic/src/war/engine.ts`가 전투 resolution을, `war/actions.ts`와 trigger module이 확장 효과를,
|
||||
`war/aftermath.ts`가 피해·점령·외교·후속 state를 계산합니다. `che_출병.ts`가 map, unit set, diplomacy,
|
||||
time, seed와 aftermath를 조립하는 실제 장수 명령 entry입니다.
|
||||
|
||||
### GatewayOrchestrator
|
||||
|
||||
`app/gateway-api/src/orchestrator/gatewayOrchestrator.ts`가 DB의 profile desired state를 process state에
|
||||
맞춥니다. `workspaceManager.ts`, `buildRunner.ts`, `seedProfileDatabase.ts`, `pm2ProcessManager.ts`가
|
||||
commit worktree 준비부터 build, seed, start/stop을 나눕니다.
|
||||
|
||||
## 새 명령을 추가할 때
|
||||
|
||||
1. 가장 가까운 ref command의 constraint, 실행 순서, RNG, 로그와 DB side effect를 조사합니다.
|
||||
2. `packages/logic/src/actions/turn/{general,nation}`에 definition과 `commandSpec`을 작성합니다.
|
||||
3. 해당 `*_TURN_COMMAND_KEYS`와 필요한 `resources/turn-commands` profile에 key를 등록합니다.
|
||||
4. 인자가 있으면 Zod schema와 `app/game-api/src/turns/commandInput.ts`의 화면 입력 field를 연결합니다.
|
||||
5. engine action context가 대상 entity·map·unit set·시간·seed를 완전하게 공급하는지 확인합니다.
|
||||
6. permission/min/full 실패, 성공, 연속 턴, cooldown과 persistence를 테스트합니다.
|
||||
7. `pnpm docs:generate`로 플레이어 커맨드 목록을 갱신하고 ref 매핑 문서를 함께 수정합니다.
|
||||
1. ref command의 예약·실행 constraint, args, RNG, log와 DB mutation을 찾습니다.
|
||||
2. command definition과 필요한 domain helper를 추가합니다.
|
||||
3. engine registry, profile resource와 frontend args UI를 연결합니다.
|
||||
4. state patch와 dirty field가 flush·reload되는지 확인합니다.
|
||||
5. 정상·실패·경계 fixed-seed test와 ref 차등 fixture를 추가합니다.
|
||||
6. 생성 command catalog, 상위 mapping과 report를 갱신합니다.
|
||||
|
||||
Reference in New Issue
Block a user