From e2111b1168d62f7cff3bd3c37faf11b8c0cfa034 Mon Sep 17 00:00:00 2001 From: hided62 Date: Tue, 18 Aug 2026 13:30:49 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=EA=B2=8C=EC=9E=84=20=EC=B7=A8=EC=86=8C?= =?UTF-8?q?=20=EC=9A=B4=EC=98=81=20=EA=B2=BD=EA=B3=84=20=EB=AC=B8=EC=84=9C?= =?UTF-8?q?=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 전용 권한, 선택 가능한 기록 정책, 유산 정산식, CANCELLED 상태와 실패·재시도 운영 절차를 관리자·릴리스 문서에 기록한다. --- README.md | 2 +- docs/admin-console.md | 22 ++++++++++++++++++++++ docs/release-operations.md | 28 ++++++++++++++++++++++++++++ 3 files changed, 51 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4b77a2a3..3222a540 100644 --- a/README.md +++ b/README.md @@ -236,7 +236,7 @@ source map 제거 사유가 아니며, 별도의 보안 요구와 검토가 있 각 서버의 `버전 업데이트`는 profile의 game migration만 적용하고 현재 게임 DB를 seed하지 않습니다. 별도 `시나리오 초기화`는 Git 업데이트 없이 현재 게시 commit을 기본으로 사용하며, 필요할 때만 새 버전 배포와 결합합니다. -상태 설정·버전 업데이트·시나리오 초기화는 서버별 상단 탭으로 이동하며, +상태 설정·버전 업데이트·시나리오 초기화·게임 취소는 서버별 상단 탭으로 이동하며, 버전/초기화 화면은 URL에 고정된 profile을 다시 선택하거나 전체 profile 상태를 기다리지 않습니다. 초기화는 현재 시즌 테이블을 새 시나리오로 교체하지만 `hall`, `ng_games`, 연감, 과거 장수·국가와 상속 자료는 diff --git a/docs/admin-console.md b/docs/admin-console.md index 9d9b8f45..0374a1ea 100644 --- a/docs/admin-console.md +++ b/docs/admin-console.md @@ -16,6 +16,7 @@ Gateway 관리자 콘솔은 `/gateway/admin`에서 시작합니다. 공개 로 | 서버 상태·설정 | `/gateway/admin/servers/:profileName` | 해당 profile의 공개 정보, 계정 정책, 실행 상태와 게임 운영 동작 | | 버전 업데이트 | `/gateway/admin/servers/:profileName/version` | 현 DB를 보존하는 profile 코드·migration 배포 | | 시나리오 초기화 | `/gateway/admin/servers/:profileName/scenario` | 현재 배포 버전 또는 새 버전으로 현 시즌 DB와 시나리오 교체 | +| 게임 취소 | `/gateway/admin/servers/:profileName/cancel` | 잘못 연 게임을 닫고 기록·유산 포인트를 취소 정책에 따라 원자적으로 정산 | | Gateway 릴리스 | `/gateway/admin/releases` | Gateway control plane 배포와 rollback | | 공지 · 접속 | `/gateway/admin/system` | 로비 공지와 관리자 세션 연결 | | 감사 로그 | `/gateway/admin/audit` | 관리자 조치 결과, 대상과 사유 조회 | @@ -45,6 +46,20 @@ Gateway 관리자 콘솔은 `/gateway/admin`에서 시작합니다. 공개 로 중단되어도 관리자 capability와 서버 메뉴를 함께 기다리게 하지 않습니다. - `DEPLOY`는 현재 game DB를 유지하고 migration/build를 적용합니다. `RESET`은 현재 시즌 데이터를 새 시나리오로 교체하며 장기 보존 자료를 유지합니다. +- `CANCEL_GAME`은 `RESET`과 다른 비가역 운영 작업입니다. `PREOPEN`, `RUNNING`, + `PAUSED` 게임만 요청할 수 있고, migration 준비 후 profile process를 정지한 + 다음 한 DB transaction에서 기록과 유산 포인트를 정산합니다. 성공한 profile은 + 사용자 접근·턴 진행·운영자 재개가 모두 금지된 `CANCELLED`가 되며, 다시 + 사용하려면 새 시나리오 초기화가 필요합니다. +- 취소 화면에서 기수 이력은 `버려진 게임`으로 남기거나 `ng_games` 행을 실제 + 삭제할 수 있습니다. 플레이 장수의 `OldGeneral` 기록도 독립적으로 보존·삭제할 + 수 있습니다. 버려진 기록은 원래 season을 감사 자료에만 보관하고 과거 플레이 + 화면에서는 정식 기수 번호·왕조·승자 기록으로 표시하지 않습니다. +- 유산 포인트는 게임 오픈 시점(또는 기존 게임의 첫 활동 시점) 원금을 먼저 + 고정합니다. 취소 시 게임 중 지출과 현재 잔액에 의존하지 않고 + `오픈 원금 + floor(게임 중 획득분 × 보전율 / 100)`으로 정산합니다. 따라서 + 지출분은 항상 전액 돌아오며 신규·복귀 지급과 게임 중 보상도 관리자가 고른 + 0~100% 보전율의 적용 대상입니다. - 시나리오 초기화는 기본적으로 서버에 현재 게시된 commit을 사용하므로 Git 업데이트가 필요하지 않습니다. 새 branch/commit과 함께 초기화하려면 초기화 권한과 버전 배포 권한이 모두 필요합니다. @@ -79,6 +94,7 @@ Gateway 관리자 콘솔은 `/gateway/admin`에서 시작합니다. 공개 로 | `admin.profiles.settings:` | 표시 정보·리셋 기본 옵션·Kakao 미인증 접근/장수 생성 유예 | | `admin.profiles.deploy:` | DB를 유지하는 Git 버전 업데이트, 초기화와 새 버전 결합 | | `admin.scenarios.reset:` | 현재 배포 버전으로 시나리오 초기화 | +| `admin.games.cancel:` | 진행 게임 취소, 기록 옵션과 유산 포인트 보전율 확정 | | `admin.reset.schedule:` | 허용된 시나리오 초기화를 미래 시각에 예약 | | `admin.releases.manage` | profile과 분리된 Gateway control plane 배포·rollback | @@ -86,6 +102,12 @@ Gateway 관리자 콘솔은 `/gateway/admin`에서 시작합니다. 공개 로 다른 metadata action이어서 제거했습니다. 초기화와 예약은 시나리오 초기화 탭의 `GatewayOperation(type=RESET)`만 사용합니다. +`admin.games.cancel`은 `admin.profiles.runtime`, `admin.scenarios.reset`이나 +기존 운영자 role에 포함되는 포괄 권한이 아닙니다. capability catalog의 별도 +`CRITICAL` 권한이며 superuser 또는 명시적으로 범위를 받은 최고관리자만 사용합니다. +브라우저의 확인 입력과 confirm은 오조작 방지 UI이고, 실제 경계는 Gateway API의 +capability 검사와 orchestrator의 상태·lease 검사입니다. + ## Kakao 없는 특수 계정 접근 운영자 role(`superuser`, `admin`, `admin.*`)은 별도 grant 없이 모든 game diff --git a/docs/release-operations.md b/docs/release-operations.md index ca78de0b..03dc8033 100644 --- a/docs/release-operations.md +++ b/docs/release-operations.md @@ -125,6 +125,32 @@ table 부재로 실패하지 않습니다. 현 시즌의 장수, 초기화 작업은 되돌릴 수 있는 앱 rollback과 다릅니다. 운영 DB backup과 새 scenario 설정을 확인한 뒤 실행해 주세요. +### 잘못 연 게임 취소 + +게임 취소는 새 시즌을 만드는 `RESET`도, 코드를 되돌리는 release rollback도 +아닙니다. `/gateway/admin/servers/:profileName/cancel`에서 별도 +`admin.games.cancel:` 권한으로만 요청합니다. 대상은 `PREOPEN`, `RUNNING`, +`PAUSED` 상태여야 하며 이력 보존/삭제, 플레이 장수 기록 보존/삭제, 게임 중 획득한 +유산 포인트의 보전율(기본 0%)과 5자 이상의 사유를 확정해야 합니다. + +Orchestrator는 Gateway에 게시된 현재 commit을 고정하고 해당 commit의 build와 +game migration을 준비합니다. 그 뒤 profile을 `STOPPED`로 fence하고 process를 +내린 다음 게임 schema advisory lock과 단일 transaction 안에서 다음을 수행합니다. + +- 오픈 원금에 관리자가 고른 획득분 보전율을 적용해 참가자별 유산 포인트 정산 +- `ng_games`를 `ABANDONED`로 남기거나 삭제하고, 원래 기수·시나리오·사유·정산표는 + `game_cancellation` 감사 행에 보존 +- 선택에 따라 현재/사망 장수의 과거 기록을 `OldGeneral`로 보존하거나 모두 삭제 +- 명예의 전당, 과거 국가, 황제, 연감, 통일 finalization·상속 결과처럼 정식 완료를 + 뜻하는 파생 자료 삭제 +- `world_state`를 취소 표시하고 profile을 재개 불가능한 `CANCELLED`로 전환 + +Transaction 전 실패하면 원래 profile 상태와 process 복구를 시도합니다. 정산 +transaction이 commit된 뒤에는 실패한 작업을 재개해 게임을 다시 열지 않습니다. +동일 operation ID와 server ID는 중복 정산되지 않으며, 실패·재시도 기록은 Gateway +operation log와 `game_cancellation`에 남습니다. 취소 후에는 새 시나리오 초기화로만 +profile을 다시 사용하세요. + ### Profile 실패와 재시도 Build는 현재 runtime을 멈추기 전에 수행합니다. Migration 또는 새 process @@ -297,6 +323,8 @@ schema head·component 검사는 그대로 수행합니다. 확인합니다. - 시나리오 초기화에서는 새 시즌 상태와 명예의 전당·연감 등 장기보존 자료를 함께 확인합니다. +- 게임 취소에서는 profile이 `CANCELLED`이고 process가 정지됐는지, 취소 이력과 + 장수 기록 옵션, 참가자별 원금·획득·보전·최종 포인트가 요청과 같은지 확인합니다. Local unit, 격리 DB integration과 fixture Chromium 통과는 운영 PM2, 외부 Caddy/HTTPS, 방화벽과 실제 운영 DB 전환을 증명하지 않습니다. 운영 배포에서는