Skip to main content

JunkBox apps/raid-api 가이드

1. 애플리케이션 역할​

  • apps/raid-api는 JunkBox의 독립 레이드 운영 백엔드 앱임.
  • 공대원 목록, 공대원 관리, WCL 점수 전체 갱신, 레이드 전용 서버 렌더링 진입점을 담당함.
  • 공통 로그인과 공통 권한 체계를 재사용하면서, 레이드 도메인 데이터와 화면 자산 서빙을 한 앱에서 통합함.
  • 공통 코드와 메타 조회는 hub-api의 내부 master-data API를 통해 수행함.

2. 런타임 구성​

  • FastAPI 애플리케이션 엔트리포인트는 junkbox_raid_api.main:app임.
  • 기본 루트 /는 /raid/members로 리다이렉트됨.
  • 상태 확인 경로는 /health임.
  • OpenAPI 노출 경로는 /docs, /redoc, /openapi.json임.
  • apps/raid-ui/dist를 /raid-ui 경로로 직접 마운트함.
  • libs/shared-ui 산출 자산은 /shared-ui 경로로 직접 마운트함.
  • 앱 favicon은 포털 메뉴의 menu_type_code=APP, icon_type_code=APP_ICON, icon_val 조합에서 raid 앱 아이콘 slug를 해석해 사용하며, 조회 실패 시 raid slug를 fallback으로 사용함.
  • CORS 허용 origin 목록은 shared-core 설정의 server.cors_origins를 공통으로 사용함.

2.1 로컬 개발 서버 연동​

  • raid-api는 18009 포트 기준 백엔드로 실행할 수 있음.
  • apps/raid-ui는 15009 포트 기준 Vite 개발 서버로 실행할 수 있음.
  • 페이지 HTML은 18009가 렌더링하고, React 엔트리와 HMR 자산은 15009/raid-ui/* 경로에서 로드함.

2.2 운영 배포 기준​

  • 운영 컨테이너 기본 포트는 8009임.
  • 운영 이미지는 apps/raid-ui/dist, libs/shared-ui 자산, raid-api 실행 코드를 함께 포함함.
  • 운영 환경변수는 /sorc001/junkbox/env/.env.shared와 /sorc001/junkbox/env/.env.prod를 함께 참조하고, 컨테이너 내부 ENV_FILE=/app/env/.env.prod 기준으로 로딩함.
  • 운영 로그 볼륨은 /logs001/junkbox/raid-api 호스트 경로를 컨테이너 내부 /app/logs에 연결함.
  • 공통 애플리케이션 로그 파일 경로는 /app/logs/app.log임.
  • RAID_BASE_URL, WCL_CLIENT_ID, WCL_CLIENT_SECRET, WCL_TOKEN_URL, WCL_GRAPHQL_URL 설정 정합성이 중요함.

2.3 공통 로깅 초기화​

  • 앱 import 시점에 shared-core의 setup_app_logging()을 호출함.
  • 설정값은 settings.modules.raid.logging에서 읽음.
  • 로그 sink는 콘솔 출력과 파일 출력 두 축으로 동시에 구성됨.

3. 라우팅 구조​

3.1 인증 API​

  • raid-api는 자체 인증 발급 API를 제공하지 않음.
  • 사용자 credential 검증, JWT 발급, logout API는 hub-api가 담당함.
  • raid-api는 shared-core 인증 의존성으로 hub-api가 발급한 JWT를 검증함.

3.2 raid API​

  • GET /api/raid/members
  • POST /api/raid/members/roles
  • POST /api/raid/scores/all
  • GET /api/raid/members/manage
  • POST /api/raid/members/manage
  • POST /api/raid/members/manage/sort
  • DELETE /api/raid/members/manage/{raid_member_id}
  • DELETE /api/raid/members/manage/member/{member_id}

3.3 웹 화면​

  • GET /raid/members
  • GET /raid/members/manage
  • GET /error/403
  • /error/403은 하위 호환 진입점이며 별도 권한 오류 페이지를 렌더링하지 않고 hub-api 로그인 화면의 권한 없음 alert 흐름으로 연결함.

4. 인증 및 권한 흐름​

4.1 토큰 입력 경로​

  • API는 Authorization: Bearer 헤더와 COOKIE_NAME 설정값 기준 HttpOnly 쿠키를 모두 수용함.
  • 현재 기본 쿠키 이름은 JUNKBOX_AUTH임.
  • 인증 해석 우선순위는 Authorization 헤더가 먼저임.

4.2 로그인과 페이지 접근 흐름​

  • 보호 페이지는 강제 인증 구조를 사용함.
  • 비로그인 요청은 hub-api 공통 로그인 화면 /login?redirect=...&required_module=RAID로 리다이렉트됨.
  • 로그인 성공 시 redirect 값이 허용된 경로 또는 허용된 앱 origin이면 해당 위치로 이동함.
  • 요구 모듈 권한이 없으면 hub-api 공통 로그인 화면으로 이동하며 permission_denied=1을 전달함.
  • 공통 로그인 화면은 권한 없음 alert를 한 번 표시하고 URL의 permission_denied 플래그를 제거함.
  • allowed_modules에 RAID가 포함된 사용자만 레이드 화면과 API에 접근할 수 있음.

4.3 슬라이딩 세션 갱신​

  • raid-api는 FastAPI 앱 초기화 시 shared-core의 SlidingSessionMiddleware를 등록함.
  • 브라우저 쿠키 기반 요청은 hub 내부 인증 API를 통해 세션 갱신 필요 여부를 확인함.
  • raid-api의 JSON API와 HTML 페이지 접근 검증은 일반 사용자 JWT에 대해 hub 내부 인증 API의 세션 유효성 검증을 사용함.
  • 세션 갱신 판단과 새 JWT 발급은 hub-api의 POST /api/internal/auth/refresh가 담당함.
  • 만료되었거나 유효하지 않거나 hub에서 revoke된 토큰은 미들웨어가 갱신하지 않으며, 표준 인증 실패 흐름에서 로그인 재진입 또는 JSON 401로 처리됨.

5. 데이터 저장 책임​

5.1 레이드 도메인 저장소​

  • 레이드 도메인은 PostgreSQL raid 스키마를 소스 오브 트루스로 사용함.
  • 공대원 풀은 raid.tb_member_m을 기준으로 관리함.
  • 레이드 메타는 raid.tb_raid_m을 기준으로 관리함.
  • 레이드 소속과 정렬 순서는 raid.tb_raid_member_n을 기준으로 관리함.
  • 보스별 점수와 최근 갱신 시각은 raid.tb_raid_boss_score_n 계열 구조를 기준으로 관리함.
  • 같은 공대원이 여러 레이드에 중복 소속될 수 있음.
  • 삭제 정책은 물리 삭제 기준임.

5.2 공통 master-data 의존 구조​

  • 레이드, 난이도, 역할, 근/원, 직업, 서버, 보스 메타는 hub-api 내부 master-data API를 통해 조회함.
  • 앱 내부에서 공통 코드와 메타를 직접 DB 조회하지 않음.
  • raid-api는 shared-core.masterdata.MasterDataService를 통해 공통 코드와 메타를 조회함.
  • 내부 master-data 조회 결과는 shared-core의 TTL 캐시를 통해 재사용함.

5.3 WCL 연동​

  • WCL 연동은 settings.raid.wcl 설정을 사용함.
  • OAuth 토큰 발급 후 GraphQL API를 호출하는 구조를 사용함.
  • 레이드 화면에서는 페이지 전체 갱신만 지원하며, 개별 행 단건 갱신은 제공하지 않음.
  • 점수 갱신 시 전체 점수와 최근 업데이트 시각을 함께 동기화함.

6. 화면 진입 데이터 구성​

  • 서버 템플릿은 공통 베이스 템플릿과 raid-ui React 마운트 지점을 제공함.
  • 페이지는 page_props.view 값을 통해 members와 manage 화면을 구분함.
  • 초기 props에는 현재 사용자, 레이드 관련 코드 목록, 현재 선택 가능한 필터 목록이 포함됨.
  • 서버 템플릿 문구는 템플릿 또는 라우터 컨텍스트에 한국어 문구로 직접 작성함.
  • 공통코드 라벨과 메타 설정값처럼 데이터 자체가 마스터데이터인 값만 DB 조회 구조를 사용함.

7. API 계약 특성​

  • 두 화면 모두 기본적으로 풀 로딩형 Tabulator 편집 화면을 사용함.
  • 공대원 목록 저장은 역할, 근/원, 참여 여부, 정렬 순서 같은 레이드 소속 정보를 기준으로 처리함.
  • 공대원 관리 저장은 공대원 풀 자체의 생성, 수정, 삭제를 기준으로 처리함.
  • 신규 행 삭제는 프런트 메모리에서만 제거되고, 저장된 행 삭제만 실제 삭제 API를 호출함.
  • 공대원 관리의 일괄 삭제는 선택 체크박스 기반으로 수행함.

8. 배포 및 운영 체크​

  • Docker Compose 서비스명은 junkbox-raid임.
  • GitHub Actions 배포 감지 경로와 서비스 정책에 raid-api, raid-ui, junkbox-raid가 포함됨.
  • 운영 reverse proxy는 RAID_BASE_URL이 8009 컨테이너로 연결되는 전제를 가짐.
  • 점수 갱신 기능을 사용하려면 WCL 인증 환경변수가 모두 채워져 있어야 함.

9. 관련 문서​

  • 프로젝트 전체 구조는 docs/junkbox/common/guide-jb-core.md를 따름.
  • 공통 설정, DB, 인증은 docs/junkbox/libs/guide-lib-shared-core.md를 따름.
  • 공통 UI 자산은 docs/junkbox/libs/guide-lib-shared-ui.md를 따름.
  • 레이드 프런트 구조는 docs/junkbox/apps/guide-apps-raid-ui.md를 따름.