From 027225081d074e493a51d9e42a7aa38a39fe72b5 Mon Sep 17 00:00:00 2001 From: hided62 Date: Thu, 30 Jul 2026 14:15:47 +0000 Subject: [PATCH] docs: consolidate current architecture documentation --- AGENTS.md | 7 +- README.md | 272 ++---- docs/.vitepress/config.mts | 7 +- docs/architecture/action-module-protocol.md | 6 +- docs/architecture/game-frontend-spa-plan.md | 165 ---- .../general-command-differential-testing.md | 779 ------------------ docs/architecture/legacy-commands.md | 136 --- docs/architecture/legacy-engine-ai.md | 209 ----- docs/architecture/legacy-engine-auction.md | 106 --- docs/architecture/legacy-engine-city.md | 48 -- docs/architecture/legacy-engine-constants.md | 60 -- .../architecture/legacy-engine-constraints.md | 62 -- docs/architecture/legacy-engine-diplomacy.md | 55 -- docs/architecture/legacy-engine-economy.md | 89 -- docs/architecture/legacy-engine-events.md | 150 ---- docs/architecture/legacy-engine-execution.md | 135 --- docs/architecture/legacy-engine-general.md | 103 --- docs/architecture/legacy-engine-items.md | 78 -- docs/architecture/legacy-engine-logging.md | 36 - docs/architecture/legacy-engine-pools.md | 43 - docs/architecture/legacy-engine-server-env.md | 25 - docs/architecture/legacy-engine-triggers.md | 226 ----- docs/architecture/legacy-engine-war.md | 199 ----- docs/architecture/legacy-engine.md | 59 -- docs/architecture/legacy-entities.md | 432 ---------- docs/architecture/legacy-inherit-points.md | 161 ---- docs/architecture/legacy-scenarios.md | 139 ---- .../npc-unification-memory-profile.md | 101 --- docs/architecture/overview.md | 140 ++-- docs/architecture/postgres-schema.md | 306 ------- docs/architecture/rewrite-constraints.md | 106 --- docs/architecture/rewrite-plan.md | 55 -- docs/architecture/runtime.md | 357 ++------ docs/architecture/scenario-composition.md | 14 +- docs/architecture/todo.md | 152 ---- docs/architecture/turn-daemon-lifecycle.md | 338 -------- .../turn-state-differential-testing.md | 294 ++----- docs/architecture/typescript-version.md | 66 +- docs/command-log-checklist.md | 50 -- docs/developer/code-map.md | 109 ++- docs/developer/domain-and-classes.md | 140 ++-- docs/developer/index.md | 49 +- docs/developer/request-turn-persistence.md | 146 ++-- docs/developer/system-architecture.md | 100 --- docs/e2e-caddy-routing.md | 194 ++--- docs/e2e-orchestrator-tests.md | 199 ++--- docs/frontend-css-architecture.md | 4 +- docs/frontend-legacy-parity.md | 6 +- docs/index.md | 36 +- docs/integration-tests.md | 117 +-- docs/legacy-db-migration.md | 15 +- docs/reference-baseline.md | 39 - docs/test-suite-audit.md | 161 ---- docs/testing-policy.md | 160 ++-- packages/infra/prisma/migrations/README.md | 46 +- tools/legacy-db-migration/README.md | 6 +- 56 files changed, 924 insertions(+), 6369 deletions(-) delete mode 100644 docs/architecture/game-frontend-spa-plan.md delete mode 100644 docs/architecture/general-command-differential-testing.md delete mode 100644 docs/architecture/legacy-commands.md delete mode 100644 docs/architecture/legacy-engine-ai.md delete mode 100644 docs/architecture/legacy-engine-auction.md delete mode 100644 docs/architecture/legacy-engine-city.md delete mode 100644 docs/architecture/legacy-engine-constants.md delete mode 100644 docs/architecture/legacy-engine-constraints.md delete mode 100644 docs/architecture/legacy-engine-diplomacy.md delete mode 100644 docs/architecture/legacy-engine-economy.md delete mode 100644 docs/architecture/legacy-engine-events.md delete mode 100644 docs/architecture/legacy-engine-execution.md delete mode 100644 docs/architecture/legacy-engine-general.md delete mode 100644 docs/architecture/legacy-engine-items.md delete mode 100644 docs/architecture/legacy-engine-logging.md delete mode 100644 docs/architecture/legacy-engine-pools.md delete mode 100644 docs/architecture/legacy-engine-server-env.md delete mode 100644 docs/architecture/legacy-engine-triggers.md delete mode 100644 docs/architecture/legacy-engine-war.md delete mode 100644 docs/architecture/legacy-engine.md delete mode 100644 docs/architecture/legacy-entities.md delete mode 100644 docs/architecture/legacy-inherit-points.md delete mode 100644 docs/architecture/legacy-scenarios.md delete mode 100644 docs/architecture/npc-unification-memory-profile.md delete mode 100644 docs/architecture/postgres-schema.md delete mode 100644 docs/architecture/rewrite-constraints.md delete mode 100644 docs/architecture/rewrite-plan.md delete mode 100644 docs/architecture/todo.md delete mode 100644 docs/architecture/turn-daemon-lifecycle.md delete mode 100644 docs/command-log-checklist.md delete mode 100644 docs/developer/system-architecture.md delete mode 100644 docs/reference-baseline.md delete mode 100644 docs/test-suite-audit.md diff --git a/AGENTS.md b/AGENTS.md index a90a690..830a552 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,8 +37,9 @@ commit 또는 삭제를 하지 말아 주세요. ## 완료 상태를 해석하는 법 -2026-07-27의 백엔드 누락 감사에서는 현재 `main`에서 재현 가능한 구체적 -미구현·미병합 항목을 찾지 못했습니다. 이를 “이관 전체 완료”로 해석하지 말아 주세요. +이관 상태는 현재 `main`의 코드, Git ancestry, 실행 경로와 ref 비교로 +판정해 주세요. 기능 목록이나 report의 완료 표현만으로 전체 이관이 끝났다고 +판정하지 말아 주세요. - 새 차등 fixture가 mismatch를 드러내면 다시 제품 결함으로 분류해 주세요. - green unit test는 ref 호환, 실제 DB transaction, Chromium geometry 또는 @@ -160,7 +161,7 @@ API request - 전투·명령·월간 action의 호출, state patch, 로그와 RNG 소비 순서를 리팩터링 편의로 바꾸지 말아 주세요. -게임 난수는 기존 `packages/common/src/util/LiteHashDRBG.ts`, `RNG.ts`, +게임 난수는 `packages/common/src/util/LiteHashDRBG.ts`, `RNG.ts`, `RandUtil.ts` 흐름을 사용해 주세요. `Math.random()` 같은 임의 경로를 gameplay에 추가하지 말아 주세요. 후보가 하나뿐인 선택, 실패 분기, fallback에서도 ref가 소비하는 RNG call을 생략하지 말아 주세요. diff --git a/README.md b/README.md index 8843bf6..3dd6c2e 100644 --- a/README.md +++ b/README.md @@ -1,81 +1,65 @@ -# 삼국지 모의전투 HiDCHe — core2026 +# 삼국지 모의전투 HiDCHe core2026 -`core2026`은 삼국지 모의전투 HiDCHe(삼모/삼모전/힏체섭)의 PHP 서비스를 -TypeScript로 호환 이관하는 pnpm 모노레포입니다. 기준 구현은 이 저장소 안의 -`legacy/`가 아니라 작업공간의 `../ref/sam`이며, 제품 동작·저장 상태·화면은 -그 기준과 실제 실행 결과를 대조합니다. +`core2026`은 `../ref/sam`의 PHP 서비스를 TypeScript로 호환 이관하는 pnpm +모노레포입니다. 전투·턴·권한·저장 상태·API·화면 동작은 ref 구현과 실제 실행 +결과를 기준으로 검증합니다. -## 현재 상태 +## 저장소 구성 -2026-07-27의 `main` 기준으로 gateway, game API/프론트엔드, turn daemon과 -주요 게임 명령·월간 이벤트가 구현되어 있습니다. 최근 백엔드 누락 감사에서 -재현 가능한 구체적 미구현 또는 미병합 항목은 남지 않았지만, 이것이 전체 -호환성이나 운영 준비 완료를 뜻하지는 않습니다. +| 경로 | 책임 | +| ------------------------------ | -------------------------------------------------------------- | +| `app/gateway-frontend` | 가입, 로그인, 로비, 계정, 관리자 UI | +| `app/gateway-api` | 계정·세션, profile 정책, operation queue, PM2 orchestration | +| `app/game-frontend` | profile별 게임 SPA와 ref 호환 화면 | +| `app/game-api` | tRPC, SSE, 인증, 조회·입력 API, 비동기 worker | +| `app/game-engine` | turn daemon, AI, 월간 lifecycle, in-memory world와 DB flush | +| `packages/common` | 공통 타입, 직렬화, 인증 token, 결정적 RNG | +| `packages/logic` | 명령, constraint, 전투, trait·item·병종 action module | +| `packages/infra` | gateway/game Prisma schema, migration, PostgreSQL·Redis client | +| `packages/tools-scripts` | resource schema 생성과 검증 | +| `resources` | scenario, map, unit set, turn-command profile | +| `tools/integration-tests` | PostgreSQL·Redis 및 ref↔core 차등 검증 | +| `tools/frontend-legacy-parity` | Chromium 기반 화면·상호작용 비교 | +| `tools/legacy-db-migration` | 레거시 장기보존 데이터 이관 CLI | +| `tools/docs` | 플레이어 커맨드 문서 생성 | -현재 열린 경계는 주로 다음과 같습니다. +구조와 실행 흐름은 [아키텍처 개요](docs/architecture/overview.md), 파일별 변경 +위치는 [개발자 핸드북](docs/developer/index.md)에서 확인해 주세요. ref entry +point와 core 구현의 대응 근거는 상위 작업공간의 +`../docs/ref-core2026-mapping.md`에 있습니다. -- 아직 fixture가 없는 명령 실패값·조합과 live 출병 조합의 차등 범위 확대 -- 실제 배포 profile에서 worker의 장시간 소비, 재시작, host/firewall 장애 검증 -- 인증 fixture가 필요한 화면과 남은 페이지의 Chromium 룩앤필 비교 -- 외부 Caddy의 `/gateway/`, `/che/`, `/hwe/` 경로에서 tRPC, SSE, 자산, - 새로고침과 로그인 인계의 반복 검증 -- 운영 DB 이관 전 backup/restore, maintenance mode와 dry-run count 재확인 +## 런타임 경계 -테스트가 통과했다는 사실만으로 PHP 기준과의 호환성이 증명되지는 않습니다. -기능별 근거와 남은 범위는 작업공간의 `../docs/ref-core2026-mapping.md`와 -`../report/`를 함께 확인해 주세요. +Gateway는 계정과 profile 운영을 소유합니다. `gateway-api`가 gateway +PostgreSQL과 Redis session을 사용하며, game session token을 발급합니다. +관리 operation은 `GatewayProfile`과 `GatewayOperation`에 저장되고 +orchestrator가 commit별 worktree와 PM2 process를 조정합니다. -## 구성 +각 game profile은 별도 PostgreSQL schema를 사용합니다. `game-api`는 인증된 +요청을 검증하고 직접 처리할 mutation 또는 daemon 입력을 +`InputEvent`에 기록합니다. `game-engine`은 DB lease와 fencing token을 확보한 +단일 실행자로서 world를 메모리에 적재하고, 명령·월간 이벤트·로그·예약 턴과 +input-event 결과를 transaction으로 반영합니다. Redis pub/sub과 SSE는 알림 +경로이며 gameplay commit의 기준 저장소가 아닙니다. -| 경로 | 역할 | -| ------------------------------ | ------------------------------------------------- | -| `app/gateway-frontend` | 가입·로그인, 로비, 계정과 관리자 운영 UI | -| `app/gateway-api` | 계정·세션·profile 정책과 PM2 운영 orchestration | -| `app/game-frontend` | 게임 SPA와 ref 룩앤필 호환 화면 | -| `app/game-api` | profile별 tRPC/SSE, 조회·입력 API와 비동기 worker | -| `app/game-engine` | 턴 scheduler/daemon, 월간 처리와 DB flush | -| `packages/common` | 공통 타입, 직렬화, 결정적 RNG와 유틸리티 | -| `packages/logic` | 전투·명령·월간 action과 typed action module 로직 | -| `packages/infra` | game/gateway Prisma schema, migration과 client | -| `packages/tools-scripts` | resource schema 생성·검증 도구 | -| `tools/integration-tests` | PostgreSQL/Redis 및 ref↔core 통합·차등 테스트 | -| `tools/frontend-legacy-parity` | 실제 Chromium 기반 화면·상호작용 비교 | -| `tools/legacy-db-migration` | 레거시 장기보존 데이터 CLI 이관 | -| `tools/docs` | 플레이어 커맨드 문서 자동 생성 | -| `resources/scenario` | 시나리오 본문과 조합 가능한 이벤트·규칙 확장 | -| `docs` | VitePress 핸드북과 런타임·테스트·운영 문서 | - -런타임의 영속 입력은 PostgreSQL `input_event`가 담당합니다. game API가 -요청을 기록하고 turn daemon이 claim한 뒤, 게임 상태·로그·예약 턴·결과와 -event 완료를 transaction으로 commit합니다. Redis는 session, realtime fan-out, -battle simulation 등 해당 기능의 계약에만 사용하며 게임 mutation의 영속 -성공 여부를 대신하지 않습니다. 자세한 흐름은 -[`docs/architecture/runtime.md`](docs/architecture/runtime.md)와 -[`docs/architecture/turn-daemon-lifecycle.md`](docs/architecture/turn-daemon-lifecycle.md)에 -있습니다. - -장수 특기·관직·병종·계승·아이템 효과는 -[`docs/architecture/action-module-protocol.md`](docs/architecture/action-module-protocol.md)의 -계산 hook, 우선순위 trigger, 닫힌 의미 이벤트 경계를 따릅니다. 제품용 -action stack은 ref의 소유권 순서를 brand한 `loadActionModuleBundle()`에서만 -조립합니다. +자세한 흐름은 [런타임 아키텍처](docs/architecture/runtime.md)와 +[요청·턴·저장 흐름](docs/developer/request-turn-persistence.md)을 확인해 +주세요. ## 도구 체인 -- pnpm workspace와 Turbo -- TypeScript `6.0.2` 고정 -- Node.js + Fastify + tRPC + zod -- Vue 3 + Pinia + Vue Router + Vite -- PostgreSQL + Prisma, Redis -- Vitest와 Playwright/Chromium -- VitePress 정적 HTML 문서 사이트 +- pnpm `11.17.0`, Turbo +- TypeScript `6.0.2` +- Fastify, tRPC, zod +- Vue 3, Pinia, Vue Router, Vite +- PostgreSQL, Prisma, Redis +- Vitest, Playwright/Chromium +- VitePress -package manager 버전은 루트 `package.json`의 `packageManager`를 따릅니다. -현재 값은 `pnpm@11.17.0`입니다. 저장소는 Node `engines`를 고정하지 않으므로 -개발 호스트의 임의 버전을 README 계약으로 간주하지 말고, lockfile 설치와 -전체 검증 결과로 호환성을 확인해 주세요. +Node.js 버전은 저장소에서 고정하지 않습니다. 의존성 설치와 검증에는 +`package.json`과 `pnpm-lock.yaml`을 함께 사용해 주세요. -## 로컬 시작 +## 개발 환경 ```sh pnpm install --frozen-lockfile @@ -84,53 +68,37 @@ pnpm --filter @sammo-ts/infra prisma:generate CI=1 pnpm typecheck ``` -`.env`는 Git에서 제외됩니다. `.env.example`의 placeholder를 실제 비밀값으로 -바꾸되 secret을 커밋, 명령행, 로그, 스크린샷 또는 `VITE_*` 변수에 넣지 -말아 주세요. - -PostgreSQL과 Redis가 필요합니다. 전체 `sam_rebuild` 작업공간에서는 -`../docker_compose_files/development/README.md`의 worktree별 격리 stack을 -사용할 수 있습니다. standalone checkout이라면 `.env.example` 계약에 맞는 -별도 PostgreSQL/Redis를 준비해 주세요. - -작업공간 helper를 사용하는 기본 예시는 다음과 같습니다. +`.env`는 Git에서 제외됩니다. 비밀값은 명령행, 로그, screenshot, report, +`VITE_*` 변수에 넣지 말아 주세요. 상위 작업공간에서는 +`../docker_compose_files/development/README.md`의 PostgreSQL·Redis stack을 +worktree별로 준비할 수 있습니다. ```sh cd ../docker_compose_files/development ./scripts/prepare-instance.sh main 15433 16379 ../../core2026 ./scripts/compose.sh main up -d --wait - -cd ../../core2026 -pnpm --filter @sammo-ts/infra prisma:generate -pnpm test:integration ``` -`prepare-instance.sh`는 ignored `.env`와 `.env.ci`를 생성합니다. 통합 테스트는 -schema를 truncate하거나 Redis를 비울 수 있으므로 다른 worktree나 개발 -데이터와 DB/Redis instance를 공유하지 말아 주세요. volume 삭제는 명시적으로 -데이터 폐기를 결정한 경우에만 수행해 주세요. +통합 테스트는 schema를 truncate하거나 Redis key를 정리할 수 있습니다. 다른 +worktree나 개발 데이터와 같은 instance를 공유하지 말아 주세요. -## 자주 쓰는 명령 +## 검증 명령 ```sh pnpm lint -pnpm test CI=1 pnpm typecheck +pnpm test pnpm build -pnpm dev +pnpm test:integration ``` -`pnpm test`의 일부 PostgreSQL/Redis 테스트는 전용 환경 변수가 없으면 -의도적으로 skip됩니다. 외부 서비스가 필요한 경계까지 실행하려면 격리된 -instance를 준비한 뒤 다음을 사용해 주세요. +PostgreSQL·Redis 조건부 suite는 격리된 서비스를 준비한 뒤 실행합니다. ```sh -pnpm test:integration pnpm test:integration:conditional ``` -레거시 명령의 정적 계약과 실제 Chromium 화면 비교는 각각 다음 entry -point를 사용해 주세요. +ref 명령 계약과 실제 화면은 다음 명령으로 비교합니다. ```sh pnpm check:legacy:general @@ -138,113 +106,53 @@ pnpm check:legacy:nation pnpm test:e2e:frontend-legacy ``` -이 명령들은 ref checkout, fixture, 로그인 상태 또는 별도 서비스가 필요할 -수 있습니다. 실행 조건과 coverage는 -[`docs/integration-tests.md`](docs/integration-tests.md)와 -[`docs/frontend-legacy-parity.md`](docs/frontend-legacy-parity.md)를 따라 주세요. +각 명령의 fixture, 서비스, 인증 요구사항은 +[테스트 정책](docs/testing-policy.md), +[통합 테스트](docs/integration-tests.md), +[프론트엔드 호환 검증](docs/frontend-legacy-parity.md)에 있습니다. skip된 +테스트와 mock 검증은 실제 외부 서비스 검증으로 간주하지 않습니다. -프론트엔드나 개별 서비스만 실행할 때는 workspace filter를 사용해 주세요. - -```sh -pnpm --filter @sammo-ts/gateway-frontend dev -pnpm --filter @sammo-ts/gateway-api dev -pnpm --filter @sammo-ts/game-frontend dev -pnpm --filter @sammo-ts/game-api dev -pnpm --filter @sammo-ts/game-engine dev -``` - -## 문서 사이트 - -개발자 아키텍처·파일 흐름·핵심 클래스와 플레이어 커맨드·시기별 가이드는 -[`docs/index.md`](docs/index.md)에서 시작합니다. VitePress 개발 서버와 정적 HTML -빌드는 다음 명령으로 실행합니다. +## 문서 ```sh +pnpm docs:generate pnpm docs:dev pnpm docs:build pnpm docs:preview ``` -`docs:dev`와 `docs:build`는 먼저 `pnpm docs:generate`를 실행합니다. 이 단계는 -현재 장수·국가 명령 등록부와 각 `commandSpec`에서 -`docs/user/command-catalog.generated.md`를 다시 만듭니다. 생성 파일을 직접 -수정하지 말고 명령 정의나 생성기를 고쳐 주세요. 정적 HTML은 -`docs/.vitepress/dist`에 생성되며 Git에서 제외됩니다. +`docs:generate`는 등록된 장수·국가 command spec에서 +`docs/user/command-catalog.generated.md`를 만듭니다. 생성 파일은 직접 +수정하지 말아 주세요. -핸드북이 조사한 코드 기준은 -[`docs/reference-baseline.md`](docs/reference-baseline.md)에 고정해 두었습니다. -기능 리팩터링 뒤에는 기준 commit부터 현재 commit까지의 diff를 대조하고 관련 -페이지, 생성 목록과 기준선을 같은 변경에서 갱신해 주세요. +문서의 시작점은 다음과 같습니다. -## DB schema와 migration +- [core2026 핸드북](docs/index.md) +- [개발자 핸드북](docs/developer/index.md) +- [플레이어 가이드](docs/user/index.md) +- [아키텍처 개요](docs/architecture/overview.md) +- [런타임 아키텍처](docs/architecture/runtime.md) +- [차등 검증](docs/architecture/turn-state-differential-testing.md) +- [Caddy prefix 계약](docs/e2e-caddy-routing.md) +- [레거시 DB 이관](docs/legacy-db-migration.md) -Gateway는 기본적으로 PostgreSQL `public` schema를 사용하고, 게임은 -`PROFILE`별 schema를 사용합니다. +## DB와 배포 + +Gateway schema는 `packages/infra/prisma/gateway.prisma`, game schema는 +`packages/infra/prisma/game.prisma`가 정의합니다. migration은 각각 +`gateway-migrations/`와 `migrations/`에 있습니다. ```sh pnpm --filter @sammo-ts/infra prisma:migrate:status:game pnpm --filter @sammo-ts/infra prisma:migrate:deploy:game pnpm --filter @sammo-ts/infra prisma:migrate:deploy:gateway -``` - -새 영속 필드는 Prisma schema와 migration만 추가해서 끝내지 말아 주세요. runtime -model/type, loader, transaction flush와 실제 PostgreSQL 검증까지 연결해 주세요. -기존 migration 파일이나 checksum을 고치지 말아 주세요. - -레거시 장기보존 데이터 이관은 HTTP 기능이 아닌 CLI입니다. 기본 동작은 -dry-run이며 실제 쓰기에는 `--apply`가 필요합니다. - -```sh pnpm migrate:legacy -- --help ``` -현재 기수의 `general`, `city`, `nation`, queue, 시장, 메시지 등은 이관 -범위가 아닙니다. 운영 적용 절차와 table별 범위는 -[`docs/legacy-db-migration.md`](docs/legacy-db-migration.md)와 -[`tools/legacy-db-migration/README.md`](tools/legacy-db-migration/README.md)를 -따라 주세요. +활성 외부 prefix는 `/gateway/`, `/che/`, `/hwe/`입니다. 앱은 필요한 +listener를 `0.0.0.0`에 bind하고 prefix를 보존한 frontend, tRPC, SSE, +direct-navigation URL을 사용합니다. `/image/*`는 외부 Caddy가 소유합니다. -## 배포 경로와 자산 - -현재 외부 계약의 활성 경로는 gateway `/gateway/`, game `/che/`와 `/hwe/`입니다. -프론트 build와 API는 같은 prefix의 tRPC/SSE/direct navigation 계약을 -지켜야 합니다. `/image/*`는 외부 Caddy가 별도 파일 시스템에서 제공하므로 앱이 -rewrite하거나 복제하지 말아 주세요. - -`kwe`, `twe`, `nya`, `pya`, `pwe` 같은 profile 이름이 코드나 계획 문서에 -존재하더라도 외부 route가 활성화됐다는 뜻은 아닙니다. 실제 포트와 build-time -환경 변수는 [`docs/e2e-caddy-routing.md`](docs/e2e-caddy-routing.md)를 -현재 인프라와 다시 대조해 주세요. - -루트의 `build:server` 스크립트는 현재 profile resource를 `dist/`로 -복사하기 위한 placeholder이며, API·daemon·frontend의 완전한 배포 bundle을 -만들지 않습니다. 운영 build는 gateway operation/orchestrator와 profile별 -worktree 흐름을 사용합니다. - -## 호환성 원칙 - -- 전투 결과, 판정·반올림·정렬과 RNG 소비 순서를 최우선으로 보존합니다. -- actor와 archive owner는 인증 session에서 서버가 결정합니다. client가 보낸 - general ID나 owner 값을 권한 근거로 신뢰하지 않습니다. -- gameplay 난수는 `packages/common/src/util/LiteHashDRBG.ts`, - `RNG.ts`, `RandUtil.ts`의 기존 흐름을 사용합니다. -- ref와 같은 viewport, Chromium, font, image, 로그인 fixture에서 geometry와 - hover/focus/active/disabled 상태를 비교합니다. -- 동일한 CSS class 이름만으로 page별 layout을 합치지 않습니다. 공통 token과 - shell의 기준은 [`docs/frontend-css-architecture.md`](docs/frontend-css-architecture.md)입니다. -- mock/local E2E 성공과 외부 Caddy·운영 데이터 검증을 구분합니다. - -## 핵심 문서 - -- [core2026 핸드북](docs/index.md) -- [문서 기준 커밋](docs/reference-baseline.md) -- [개발자 핸드북](docs/developer/index.md) -- [플레이어 가이드](docs/user/index.md) -- [테스트 정책](docs/testing-policy.md) -- [테스트 suite 감사](docs/test-suite-audit.md) -- [통합 테스트](docs/integration-tests.md) -- [프론트엔드 ref 호환 검증](docs/frontend-legacy-parity.md) -- [Caddy prefix E2E](docs/e2e-caddy-routing.md) -- [레거시 DB 이관](docs/legacy-db-migration.md) -- [TypeScript 버전 정책](docs/architecture/typescript-version.md) -- [저장소 작업 지침](AGENTS.md) +`build:server`는 profile resource를 `dist/`에 복사하는 도구입니다. +완전한 API·daemon·frontend 배포 bundle은 gateway orchestrator의 +commit-worktree build 경로에서 구성합니다. diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index dcca0db..87159fc 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -12,7 +12,7 @@ export default defineConfig({ nav: [ { text: '개발자', link: '/developer/' }, { text: '플레이어', link: '/user/' }, - { text: '기준 커밋', link: '/reference-baseline' }, + { text: '아키텍처', link: '/architecture/overview' }, ], sidebar: { '/developer/': [ @@ -20,7 +20,8 @@ export default defineConfig({ text: '개발자 핸드북', items: [ { text: '시작하기', link: '/developer/' }, - { text: '시스템 아키텍처', link: '/developer/system-architecture' }, + { text: '아키텍처 개요', link: '/architecture/overview' }, + { text: '런타임 아키텍처', link: '/architecture/runtime' }, { text: '요청·턴·저장 흐름', link: '/developer/request-turn-persistence' }, { text: '도메인 로직과 핵심 클래스', link: '/developer/domain-and-classes' }, { text: '파일 지도와 변경 절차', link: '/developer/code-map' }, @@ -55,7 +56,7 @@ export default defineConfig({ text: '마지막 변경', }, footer: { - message: '현재 구현을 설명하는 문서입니다. 기준 커밋과 검증 범위를 함께 확인해 주세요.', + message: '현재 구현을 설명하는 문서입니다. 코드와 검증 범위를 함께 확인해 주세요.', }, }, }); diff --git a/docs/architecture/action-module-protocol.md b/docs/architecture/action-module-protocol.md index cdf097d..8ff2b95 100644 --- a/docs/architecture/action-module-protocol.md +++ b/docs/architecture/action-module-protocol.md @@ -1,7 +1,7 @@ # 장수 행동 모듈 프로토콜 -`packages/logic/src/actionModules/`는 ref의 `iAction`을 그대로 복사한 범용 -interface가 아니라, 실제 core2026 실행 경계만 타입으로 표현합니다. 계산 +`packages/logic/src/actionModules/`는 core2026 실행 경계를 타입으로 +표현합니다. 계산 hook, 우선순위 trigger, 의미 이벤트는 서로 다른 실행 계약입니다. ## 세 가지 실행 계약 @@ -61,7 +61,7 @@ source입니다. 현재 이벤트는 장비 구매·판매, 계략 성공, 도 ## 저장과 RNG 경계 의미 이벤트는 producer가 가진 객체를 동기적으로 수정합니다. producer는 -이벤트 전후의 ref mutation 순서를 그대로 유지한 뒤 기존 effect/flush +이벤트 전후의 ref mutation 순서를 유지한 뒤 effect/flush 경계에 결과를 전달합니다. - 장비 판매는 판매 대금 반영 → 판매 이벤트 → 슬롯 제거 순서입니다. diff --git a/docs/architecture/game-frontend-spa-plan.md b/docs/architecture/game-frontend-spa-plan.md deleted file mode 100644 index 3c8d199..0000000 --- a/docs/architecture/game-frontend-spa-plan.md +++ /dev/null @@ -1,165 +0,0 @@ -# Game Frontend SPA Plan - -이 문서는 `app/game-frontend`를 Vue 3 + Pinia + Vue Router 기반 SPA로 구축하기 위한 -지속 사용 가능한 작업 플랜이다. 레거시 화면(`legacy/hwe`)과 문서(`docs/`)를 기준으로 -화면 목록, 인증/권한 분기, 데이터 계약을 정리하고 단계별 구현 순서를 정의한다. - -## Goals - -- 레거시 화면과 정보 제공 범위를 보존하면서 SPA로 재구성한다. -- 인증 상태별 정보 공개 범위를 엄격히 분리한다. -- API 통신은 tRPC로 통일하고, 추후 SSE 실시간 업데이트 경로를 고려한다. -- UI/레이아웃은 레거시와 유사하게 유지하되, 정보 구조는 SPA에 맞게 재배치 가능. - -## Reference Sources - -- Legacy view entrypoints: `legacy/hwe/{b_,v_,a_,index}*.php` -- Legacy Vue/TS sources: `legacy/hwe/ts/`, `legacy/hwe/ts/components/` -- Docs: `docs/architecture/overview.md`, `docs/architecture/rewrite-plan.md`, - `docs/architecture/runtime.md`, `docs/architecture/legacy-engine*.md` - -## User State Matrix - -- Public (미로그인/장수 미생성): 공개 정보만 노출 - - 레거시 기준: 10분 캐시 지도 + 동향(최소 정보) -- Authed (로그인 + 장수 생성): 대부분의 정보 접근 허용 -- Admin/GM: 운영자 전용 화면 및 도구 (후순위) - -## Legacy Screen Inventory (Route 후보) - -정확한 데이터 흐름/권한은 각 PHP 엔트리포인트와 연관 TS 컴포넌트에서 확인한다. - -- `legacy/hwe/index.php` -- `legacy/hwe/v_cachedMap.php` -- `legacy/hwe/v_join.php` -- `legacy/hwe/v_processing.php` -- `legacy/hwe/v_board.php` -- `legacy/hwe/v_history.php` -- `legacy/hwe/v_vote.php` -- `legacy/hwe/v_auction.php` -- `legacy/hwe/v_battleCenter.php` -- `legacy/hwe/v_chiefCenter.php` -- `legacy/hwe/v_globalDiplomacy.php` -- `legacy/hwe/v_inheritPoint.php` -- `legacy/hwe/v_NPCControl.php` -- `legacy/hwe/v_nationBetting.php` -- `legacy/hwe/v_nationGeneral.php` -- `legacy/hwe/v_nationStratFinan.php` -- `legacy/hwe/v_troop.php` -- `legacy/hwe/a_bestGeneral.php` -- `legacy/hwe/a_emperior.php` -- `legacy/hwe/a_emperior_detail.php` -- `legacy/hwe/a_genList.php` -- `legacy/hwe/a_hallOfFame.php` -- `legacy/hwe/a_kingdomList.php` -- `legacy/hwe/a_npcList.php` -- `legacy/hwe/a_traffic.php` -- `legacy/hwe/b_betting.php` -- `legacy/hwe/b_currentCity.php` -- `legacy/hwe/b_genList.php` -- `legacy/hwe/b_myBossInfo.php` -- `legacy/hwe/b_myCityInfo.php` -- `legacy/hwe/b_myGenInfo.php` -- `legacy/hwe/b_myKingdomInfo.php` -- `legacy/hwe/b_myPage.php` -- `legacy/hwe/b_tournament.php` - -## Architecture Decisions (SPA) - -- Vue 3 + `