merge: 최신 main을 0.1.0 사전점검에 통합

docs/admin-console.md

@@ -76,6 +76,11 @@ Gateway 관리자 콘솔은 `/gateway/admin`에서 시작합니다. 공개 로
   메타가 없거나 유효하지 않으면 기존 시스템 기본값을 사용합니다. 시나리오와
   예약·가오픈·정식 오픈 시각은 매 실행마다 선택하므로 서버 기본값에 포함하지
   않습니다.
+- 서버 상태의 `다음 시즌 번호`는 위 리셋 옵션과 별도의
+  `GatewayProfile.meta.nextSeasonIdx`이며 0 이상의 정수를 허용합니다. 이벤트
+  기수는 0을 저장한 뒤 RESET하고, 이벤트 종료 뒤 정상 기수 번호를 다시 저장한
+  다음 RESET합니다. 빈 값은 강제 번호를 해제하여 기존 게임의 season 또는 신규
+  기본값 1을 사용한다는 뜻입니다.
 - 같은 화면의 `실행 중 게임 옵션`은 리셋 기본값과 별개로 현재 기수 DB의 턴
   간격, 장수 생성 제한, 유저 자동턴 제한·동작을 읽어 표시합니다. 세 값은
   `admin.profiles.runtime:<name>` 권한과 3자 이상의 사유가 있을 때 하나의
@@ -96,7 +101,7 @@ Gateway 관리자 콘솔은 `/gateway/admin`에서 시작합니다. 공개 로
 | `admin.profiles.settings:<name>` | 표시 정보·리셋 기본 옵션·Kakao 미인증 접근/장수 생성 유예 |
 | `admin.profiles.deploy:<name>`   | DB를 유지하는 Git 버전 업데이트, 초기화와 새 버전 결합    |
 | `admin.scenarios.reset:<name>`   | 현재 배포 버전으로 시나리오 초기화                        |
-| `admin.games.cancel:<name>`      | 진행 게임 취소, 기록 옵션과 유산 포인트 보전율 확정        |
+| `admin.games.cancel:<name>`      | 진행 게임 취소, 기록 옵션과 유산 포인트 보전율 확정       |
 | `admin.reset.schedule:<name>`    | 허용된 시나리오 초기화를 미래 시각에 예약                 |
 | `admin.releases.manage`          | profile과 분리된 Gateway control plane 배포·rollback      |
 

docs/index.md

@@ -35,6 +35,8 @@ features:
 [시간과 턴](./user/time-and-turns.md)과
 [커맨드 목록](./user/command-catalog.generated.md)을 확인해 주세요. Profile과
 Gateway 배포는 [릴리스 운영 매뉴얼](./release-operations.md)을 따라 주세요.
+[Gateway와 게임 공통 메뉴 설정](./runtime-navigation.md)은 코드 재빌드 없이
+상단 링크와 dropdown을 바꾸는 JSON 형식과 복구 경계를 설명합니다.
 관리자 화면의 메뉴와 권한·운영 경계는
 [관리자 콘솔](./admin-console.md)에서 확인할 수 있습니다.
 게임 진행 시각과 운영 벽시계의 경계는

docs/runtime-navigation.md

@@ -0,0 +1,59 @@
+# Gateway와 게임 공통 메뉴 설정
+
+Gateway 상단 메뉴와 profile 게임 화면의 공통 메뉴는 하나의 JSON 설정을
+공유합니다. 저장소 기본값은 `resources/navigation.json`이고 운영 runtime은
+`CORE_NAVIGATION_CONFIG_FILE`이 가리키는 파일을 우선합니다. Docker 운영 구성의
+기본 경로는 영속 volume 안의 `/srv/data/navigation.json`입니다.
+
+## 반영 경계
+
+`GET /gateway/api/navigation`과 `navigation.get`은 인증 없이 현재 파일을 요청마다
+읽고 schema를 검증합니다.
+Gateway와 게임 frontend는 화면을 처음 열 때 이를 조회하므로 JSON을 저장한 뒤
+브라우저를 새로고침하면 frontend 재빌드나 profile DB 초기화 없이 반영됩니다.
+이미 열린 화면을 서버가 강제로 바꾸지는 않습니다.
+
+운영 파일이 아직 없으면 저장소 기본값을 사용합니다. Docker entrypoint는 최초
+기동 때만 저장소 기본값을 영속 경로로 복사하고, 이미 존재하는 운영 파일은 배포나
+container 재생성 때 덮어쓰지 않습니다. 파일을 읽을 수 없거나 schema가 틀리면
+API는 오류를 반환하고 frontend는 빌드에 포함된 안전한 기본 메뉴를 표시합니다.
+
+## 편집 형식
+
+최상위 `version`은 현재 `1`입니다.
+
+- `gateway.brand`: Gateway 브랜드 문구와 내부 `to`
+- `gateway.items`: `id`, `label`, `href`, 선택적인 `newTab`
+- `game.items`: `link`, `group`, `split` 항목
+- `link`: `to`, `href`, `action` 가운데 정확히 하나만 사용
+- `divider`: dropdown 구분선이며 고유한 `id`만 사용
+- `showWhen: npc-enabled`: NPC 모드에서만 노출
+- `highlightWhen: nation-betting|vote`: 해당 실시간 상태일 때 기존 강조색 적용
+- `action: show-version`: 현재 지원하는 유일한 로컬 동작으로 버전 정보 dialog 표시
+
+`to`는 profile base path를 보존하는 Vue Router 내부 경로입니다. `/xe`, `/wiki`
+같이 Caddy가 소유한 외부 경로는 `href`를 사용합니다. URL은 `/`, `//`,
+`https://`, `http://`로 시작하는 값만 허용하며 `javascript:` 같은 실행 URL은
+거부합니다. 브라우저 식별과 자동 검증에 쓰이는 `id`는 영문 소문자, 숫자와
+하이픈만 사용합니다.
+
+## 운영 변경과 복구
+
+1. `/srv/data/navigation.json`을 별도 위치에 복사해 되돌릴 파일을 확보합니다.
+2. 임시 파일에서 편집하고 `jq empty`로 JSON 문법을 확인합니다.
+3. 임시 파일을 운영 경로로 같은 filesystem 안에서 교체합니다.
+4. `GET /gateway/api/navigation`이 성공하는지 확인합니다.
+5. Gateway desktop/mobile과 실제 profile 화면을 새로고침해 순서, 링크,
+   dropdown과 hover/focus를 확인합니다.
+
+API 검증이 실패하면 직전 복사본을 원래 경로로 되돌립니다. 저장소 기본값으로
+완전히 복구하려면 현재 배포 commit의 `resources/navigation.json`을 운영 경로에
+복사합니다. 이 작업은 PostgreSQL, Redis, profile release나 현재 시즌을 변경하지
+않습니다.
+
+개발 검증은 다음 명령을 사용합니다.
+
+```sh
+pnpm --filter @sammo-ts/gateway-api test -- runtimeNavigationConfig.test.ts
+pnpm --filter @sammo-ts/gateway-frontend test:e2e:operations --grep 'Gateway 상단 메뉴|Gateway 모바일|JSON 응답'
+```