Hide_DandClaude Opus 5
1f21379964
The auction, my page, nation betting and hall of fame roots clipped content that Ref lets overflow, which shifted their measured document size. The dashboard reload controls and the diplomacy table frame now follow Ref's Lumen navigation family and its non-collapsed gray/black frame. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
삼국지 모의전투 HiDCHe core2026
core2026은 ../ref/sam의 PHP 서비스를 TypeScript로 호환 이관하는 pnpm
모노레포입니다. 전투·턴·권한·저장 상태·API·화면 동작은 ref 구현과 실제 실행
결과를 기준으로 검증합니다.
저장소 구성
| 경로 | 책임 |
|---|---|
app/gateway-frontend |
가입, 로그인, 로비, 계정, 관리자 UI |
app/gateway-api |
계정·세션, profile 정책, operation queue, PM2 orchestration |
app/release-controller |
Gateway 전체 릴리스와 controller CLI self-upgrade |
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 |
플레이어 커맨드 문서 생성 |
구조와 실행 흐름은 아키텍처 개요, 파일별 변경
위치는 개발자 핸드북에서 확인해 주세요. ref entry
point와 core 구현의 대응 근거는 상위 작업공간의
../docs/ref-core2026-mapping.md에 있습니다.
런타임 경계
Gateway는 계정과 profile 운영을 소유합니다. gateway-api가 gateway
PostgreSQL과 Redis session을 사용하며, game session token을 발급합니다.
관리 operation은 GatewayProfile과 GatewayOperation에 저장되고
orchestrator가 commit별 worktree와 PM2 process를 조정합니다.
Gateway 자체 릴리스는 Gateway 프로세스 밖의 release-controller가 별도
GatewayReleaseOperation queue를 처리합니다.
각 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의 기준 저장소가 아닙니다.
자세한 흐름은 런타임 아키텍처와 요청·턴·저장 흐름을 확인해 주세요.
도구 체인
- 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
Node.js 버전은 저장소에서 고정하지 않습니다. 의존성 설치와 검증에는
package.json과 pnpm-lock.yaml을 함께 사용해 주세요.
개발 환경
pnpm install --frozen-lockfile
cp .env.example .env
pnpm --filter @sammo-ts/infra prisma:generate
CI=1 pnpm typecheck
.env는 Git에서 제외됩니다. 비밀값은 명령행, 로그, screenshot, report,
VITE_* 변수에 넣지 말아 주세요. 상위 작업공간에서는
../docker_compose_files/development/README.md의 PostgreSQL·Redis stack을
worktree별로 준비할 수 있습니다.
cd ../docker_compose_files/development
./scripts/prepare-instance.sh main 15433 16379 ../../core2026
./scripts/compose.sh main up -d --wait
통합 테스트는 schema를 truncate하거나 Redis key를 정리할 수 있습니다. 다른 worktree나 개발 데이터와 같은 instance를 공유하지 말아 주세요.
검증 명령
pnpm lint
CI=1 pnpm typecheck
pnpm test
pnpm build
pnpm test:integration
PostgreSQL·Redis 조건부 suite는 격리된 서비스를 준비한 뒤 실행합니다.
pnpm test:integration:conditional
ref 명령 계약과 실제 화면은 다음 명령으로 비교합니다.
pnpm check:legacy:general
pnpm check:legacy:nation
pnpm typecheck:e2e:frontend-legacy
pnpm test:e2e:frontend-legacy
pnpm test:e2e:main-front-status-live
pnpm test:e2e:main-records-live
각 명령의 fixture, 서비스, 인증 요구사항은 테스트 정책, 통합 테스트, 프론트엔드 호환 검증에 있습니다. skip된 테스트와 mock 검증은 실제 외부 서비스 검증으로 간주하지 않습니다.
문서
pnpm docs:generate
pnpm docs:dev
pnpm docs:build
pnpm docs:preview
docs:generate는 등록된 장수·국가 command spec에서
docs/user/command-catalog.generated.md를 만듭니다. 생성 파일은 직접
수정하지 말아 주세요.
문서의 시작점은 다음과 같습니다.
DB와 배포
Gateway schema는 packages/infra/prisma/gateway.prisma, game schema는
packages/infra/prisma/game.prisma가 정의합니다. migration은 각각
gateway-migrations/와 migrations/에 있습니다.
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
pnpm migrate:legacy -- --help
Game과 gateway가 같은 database/schema를 쓰므로 deploy 순서는
game → gateway입니다. 양쪽 migration directory 이름은 공유
_prisma_migrations에서 충돌하지 않도록 전역적으로 고유해야 합니다.
활성 외부 prefix는 /gateway/, /che/, /hwe/입니다. 앱은 필요한
listener를 0.0.0.0에 bind하고 prefix를 보존한 frontend, tRPC, SSE,
direct-navigation URL을 사용합니다. /image/*는 외부 Caddy가 소유합니다.
build:server는 profile resource를 dist/<profile>에 복사하는 도구입니다.
완전한 API·daemon·frontend 배포 bundle은 gateway orchestrator의
commit-worktree build 경로에서 구성합니다.
관리자 화면의 DB 유지 배포는 profile의 game migration만 적용하고 현재
게임 DB를 seed하지 않습니다. DB 초기화 배포는 현재 시즌 테이블을 새
시나리오로 교체하지만 hall, ng_games, 연감, 과거 장수·국가와 상속 자료는
보존합니다. Gateway API·frontend·orchestrator는 외부 release-controller가
함께 전환합니다. 설치와 CLI self-upgrade 절차는
app/release-controller/README.md를 확인해
주세요.