독자 수준별 구조 문서와 게이머 입문·전술 안내를 재정비한다

docs/developer/domain-and-classes.md

@@ -1,16 +1,33 @@
 # 도메인과 조립 지점
 
+**도메인**은 장수·도시·전투처럼 이 게임이 다루는 개념과 규칙입니다. 이 문서는
+객체 지향 문법을 설명하기보다 “규칙을 누가 계산하고 결과를 누가 적용하는가”를
+따라갑니다. [기초 안내](./first-steps.md)의 모병 예시를 떠올리면 좋습니다.
+
+```text
+저장된 장수·도시 → loader → 메모리 세계
+예약한 명령 → 입력 해석 → 조건 검사 → 규칙 계산 → 변경 결과
+변경 결과 → 메모리 세계에 적용 → DB 저장 또는 실패 시 복원
+```
+
 ## World entity
 
 `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를 관리합니다.
+메모리 snapshot과 실패 복원을 관리합니다. 실제 DB transaction은
+`databaseHooks.ts`의 책임입니다. **dirty state**는 마지막 저장 이후 바뀌어 다시
+저장해야 하는 상태를 뜻합니다.
 
 ## Command
 
-장수 command는 `GeneralActionDefinition`으로 다음 계약을 가집니다.
+명령(command)은 “모병” 같은 행동 한 종류입니다. 입력(args)은 병종·수량처럼
+그 행동에 필요한 값입니다. **constraint**는 실행에 필요한 조건이고,
+**state patch**는 병력·자원 등 바꿀 값의 묶음입니다. 실행 결과에는 patch뿐 아니라
+플레이어에게 보일 로그와 후속 효과도 포함됩니다.
+
+장수 command는 definition·command spec·resolver를 통해 다음 계약을 연결합니다.
 
 - key와 사용자 표시 이름
 - raw args parser
@@ -38,25 +55,26 @@ turn 소비와 side effect 계약을 보존합니다.
 priority trigger와 의미 event는 각각 다른 interface를 사용합니다.
 [행동 모듈 프로토콜](../architecture/action-module-protocol.md)을 따라 주세요.
 
-## 주요 클래스
+## 주요 클래스와 함수
 
-| 클래스·함수               | 책임                                               |
-| ------------------------- | -------------------------------------------------- |
-| `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 결과                   |
+| 클래스·함수                   | 책임                                               |
+| ----------------------------- | -------------------------------------------------- |
+| `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, 실패 시 restore                   |
+| `createReservedTurnHandler()` | revision·lease 기반 예약 명령 claim과 실행         |
+| `GeneralActionPipeline`       | action module 계산·trigger·event 실행              |
+| `resolveWarBattle()`          | 전투 phase, RNG, 상태와 log 결과                   |
 
 ## 명령 추가
 
-1. ref command의 예약·실행 constraint, args, RNG, log와 DB mutation을 찾습니다.
+1. 계승 명령이면 Ref의 예약·실행 조건, 입력, RNG, 로그와 DB 변경을 찾습니다.
+   Core 전용 명령이면 요구사항과 의도한 결과를 먼저 정합니다.
 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를 추가합니다.
+5. 정상·실패·경계 fixed-seed test를 추가하고, 계승 계약은 Ref 차등 fixture로 확인합니다.
 6. 생성 command catalog, 상위 mapping과 report를 갱신합니다.