JunkBox apps/chess-api 가이드
업무 개요
- 사용자의 Lichess 대국을 복기해 실력을 키우는 것이 목적임. 종료 대국을 수집하고 Stockfish로 모든 수를 분석한 뒤 사용자가 둔 수에 코칭을 붙임.
- 핵심 개념은 연결 계정(단일 Lichess OAuth 계정), 대국과 수, 엔진 분석, 복기 코칭, 관전 대국(연결 계정이 참가하지 않은 PGN), 실시간 대국임.
- 복기 흐름은 계정 연결, 종료 대국 자동 수집 또는 PGN 업로드, 엔진 분석, AI 복기 요청, 수별 복기 순서임.
- 실시간 대국은 복기와 별개 기능이며 Lichess Board API로 공개 매칭 또는 Lichess AI와 대국함.
- 체스 용어와 필드명 기준은
docs/junkbox/domain/terms-chess.md를 따름.
1. 역할과 책임 경계
apps/chess-api는 Lichess 종료 대국 수집·업로드·Stockfish 분석·복기와 Board API 기반 실시간 대국을 제공하는 FastAPI 앱임.- Lichess OAuth 연결 계정은 하나만 활성화함. 연결 계정으로 공개 매칭 또는 Lichess AI 대국을 생성하고, 상대 수신·착수·무승부·기권을 Lichess Board API로 중계함.
- 종료 대국 동기화의 일정·실행 이력·재시도는
automation-api가 소유하며 Chess 앱에는 자체 polling 또는 scheduler loop가 없음. - 주석 포함 Lichess PGN 파일은 수동 업로드할 수 있음. 연결 계정이 참가하지 않은 PGN은 관전 대국으로 저장함.
- 모든 수의 Stockfish 분석 원본을 저장하고, 연결 계정의 수에만 복기 코칭을 연결함.
- 사용자 요청으로 시작한 AI 복기는 Automation의
chess.ai-review수동 작업으로 실행함. Automation은 실행 이력과 단일 시도 상태를, Chess SQLite는 분석 근거·성공한 코칭·사용량·오류 상태를 소유함. - 인증과 모듈 권한은 Hub JWT/Cookie 및
allowed_modules의CHESS권한을 사용함. - Chess 도메인은 독립 SQLite 파일을 단일 writer로 소유하며 Hub SQLite를 직접 사용하지 않음. OAuth 연결 계정과 대국·분석 데이터는 현재 단일 공유 데이터이며 Hub 사용자 ID로 분리하지 않음.
2. 런타임과 배포
- FastAPI 엔트리포인트는
junkbox_chess_api.main:app임. - 웹 화면은
GET /chess, 상태 확인은GET /health임. - 보호 화면
GET /chess는 Hub JWT의allowed_modules=CHESS를 확인한 뒤 공통base.html앱 셸을 렌더링함. 브랜드 설명은 Hub 포털 Chess APP 메뉴의 표시 가능한description을 사용하며, 설명을 조회할 수 없으면 숨김. 앱 셸은 Chess 모바일 메뉴 드로어와 로그아웃 제어를 제공함. - React 빌드 산출물은
/chess-ui, 공통 자산은/shared-ui로 마운트함. - 로컬 개발 포트는 API
18002, Vite15002임. Vite는/api/chess,/chess,/health,/shared-ui요청을 API로 프록시함. - 컨테이너 내부 포트는
8080이며 Chess SQLite는/app/db/chess.sqlite3을 사용함. - 운영 Chess 공개 origin은
https://c.sleepzz.xyz이며 Hub SQLitetb_portal_menu_m의 ChessAPP메뉴menu_url이 이 주소를 가리킴. 로컬 메뉴는http://localhost:15002를 사용함. junkbox-chessCompose 서비스는JUNKBOX_CHESS_RESTART_POLICY가 비어 있을 때unless-stopped정책으로 기동함. 배포 정책은autoStartOnDeploy=true와restartPolicy=unless-stopped이므로 배포 후 컨테이너를 생성 상태로 남기지 않고 기동함.- 컨테이너는
/sorc001/junkbox/db를/app/db에 마운트하므로 DB 파일은 이미지와 분리되어 영속됨. - Chess 이미지는 Stockfish를 설치하고
CHESS_STOCKFISH_PATH=/usr/games/stockfish를 기본값으로 사용함. 엔진 결과가 없는 대국의 AI 복기는 이 실행 파일을 사용함. - 앱은 HTTP API와 Lichess NDJSON 스트림 중계를 제공함. Chess 전용 runtime YAML, 자체 polling loop, WebSocket 라우트는 사용하지 않음.
2.1 설정과 OAuth
- 공통 Settings는
settings.lichess와settings.modules.chess중첩 모델로 접근함. - Chess 전용 설정은 프로젝트 루트
.env.chess에 둠. Settings는 선택된ENV_FILE과 같은 디렉터리의.env.chess를 읽음. - 주요 설정 키는
LICHESS_BASE_URL,LICHESS_OAUTH_CLIENT_ID,LICHESS_OAUTH_REDIRECT_URI,CHESS_STOCKFISH_PATH,CHESS_STOCKFISH_TIME_LIMIT_SECONDS,CHESS_STOCKFISH_DEPTH,CHESS_STOCKFISH_MULTIPV,CHESS_REVIEW_MAX_COST_USD임. LICHESS_OAUTH_REDIRECT_URI는 기본 Chess OAuth callback URL임.- 로컬 profile에서 검증된 LAN HTTP 또는 Tailnet HTTPS UI 주소로
GET /api/chess/oauth/connect에 접근하면 현재 Chess UI origin의/api/chess/oauth/callback을 redirect URI로 사용함. - 운영 profile에서는
CHESS_BASE_URL에/api/chess/oauth/callback을 붙인 공개 HTTPS URL을 사용하므로.env.chess의 로컬 callback 값을 사용하지 않음. - 이 URI는 PKCE state에 보관되어 토큰 교환 요청에도 동일하게 전달됨.
- 개발 Compose의 Chess 서비스도
.env.chess를 읽기 전용으로 마운트함.
- 로컬 profile에서 검증된 LAN HTTP 또는 Tailnet HTTPS UI 주소로
- 프로젝트 루트의 운영
.env.prod는CHESS_BASE_URL=https://c.sleepzz.xyz를 사용함. 운영 Hub의 로그인 복귀 허용 origin과 Chess의 OAuth callback·페이지 로그인 복귀 URL이 이 설정에 의존하므로 실행 환경의 값도 같은 공개 origin이어야 함. GET /chess보호 화면이 Hub 로그인으로 이동할 때 운영 profile은CHESS_BASE_URL에 요청 path와 query를 결합한 HTTPS 복귀 URL과required_module=CHESS를 전달함. 로컬 profile은 검증된 개발 브라우저 주소를 복귀 URL로 사용함.GET /api/chess/oauth/connect는board:playscope를 요청하는 PKCE authorization-code 흐름을 시작함. 수동 발급 개인 토큰을.env에서 읽지 않음.GET /api/chess/oauth/callback은 code와 state를 검증하고 토큰·계정명·수집 cursor를 SQLite에 저장한 뒤/chess로 이동함.DELETE /api/chess/account는 활성 연결을 해제하며 기존 대국·분석 데이터는 삭제하지 않음.- Lichess 계정·종료 대국 연동은
LichessService, 실시간 Board API 연동은LichessLiveService로 분리함. - access token과 optional refresh token 필드는
tb_lichess_account_m에 저장하며 외부 응답으로 노출하지 않음. 실시간 대국 요청도 연결 계정의 저장된 access token을 사용함. - 재연동 시 같은 계정의 토큰을 갱신하고 기존 완료 대국 수집 cursor를 유지함. 기존 연결에
board:play권한이 없으면 UI의권한 재연동흐름을 사용함.
3. 데이터
tb_lichess_account_m: 단일 OAuth 연결 계정, 토큰, 만료 시각, 수집 cursor, 연결 상태를 저장함.tb_chess_game_m: game id, 사용자명, 내 색상, 상대, 결과, 속도, variant, PGN, 초기·최종 FEN, 대국·등록 시각, 엔진 상태를 저장함. 관전 대국은result='OBSERVED'로 저장함.tb_chess_game_move_n: ply별 SAN, UCI, 착수 전후 FEN, 내 수 여부를 저장함.(game_id, ply)가 유일함.tb_chess_engine_analysis_n: ply별best_score_cp,best_mate_in,actual_score_cp,actual_mate_in,centipawn_loss, 최선 수, principal variation, MultiPV를 저장함.tb_chess_coaching_n: 연결 계정의 수에 대한severity,mistake_type, 한국어 코멘트, 복기 질문, 재복습 여부를 저장함.tb_chess_review_state_m: 대국별 AI 복기 단계·상태·입력 지문·실행 소유권·배치 진행 지점·사용량·오류를 저장함. 배치 처리에 필요한 모델 응답과 기본 코칭으로 채운 착수 번호는draft_json에서 관리함. 기존 형식의 초안은 재검증을 통과한 경우 수동 재요청 시 코칭 행으로 반영함.- Chess 자체 상태·분류 코드인
status,engine_status,coaching_status, 복기 단계·표시 상태,result,opponent_type,severity,mistake_type은 대문자로 저장하고 API에도 대문자로 반환함.- 대국 종료 상태는
FINISHED, 분석 완료 상태는COMPLETED임. - 기존 Chess SQLite의 소문자 코드는 백업 후
apps/chess-api/scripts/migrate_chess_codes_uppercase.py로 이관하며 복기 상태 테이블의 제약·기본값도 함께 갱신함.
- 대국 종료 상태는
- Lichess 응답과 요청 계약의
started,white,black,rapid,standard등은 원래 표기를 유지함.side,speed,variant와 실시간 스트림 상태·진영은 Lichess 계약에 맞춰 해석하고, 외부 요청에도 해당 소문자 값을 사용함. - 모든 자식 테이블은 game id FK와
ON DELETE CASCADE를 사용함. - SQLite 연결은 WAL,
busy_timeout=5000, foreign key pragma를 적용함.AsyncSession은async with경계에서 commit 또는 rollback함.
4. 업무 규칙
4.1 대국 수집·업로드·분석 흐름
OAuth 계정 자동 수집
- Automation의 등록된
chess.game-sync작업이 Chess internal Job API를 호출함. - Chess가 자기 SQLite의 활성 연결 계정과
sync_cursor_ms를 조회하고 Lichess 종료 대국 export API를 호출함. - Lichess game id가 아직 없을 때만 PGN, 게임 메타, 수별 SAN/UCI/FEN을 저장함.
- 저장 후 모든 ply를 Stockfish로 분석하고 엔진 결과를 저장함.
- 분석 상태는
pending,running,completed,failed중 하나임.
- 계정 연결 시 cursor는 현재 시각으로 초기화하므로 과거 대국을 자동 수집하지 않음.
- Chess internal Job API는 Automation caller, service token,
chess.game-syncjob type을 검증함. 일정, claim/lease, timeout, 실행 재시도, idempotency key와 실행 이력은 Automation SQLite의 책임임. - Chess는 자기 DB의 game id 중복 저장을 방지하며 Automation이 Chess SQLite를 직접 읽거나 쓰지 않음.
- 동기화 응답은 가져온 대국 수
fetched와 새 대국이 없었음을 뜻하는noop을 포함함. 계정이 연결되지 않았으면noop임.
수동 PGN 업로드
- 업로드는 주석을 포함한 Lichess PGN만 허용함. 주석은 시계 정보와 Lichess 주석을 보존하는 원본 정책임.
- 파일은
.pgn, UTF-8 또는 UTF-8 BOM, 최대 5MB만 허용함. - 유효한 수순,
White,Black,GameId또는 LichessSite태그가 필요함. GameId또는Site에서 추출한 Lichess game id를 게임 식별자로 사용함. 자동 수집 대국과 수동 업로드 대국은 같은 식별자 기준으로 중복을 거부함.- 연결 계정명이
White또는Black과 일치하면 해당 색을side와is_my_move기준으로 사용함. - 두 선수 모두 연결 계정과 일치하지 않거나 연결 계정이 없으면 관전 대국으로 저장함. 관전 대국은 모든
is_my_move값을 false로 저장하고 복기 코칭 대상에 포함하지 않음. - 업로드 PGN도 수순 저장 트랜잭션이 완료된 뒤 자동 수집 대국과 같은 Stockfish 분석 흐름을 사용함.
엔진 분석과 코칭
- Stockfish는 각 ply의 착수 전
fen_before와 실제 착수 후fen_after를 기준으로 분석함. - 분석 결과는 착수자 관점의 최선·실제 평가, 메이트,
centipawn_loss, 최선 UCI 수, principal variation, MultiPV를 포함함. - Stockfish 기본값은 초급자 복기 기준 수당 1초, 깊이 14, MultiPV 3개이며 환경 변수로 조절함.
- 종료된 표준 대국의 사용자 요청 AI 복기는 엔진 분석이 완료된 연결 계정 수를 최대 8수 단위로 처리함. 엔진 결과가 없으면 별도 단계에서 Stockfish 분석을 완료한 뒤 코칭을 이어감.
- Chess는 FEN·SAN·UCI·엔진 최선 수·PV·평가를 검증함.
CHESS_REVIEW_COACHING라우트는 LiteLLM의openai/z-ai/glm-5.3-flash,reasoning_effort: low, 네이티브 JSON Schema를 사용해 착수별 복습 항목과 근거 ID를 선택함. - 읽을 수 있는 응답은 착수별로 검증하고 통과한 코칭을 먼저 저장함. 같은 배치 실행 안에서 실패한 착수만 사유를 붙여 한 번 다시 요청함. JSON 또는 공통 필드 검증에 실패한 경우 해당 묶음을 한 번 다시 요청함.
- 재요청 실패 또는 모델 호출 한도 도달 시 남은 착수에 Stockfish 기반 기본 코칭을 저장함. 첫 호출의 연동 오류나 저장 실패로 실행이 끝나면 기존 결과를 유지하며 수동 재요청은 누락된 수부터 처리함. 배치 완료 후 Automation이 다음 배치를 실행함.
- 실시간 대국에는 Stockfish 평가·최선 수·PV·복기 코칭을 제공하지 않음. 분석 정보는 종료 대국 복기에서만 제공함.
실시간 Board API 대국
- 진행 중 대국 조회, 계정 이벤트 스트림, 대국별 게임 스트림은 연결 계정의 access token으로 Lichess에 요청함.
GET /api/chess/live/playing은 Lichess/api/account/playing?nb=20을 조회하고nowPlaying배열을 그대로 반환함. 스트림은 NDJSON 줄 단위로 중계하고 빈 keepalive 줄도 전달함. - 공개 매칭은 표준 체스의 래피드·클래시컬·서신 설정을 지원함. 매칭 대기 취소도 Board API로 전달함.
- Lichess AI 대국은 난이도 1~8, 내 진영, 시간 규칙을 선택해 생성함. AI 대국은 레이팅 대국으로 만들지 않음.
- 착수 전 게임 ID와 UCI 형식, 현재 차례, 서버에서 받은 게임 상태,
python-chess의 합법 수를 검사함. 프로모션·캐슬링·앙파상을 포함한 합법 수만 Lichess에 전달하며 동일 게임의 중복 착수 전송을 막음. - 게임의 최종 상태는 Lichess 게임 스트림을 기준으로 갱신함. 무승부 제안·응답과 기권은 Lichess Board API로 전달함.
- 401/403은 계정 권한 재연동이 필요한 상태로, 429는 최소 1분 대기해야 하는 요청 제한으로 응답함. 스트림 재연결과 화면 복구는 Chess UI가 담당함.
4.2 AI 코칭 반영 규칙
- 코칭 선택은 Hub의
CHESS_REVIEW_COACHING_SYSTEM,CHESS_REVIEW_COACHING_USER_TEMPLATE활성 현재 버전을 사용함. 사용자 템플릿의payload변수는 분석 근거 JSON임. 사용 로그에 두 프롬프트 버전을 기록함. - 선택 응답 스키마는 Chess 코드의
selection:2계약임. LLM은 각 착수에 제공된focus와evidence_ref를 짝지어 반환함. 서버는 착수 번호, 중복 여부, 허용된 항목과 근거의 일치를 검사함. engine_status='COMPLETED'게임의is_my_move=1ply 중 코칭 행이 없는 대상만 처리함.- 엔진 원본 데이터와 PGN·FEN을 수정하지 않음.
centipawn_loss, 메이트 정보, 착수 전 최선 수·PV를 severity 판정의 우선 근거로 사용함. severity는BEST,GOOD,INACCURACY,MISTAKE,BLUNDER중 하나임.- 신규
mistake_type은 체크·캡처·위협, 추천 수순 계산, 킹 안전 중 선택함. 수순 계산은 추천 수순에 응수가 있을 때, 킹 안전은 메이트 평가가 있을 때 선택할 수 있음. - 서버는 실제 착수·엔진 추천 수·평가와 선택한 항목을 근거로
comment와reflection_question을 한국어 하십시오체와 문장 끝 마침표로 작성함. - 코칭 행과 기본 코칭 표시 정보를 같은 SQLite 트랜잭션으로 저장함. 배치의 마지막 저장에서 진행 지점을 확정하고 기존
(game_id, ply)행을 보존함. 신규 업무 일시는 offset 없는 KST로 저장함. - 반영 전 대상 수·게임별 ply·엔진 근거·입력 지문을 다시 검증함. Automation의 실행 이력과 재시도 정책은 Chess DB에 복제하지 않음.
5. API와 화면 진입
사용자 화면 API는 require_module("CHESS")를 적용함. OAuth callback은 Lichess redirect 수신 경로이며, Automation internal Job API는 화면 권한 대신 등록된 작업과 서비스 인증을 검증함.
GET /api/chess/account:{ username, connected }반환함.GET /api/chess/oauth/connect: Lichess OAuth authorization URL로 redirect함.GET /api/chess/oauth/callback: OAuth code 교환과 계정 연결을 처리함.DELETE /api/chess/account: 연결 계정을 해제함.POST /api/chess/internal/automation/game-sync: 등록된chess.game-sync작업만 호출하는 종료 대국 동기화 internal Job API임.POST /api/chess/internal/automation/ai-review: 등록된chess.ai-review작업의 배치 실행 internal Job API임.POST /api/chess/games/{game_id}/ai-review:CHESS권한으로 AI 복기를 접수하고 Automation 실행 상태를 반환함.GET /api/chess/games/{game_id}/ai-review: 엔진·코칭 상태, 전체 대상 수와 저장된 코칭 수, 백그라운드 실행·오류 상태 및 수동 재요청 가능 여부를 반환함. 기존 브라우저와의 호환을 위해draft_count=0을 유지함.- 실시간 대국 API는 진행 중 대국 최대 20건 조회, Lichess 이벤트·대국별 게임 NDJSON 스트림, 공개 매칭 시작·취소, AI 대국 생성, UCI 착수, 무승부, 기권을 제공함. 각 요청은 연결 계정 토큰을 사용하며
CHESS권한이 필요한 화면 API임. POST /api/chess/games/upload-pgn: multipartpgn_file을 검증·저장·분석함.{ game_id, engine_status }를 반환함.GET /api/chess/stats/finished-games?from=&to=: 기간 안의FINISHED대국을ended_at의 KST 날짜별로 센[{date, count}]만 반환하는 집계 전용 API임.ended_at이 없는 대국은 제외하고 승패·상대 유형은 구분하지 않으며 대국 상세는 노출하지 않음.CHESS사용자 JWT가 아니라 QuestLog 서비스 인증(X-Junkbox-Service: questlog와QUESTLOG_SERVICE_TOKEN을QUESTLOG_SERVICE_TOKEN_HEADER헤더로 전달)만 허용하므로CHESS권한이 없는 QuestLog 사용자도 집계는 볼 수 있음.- 기간 제한은 시작일 이후 종료일, 최대 400일이며 위반은 422임.
GET /api/chess/game-history?page=&size=: 등록 시각 최신순으로 완료 대국 목록과engine_status를 반환함.GET /api/chess/games/{game_id}: 게임 메타, 원본 PGN, 수순, 수별 엔진 결과, 해당 ply의 코칭 결과를 반환함.- 상세
Move응답은fen_before,fen_after, SAN, UCI, 내 수 여부, 엔진 평가·최선 수·PV, 코칭 필드를 포함함. Stockfish 기반 기본 코칭으로 채운 착수는engine_based_coaching=true로 반환함.
6. 관련 문서
- UI 계약은
docs/junkbox/apps/guide-apps-chess-ui.md를 따름. - 공통 설정·SQLite·인증 규칙은
docs/junkbox/libs/guide-lib-shared-core.md를 따름. - 공통 Chess 스타일 자산은
docs/junkbox/libs/guide-lib-shared-ui.md를 따름. - 프로젝트 전체 구조는
docs/junkbox/common/guide-jb-overview.md, 공통 원칙은docs/junkbox/common/guide-jb-core.md를 따름.