docs: consolidate current architecture documentation
This commit is contained in:
+59
-58
@@ -1,73 +1,74 @@
|
||||
# Integration Tests (Initialization Flow)
|
||||
# 통합 테스트
|
||||
|
||||
This document describes the end-to-end integration test that exercises the
|
||||
gateway, game-api, and game-engine initialization flow.
|
||||
## 실행 명령
|
||||
|
||||
## Scope
|
||||
|
||||
The initialization integration test validates:
|
||||
|
||||
- database reset and schema readiness
|
||||
- bootstrap admin creation
|
||||
- demo user provisioning (10 accounts)
|
||||
- scenario install for `che` with `scenario_2` and 1-minute ticks
|
||||
- deterministic seeding (via env)
|
||||
- auto admin general creation
|
||||
- general creation for demo users with constrained city selection
|
||||
- reserved turn submission (uprising, founding, appointment)
|
||||
- running three turns and validating founding outcomes
|
||||
|
||||
The test runs real Postgres and Redis, and talks to the API servers via tRPC.
|
||||
|
||||
## Files
|
||||
|
||||
- `tools/integration-tests/test/initialization.test.ts`
|
||||
- `tools/integration-tests/vitest.config.ts`
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Postgres and Redis are running and reachable.
|
||||
- `.env.ci` is present at the repo root and contains:
|
||||
- Postgres and Redis connection settings.
|
||||
- `GAME_TOKEN_SECRET`, `KAKAO_REST_KEY`, `KAKAO_REDIRECT_URI`
|
||||
- `GATEWAY_BOOTSTRAP_TOKEN`
|
||||
- `GATEWAY_API_HOST`, `GATEWAY_API_PORT`, `GAME_API_HOST`, `GAME_API_PORT`
|
||||
- `GATEWAY_TRPC_PATH`, `GAME_TRPC_PATH`, `GAME_API_EVENTS_PATH`
|
||||
- `PROFILE=che`, `SCENARIO=2`
|
||||
- `pnpm install` and `pnpm build` have already completed.
|
||||
|
||||
## Safety
|
||||
|
||||
The test truncates the `public` and `che` schemas and flushes Redis. Use a
|
||||
dedicated CI/local database and Redis instance.
|
||||
|
||||
## Running
|
||||
|
||||
Use the root helper script:
|
||||
외부 서비스 없이 실행 가능한 integration:
|
||||
|
||||
```sh
|
||||
pnpm test:integration
|
||||
```
|
||||
|
||||
Or run the package script directly:
|
||||
전용 PostgreSQL·Redis를 사용하는 조건부 suite:
|
||||
|
||||
```sh
|
||||
pnpm --filter @sammo-ts/integration-tests test:integration
|
||||
pnpm test:integration:conditional
|
||||
```
|
||||
|
||||
## Environment Flags
|
||||
조건부 runner는 환경 변수 존재 여부만으로 안전성을 보장하지 않습니다.
|
||||
대상 host, port, database, schema와 Redis prefix가 해당 worktree 전용인지
|
||||
확인해 주세요.
|
||||
|
||||
- `INTEGRATION_WORLD_SEED`: injected into world meta as `hiddenSeed` for
|
||||
deterministic RNG.
|
||||
- `INTEGRATION_JOIN_ALLOW_CITY=true`: allows test-only city selection when
|
||||
creating generals (still restricted to level 5/6 cities).
|
||||
## 준비
|
||||
|
||||
These are loaded from `.env.ci` and can be overridden per run.
|
||||
상위 작업공간의 개발 stack을 사용할 수 있습니다.
|
||||
|
||||
## Notes
|
||||
```sh
|
||||
cd ../docker_compose_files/development
|
||||
./scripts/prepare-instance.sh docs-check 15443 16389 ../../core2026
|
||||
./scripts/compose.sh docs-check up -d --wait
|
||||
|
||||
- `auth.bootstrapLocal` only works when no users exist; the test resets the DB
|
||||
to satisfy this precondition.
|
||||
- `profiles.installNow` seeds the scenario and auto-creates the admin general.
|
||||
- The test runs turn processing via administrator-authorized
|
||||
`turnDaemon.run` and validates founding rules at the third turn.
|
||||
cd ../../core2026
|
||||
pnpm install --frozen-lockfile
|
||||
pnpm --filter @sammo-ts/infra prisma:generate
|
||||
pnpm --filter @sammo-ts/common build
|
||||
pnpm --filter @sammo-ts/logic build
|
||||
pnpm test:integration:conditional
|
||||
```
|
||||
|
||||
Instance 이름과 port는 다른 worktree와 겹치지 않게 정합니다. 생성된 `.env`,
|
||||
`.env.ci`, log와 DB volume은 Git에 추가하지 않습니다.
|
||||
|
||||
## 범위
|
||||
|
||||
통합 suite는 다음 경계를 포함합니다.
|
||||
|
||||
- gateway/game Prisma 연결과 schema
|
||||
- Redis session, queue와 pub/sub
|
||||
- scenario initialization과 profile schema
|
||||
- `InputEvent` 원자성, 재시도와 중복 request
|
||||
- turn daemon lease, heartbeat, fencing과 takeover
|
||||
- 예약 턴 revision/CAS와 API/daemon 경합
|
||||
- auth header, role, sanction과 owner별 HTTP transport
|
||||
- ref/core command snapshot, RNG trace와 persistence
|
||||
- auction, tournament와 worker transaction
|
||||
|
||||
실제 포함 suite는 `tools/run-conditional-integration.sh`, 각 package의
|
||||
`package.json`, `*.integration.test.ts`를 기준으로 확인합니다.
|
||||
|
||||
## 안전 경계
|
||||
|
||||
- Test는 game schema table을 truncate할 수 있습니다.
|
||||
- Redis key 또는 선택한 DB index를 정리할 수 있습니다.
|
||||
- 운영·공유 DB URL을 사용하지 않습니다.
|
||||
- Volume 삭제는 사용자가 데이터 폐기를 명시한 경우에만 수행합니다.
|
||||
- Secret과 펼쳐진 `docker compose config` 출력은 report나 artifact에 넣지
|
||||
않습니다.
|
||||
|
||||
## 결과 해석
|
||||
|
||||
환경이 없어 skip된 test는 실행되지 않은 것입니다. Mock connector test는 실제
|
||||
PostgreSQL·Redis 경계를 증명하지 않습니다. Full suite 실패는 변경 worktree와
|
||||
변경 없는 `main`에서 각각 재현해 회귀와 baseline을 구분합니다.
|
||||
|
||||
Ref 호환성 판정은 [차등 검증](architecture/turn-state-differential-testing.md),
|
||||
UI는 [프론트엔드 호환 검증](frontend-legacy-parity.md)을 함께 사용합니다.
|
||||
|
||||
Reference in New Issue
Block a user