Skip to main content

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, Vite 15002임. Vite는 /api/chess, /chess, /health, /shared-ui 요청을 API로 프록시함.
  • 컨테이너 내부 포트는 8080이며 Chess SQLite는 /app/db/chess.sqlite3을 사용함.
  • 운영 Chess 공개 origin은 https://c.sleepzz.xyz이며 Hub SQLite tb_portal_menu_m의 Chess APP 메뉴 menu_url이 이 주소를 가리킴. 로컬 메뉴는 http://localhost:15002를 사용함.
  • junkbox-chess Compose 서비스는 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를 읽기 전용으로 마운트함.
  • 프로젝트 루트의 운영 .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:play scope를 요청하는 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 계정 자동 수집​

  1. Automation의 등록된 chess.game-sync 작업이 Chess internal Job API를 호출함.
  2. Chess가 자기 SQLite의 활성 연결 계정과 sync_cursor_ms를 조회하고 Lichess 종료 대국 export API를 호출함.
  3. Lichess game id가 아직 없을 때만 PGN, 게임 메타, 수별 SAN/UCI/FEN을 저장함.
  4. 저장 후 모든 ply를 Stockfish로 분석하고 엔진 결과를 저장함.
  5. 분석 상태는 pending, running, completed, failed 중 하나임.
  • 계정 연결 시 cursor는 현재 시각으로 초기화하므로 과거 대국을 자동 수집하지 않음.
  • Chess internal Job API는 Automation caller, service token, chess.game-sync job 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 또는 Lichess Site 태그가 필요함.
  • 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=1 ply 중 코칭 행이 없는 대상만 처리함.
  • 엔진 원본 데이터와 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: multipart pgn_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를 따름.