본문으로 건너뛰기

JunkBox apps/wow-api 가이드

업무 개요​

  • WoW 레이드 공대 운영을 돕는 앱이며 세 기능으로 구성됨.
    • 공대원 관리: 공대원 목록과 레이드별 배치를 관리하고 Warcraft Logs(WCL) 점수를 갱신함.
    • 함께한 공대원: 등록 캐릭터의 WCL 보스 처치 기록에서 같이 레이드한 상대를 집계해 검색함.
    • 공대 구인 알림: 구인 게시글을 수집해 AI로 분석하고 사용자 프로필과 매칭되면 메시지로 알림.
  • 핵심 개념은 레이드, 멤버 풀과 레이드별 배치, 멤버 구분(나·추적·공대원), WCL 점수, 구인 프로필의 모집 자리 조건과 글 제외 검색어임.
  • 예약 실행은 Automation, 메시지 전달은 Message가 담당하고 WoW 앱은 수집·분석·매칭·발송 조건을 소유함.

1. 역할과 책임 경계​

  • apps/wow-api는 JunkBox의 독립 WoW 서비스 백엔드 앱임.
  • 공대원 목록, 공대원 관리, WCL 점수 전체 갱신, 함께한 공대원 기록 수집·검색, 공대 구인 알림 수집·분석·매칭, WoW 앱 서버 렌더링 진입점을 담당함.
  • 공통 로그인과 공통 권한 체계를 재사용하면서, 레이드 도메인 데이터와 화면 자산 서빙을 한 앱에서 통합함.
  • 공통 코드와 메타 조회는 hub-api의 내부 master-data API를 통해 수행함.
  • 앱 식별자와 권한 코드는 WOW, 화면에 표시하는 서비스명은 WoW, 상단 브랜드 약칭은 WW임. 포털 메뉴의 운영 URL은 https://wow.sleepzz.xyz, 아이콘 slug는 wow임.

2. 런타임과 배포​

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

2.1 로컬 개발 서버 연동​

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

2.2 운영 배포 기준​

  • 운영 컨테이너 내부 포트는 8080임. 규칙은 운영 컨테이너 포트 통일 규칙을 따름.
  • 운영 이미지는 apps/wow-ui/dist, libs/shared-ui 자산, wow-api 실행 코드를 함께 포함함.
  • 운영 환경변수는 /sorc001/junkbox/env/.env.shared와 /sorc001/junkbox/env/.env.prod를 함께 참조하고, 컨테이너 내부 ENV_FILE=/app/env/.env.prod 기준으로 로딩함.
  • 운영과 개발 Compose는 호스트 /sorc001/junkbox/db를 컨테이너 /app/db에 마운트함.
  • 컨테이너의 WOW_DATABASE_URL은 sqlite+aiosqlite:////app/db/wow.sqlite3임.
  • 운영 로그 볼륨은 /logs001/junkbox/wow-api 호스트 경로를 컨테이너 내부 /app/logs에 연결함.
  • 공통 애플리케이션 로그 파일 경로는 /app/logs/app.log임.
  • WOW_RECRUITMENT_NOTIFICATION_OWNER_USER_ID는 구인 알림 Message 이력의 소유자 사용자 ID이며 선택값임.
  • 공대 구인 분석은 AI 라우팅 파일을 읽으므로 운영·개발 Compose는 MASTER_DATA_DIR, AI_ROUTING_YAML_PATH를 지정하고 라우팅 파일을 컨테이너 /app/var/master-data/ai-routing.yml에 읽기 전용으로 마운트함. 경로 규칙은 common/guide-jb-dev-ops.md를 따름.
  • 구인 알림 발송은 Message internal API를 호출하므로 Compose가 MESSAGE_BASE_URL(http://junkbox-message:8080)을 지정하고 junkbox-message에 의존함. 이 값이 없으면 기본값 http://localhost:18004가 컨테이너 안에서 닿지 않음.
  • WOW_BASE_URL, WOW_DATABASE_URL, WCL_CLIENT_ID, WCL_CLIENT_SECRET, WCL_TOKEN_URL, WCL_API_URL 설정 정합성이 중요함.
  • 운영 WOW_BASE_URL은 https://wow.sleepzz.xyz이며, 로그인 복귀 URL은 이 origin과 요청 경로를 조합해 생성함.

2.3 공통 로깅 초기화​

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

2.4 WOW 앱 SQLite engine 초기화​

  • 앱 import 시점에 shared-core의 create_async_engine(settings.modules.wow.database_url)를 호출하여 WOW 앱 전용 SQLite engine을 초기화함.
  • 로컬 비컨테이너 기본 WOW_DATABASE_URL은 sqlite+aiosqlite:////sorc001/junkbox/db/wow.sqlite3임.
  • SQLite 연결은 DB 파일의 부모 경로를 준비하고 PRAGMA journal_mode=WAL, PRAGMA busy_timeout=5000, PRAGMA foreign_keys=ON을 적용함.
  • WOW 앱 SQLite의 단일 writer는 wow-api임. 다른 앱은 이 파일을 직접 write하지 않음.

2.5 배포 및 운영 체크​

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

3. 인증과 권한​

3.1 토큰 입력 경로​

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

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

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

3.3 슬라이딩 세션 갱신​

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

4. 데이터​

4.1 레이드 도메인 저장소​

  • 레이드 도메인의 소스 오브 트루스는 /sorc001/junkbox/db/wow.sqlite3 SQLite 파일임.

  • 컨테이너 내부 표준 경로는 /app/db/wow.sqlite3임.

  • WOW_DATABASE_URL은 WOW 앱의 레이드 도메인 DB 연결에만 사용하며 WOW 런타임은 전역 DATABASE_URL을 사용하지 않음.

  • tb_raid_* 테이블과 raid_id 같은 컬럼은 레이드 기능의 데이터 계약이므로 wow.sqlite3 안에서 그대로 사용함.

  • 공대원 풀은 tb_member_m을 기준으로 관리함.

  • tb_member_m.member_category_code는 공대원 구분 코드이며 기본값은 RAID_MEMBER임. 구분은 레이드별 배치가 아닌 공대원 풀 속성이므로 한 캐릭터의 구분은 모든 레이드 소속에 공통 적용됨.

  • 레이드 소속과 정렬 순서는 tb_raid_member_n을 기준으로 관리함.

  • 난이도별 레이드 전체 점수는 tb_raid_member_raid_score_n을 사용함.

  • 보스별 점수와 최근 갱신 시각은 tb_raid_member_boss_score_n을 사용함.

  • 레이드, 난이도, 보스 메타는 WOW 앱 SQLite에 복제하지 않고 hub-api internal master-data API 계약으로 조회함.

  • tb_raid_member_raid_score_n의 PK는 (raid_member_id, raid_id, difficulty_code)임.

  • tb_raid_member_boss_score_n의 PK는 (raid_member_id, boss_id, difficulty_code)임.

  • SQLite 파일 간 또는 Hub 데이터에 대한 DB 레벨 FK를 전제로 하지 않음.

  • 같은 공대원이 여러 레이드에 중복 소속될 수 있음.

  • 앱 시작 시 공대원 구분 컬럼이 없는 기존 WOW 앱 SQLite에 member_category_code를 추가하고 기존 행을 RAID_MEMBER로 보정하는 멱등 스키마 보정이 수행됨.

  • 삭제 정책은 물리 삭제 기준임.

  • WOW 앱 데이터는 Hub 로그인 사용자별로 분리하지 않으며 WOW module 권한이 있는 모든 사용자가 같은 공대원·점수·등록 캐릭터·구인 프로필을 사용함. tb_member_m과 tb_raid_member_n에는 created_by·updated_by 감사 컬럼을 두지 않음.

  • 함께한 공대원 기능은 캐릭터, 수집 중간 상태, 레이드 이름, 처치 집계 테이블을 WOW 앱 SQLite에 멱등 생성함. 자세한 저장 계약은 4.7절을 따름.

4.2 공통 master-data 의존 구조​

  • 레이드, 난이도, 역할, 근/원, 직업, 서버, 보스 메타는 hub-api 내부 master-data API를 통해 조회함.
  • 공대원 구분은 RAID_MEMBER_CATEGORY 공통코드를 사용하며, 활성 코드의 sort_order_no가 목록·관리 선택지의 표시 순서임.
  • SERVER.attribute01은 wow-check 서버 식별자, SERVER.attribute02는 Warcraft Logs URL 서버 slug, SERVER.attribute03은 Warcraft Logs region 값으로 사용함.
  • 앱 내부에서 공통 코드와 메타를 직접 DB 조회하지 않음.
  • wow-api는 shared-core.masterdata.MasterDataService를 통해 공통 코드와 메타를 조회함.
  • 내부 master-data 조회 결과는 shared-core의 TTL 캐시를 통해 재사용함.

4.3 WCL 연동​

  • WCL 연동은 settings.wow.wcl 설정을 사용함.
  • OAuth 토큰 발급 후 GraphQL API를 호출하는 구조를 사용함.
  • 레이드 화면에서는 페이지 전체 갱신만 지원하며, 개별 행 단건 갱신은 제공하지 않음.
  • 점수 갱신은 현재 레이드의 전체 멤버 집합을 대상으로 하며 공대원 구분으로 갱신 대상을 제외하지 않음.
  • 점수 갱신은 복합 PK로 기존 점수 row를 조회한 뒤 생성 또는 갱신하여 전체 점수, 보스별 점수, 최근 업데이트 시각을 함께 동기화함.
  • 점수 생성·갱신 시각은 KST(UTC+9) 기준 timezone 없는 datetime으로 WOW 앱 SQLite에 저장함. 목록 응답의 전체 최근 업데이트 시각은 선택 레이드·난이도의 tb_raid_member_raid_score_n.updated_at 또는 created_at 최댓값을 변환 없이 문자열로 반환함.

4.4 공대 구인 알림 저장소와 수집 범위​

  • 공대 구인 알림은 와우 인벤 파티찾기 게시판의 고정 원본 https://www.inven.co.kr/board/wow/2972 중 [레이드] 분류만 대상으로 함. 수집은 분류 필터(category=레이드) 목록을 사용함.
  • 원본 URL, CSS selector, 전송 webhook은 프로필에서 변경하지 않음.
  • 수집은 목록을 최신 페이지부터 최대 3페이지까지 읽고, 페이지의 가장 오래된 글이 이미 저장된 글이면 멈춤. 일부만 처리된 페이지는 다음 페이지까지 읽어 회차 상한으로 남은 글을 빠짐없이 이어 처리함. 저장되지 않은 글만 신규 글로 처리함.
  • 목록에서 레이드 글을 하나도 찾지 못하면 페이지 구조 변경으로 보고 오류로 종료해 Automation 실행 이력에 실패로 남김.
  • 신규 글은 본문 영역(#powerbbsContent)만 추가 요청함. 댓글, 이미지, 첨부 파일은 수집하지 않음.
  • 본문은 분석 요청이 끝날 때까지 메모리에만 존재하며 DB, AI 사용량 로그 입력 파라미터, Telegram 메시지에 저장하지 않음.
  • tb_raid_recruitment_profile_m은 제목·활성 여부·요일·주간 횟수·가능 시간대와 찾을 모집 자리(wanted_slot_terms_json), 제외할 모집 자리(excluded_slot_terms_json), 글 제외 검색어(excluded_post_terms_json)를 저장함. 수집 주기와 알림 시간은 전역 설정임.
  • 프로필은 Hub 로그인 사용자에 귀속되지 않는 앱 전역 데이터임. 프로필 제목은 식별용 이름이며 자동 기본값을 두지 않음. 직업, 역할, 전문화, 프리셋, 자동 검색어 설정은 프로필 모델과 저장소에 존재하지 않음.
  • tb_raid_recruitment_post_n은 원본 게시글 번호, URL, 제목, 본문 해시, 수집·분석 시각, 구조화 분석 결과, 분석 상태, 오류 요약, 재시도 횟수(retry_count)만 저장함. 원문 본문 컬럼은 두지 않음.
  • tb_raid_recruitment_match_n은 프로필과 게시글 조합, 판정, 판정 요약, 알림 상태, 보류·발송 시각, delivery key, 읽음 시각(read_at, NULL이면 읽지 않음)을 저장함. (profile_id, post_id) 유니크 제약으로 같은 프로필·게시글의 중복 매칭을 막음.
  • 표시 판정은 manual_judgement가 있으면 수동 판정이고 그 값이 없으면 서버 판정임. 읽음 표시는 read_at에 저장하며 읽지 않음 건수는 표시 판정이 UNSUITABLE이 아니고 read_at이 NULL인 매칭만 셈.
  • 수동 변경과 재판정은 매칭 변경과 같은 트랜잭션에 tb_raid_recruitment_judgement_history_n을 기록함. 글 제목·URL, 변경 전후 판정, 판정 근거, 구조화 분석, 프로필 조건, 사용자·시각, 변경 출처와 재판정 프롬프트 버전을 저장하며 수집 데이터 정리 후에도 보존함.
  • tb_raid_recruitment_scan_state_n은 state_id=1 단일 행으로 마지막 수집·성공 시각과 결과 요약, 차단 해제 시각(blocked_until)·연속 차단 횟수, 처리 대기 여부(backlog), 모든 프로필이 공유하는 전역 수집 주기(scan_interval_minutes, 10·20·30·60분, 기본 10분)와 전역 알림 시간(notify_start_time, notify_end_time, 기본 08:00~23:00)을 저장함.

수집 시간·주기·차단·보존​

  • 수집은 활성 프로필이 하나 이상이고 현재가 전역 알림 시간 안일 때만 실행함. 시간 밖에서는 인벤 요청과 AI 호출을 하지 않으며, 시작이 종료보다 늦으면 자정을 넘는 구간으로 보고 매 실행 시점의 저장값으로 판정함.
  • 전역 수집 주기와 마지막 수집 후 경과 시간을 비교함. Automation tick보다 긴 주기는 앱이 건너뛰며 90초 허용 오차를 둠. 마지막 수집 시각은 처리할 글이 남은 회차에서도 매 회차 기록하며, 처리 대기(backlog) 중에는 주기를 기다리지 않고 다음 tick에서 바로 이어 처리함.
  • 신규 글의 판정은 모든 활성 프로필에 수행함. 알림 시간은 수집과 발송을 모두 제한하며, 알림 시간 밖에 남은 PENDING 매칭은 시간이 열리면 발송됨.
  • 알림 시작 시각 이후 첫 수집이 밤사이 글을 따라잡음. 한 회차는 요청 간격 1.5초로 최대 25건만 처리하고, 남은 글은 다음 tick에서 이어 처리함.
  • 인벤이 403·429로 응답하면 blocked_until까지 수집을 멈추고 1·2·4·8·12시간 순으로 물러남. 첫 차단 때 Message로 한 번 알리고 수집에 성공하면 차단 상태를 해제함.
  • 본문 추출·AI 분석에 실패한 글은 FAILED로 저장하고 최대 3회 다시 시도함. 글 한 건마다 저장하므로 중간에 실패해도 완료된 글은 유지함.
  • 한 회차에서 분석이 하나도 성공하지 못하고 삭제된 글·빈 본문·잘못된 AI 출력이 아닌 오류(라우팅 파일·인증·연결)로만 실패하면 설정 문제로 봄. 그 글들의 재시도 횟수를 돌려놓고 오류로 종료해 Automation 실행 이력에 실패로 남김.
  • 수집 실행 끝에 수집 후 30일이 지난 글과 매칭을 삭제함.
  • 프로필을 저장하면 수집 후 7일 이내의 저장된 글을 AI 호출 없이 다시 판정함. 프로필별 재분석 결과가 있으면 그 값을 사용하며 수동 판정이나 발송이 끝난 매칭은 유지함.

4.5 분석, 매칭, 발송 책임 경계​

  • 신규 본문 분석은 shared-ai의 DirectAiRunner와 SharedAiRuntimeFactory를 사용하며, 라우팅 키 RAID_RECRUITMENT_ANALYSIS의 구조화 출력 계약을 따름.
  • 분석 지침은 Hub의 RAID_RECRUITMENT_ANALYSIS_INSTRUCTION, 입력 템플릿은 RAID_RECRUITMENT_ANALYSIS_USER_TEMPLATE을 PromptService로 조회함. 입력 변수는 title, body임.
  • AI 사용량 기록은 HubApiAiUsageLogWriter를 통해 Hub에 남김. WOW 앱 SQLite에 별도 AI 사용량 로그를 만들지 않으며, 기록에는 원문 본문을 포함하지 않음.
  • 구인 분석 AI 요청의 앱 식별자는 module_code=WOW임.
  • 구인 여부는 공대가 인원을 찾는지 기준으로 추출함. 플레이어가 자리를 찾는 구직글은 제외함.
  • recruitment_slots는 실제 모집 자리와 명시적으로 허용된 참여 옵션별로 요일·참여 횟수·시간·고정/일회성 여부·직업 및 전문화·원문 표현·근거를 묶어 저장함. post_context_terms는 공대명과 방송 여부 등 글 단위 검색에 쓰는 짧은 원문 표현임.
  • 공대 진행 시각은 24시간제 HH:MM으로 정규화함(저녁 8시·20시 → 20:00, 새벽 1시·25시 → 01:00). 오전·오후 표기가 없으면 저녁으로 보고, 요일별로 다르면 가장 이른 시작과 가장 늦은 종료를 쓰며, 적혀 있지 않으면 비움. 읽을 수 없는 값은 검증기가 비움.
  • 1회성은 특정 회차나 일시적 대타 모집과 같은 참여 옵션의 속성임. 같은 글에 고정과 대타가 있으면 별도 자리로 취급함.
  • 서버는 글 제외 검색어를 제목·글 맥락·실제 모집 표현에서 우선 비교함. 글이 통과하면 각 자리 안에서 찾을 모집 자리와 제외할 모집 자리, 일정 조건을 함께 평가하고 적합·확인 필요·부적합 순으로 대표 판정을 정함.
  • 자리 배열이 비어 있으면 글 단위 요약으로 비교함. 직업명은 약칭으로 통일하며 부분 일치는 각 표현 안에서 검사함.
  • 주간 횟수는 글의 횟수(없으면 요일 수)가 프로필 값과 정확히 같아야 하고, 글의 요일은 모두 허용 요일 안에 있어야 함.
  • 프로필에 가능 시간대가 있으면 글의 공대가 그 범위 안에서 시작하고 끝나야 통과하며 범위를 꽉 채울 필요는 없음. 시작 시각 기준 경과 분으로 비교해 자정을 넘는 범위도 처리하고, 범위를 벗어나면 UNSUITABLE, 글에 시작 시각이 없으면 NEEDS_REVIEW임. 종료 시각이 없으면 시작만 비교하며, 시간 무관 프로필은 글의 시각을 보지 않음. 가능 시간대는 프로필당 하나이고 요일별로 나누지 않음.
  • 일정이 불명확하거나 1회성이거나 신뢰도가 0.65 미만이면 NEEDS_REVIEW로 남김.
  • 프로필 저장은 주간 횟수 1~7, 주간 횟수 ≤ 허용 요일 수, 가능 시간대의 유효성, 찾을 모집 자리 1개 이상을 검증함. 전역 설정 저장은 수집 주기 허용값과 서로 다른 알림 시작·종료 시각을 검증함. 검증 실패는 422로 응답함.

알림 발송​

  • 발송 시간대와 최종 중복 판정은 WOW 앱이 소유함. 수집 회차 끝과 recruitment-deliver-pending이 같은 발송 함수를 사용함.
  • 새 구인글 알림은 프로필당 한 통으로 보내며 적합·확인 필요 건수를 표시함. 구인글 보기 버튼은 해당 프로필의 /raid/recruitment/{profile_id}를 열어 줌.
  • 한 회차 상한으로 처리할 글이 남은 동안(backlog)은 두 경로 모두 발송을 보류해 밤사이 글이 한 통으로 나가게 함. 보류는 마지막 갱신 후 40분이 지나면 풀림.
  • 발송 허용 시간대 판정은 shared-core.now_kst()의 한국 시간으로 수행함.
  • 실제 Telegram 전달, 전송 이력, 재시도는 Message가 소유함. WOW 앱은 Message SQLite를 직접 읽거나 쓰지 않으며, Message internal API 응답 본문의 status가 SUCCESS일 때만 매칭을 발송 완료(DELIVERED)로 전환함. 채널 전달이 실패한 매칭은 DELIVERY_FAILED로 남기고 발송 대기에서 제외하며 다시 호출하지 않음. 같은 키는 Message가 재전달하지 않기 때문임.
  • 구인 수집(recruitment-scan)과 발송 대기 점검(recruitment-deliver-pending)은 처리할 일이 없었으면 응답에 "noop": true를 담고, 발송 대기 점검 응답은 delivered, failed 건수를 포함함.
  • Message 전달 요청의 source는 공통코드 MESSAGE_SOURCE.WOW를 사용하고 설정 WOW_RECRUITMENT_NOTIFICATION_OWNER_USER_ID(modules.wow.recruitment_notification_owner_user_id)의 값을 owner_user_id로 포함함. 값이 비어 있으면 owner_user_id를 보내지 않으며, 이 경우 알림은 전달되지만 Message 이력 목록에는 노출되지 않음.
  • raid-recruitment:{profile_id}:{첫 match_id}-{마지막 match_id}:{건수}:{match_id 목록 해시 8자} 형식의 idempotency key로 리포트 전달 요청을 식별함. 대상 집합이 달라지면 키도 달라짐.

4.6 공대 구인 스키마 초기화와 예약 실행​

  • 앱 lifespan은 공대 구인 스키마를 초기화함. 검색 조건 이관 시 종전 두 컬럼의 값은 찾을 모집 자리와 제외할 모집 자리로 옮기고 글 제외 검색어는 빈 배열로 시작함. 운영에서는 새 WoW 코드 전환과 컬럼 이관 시점을 맞춤.
  • Automation이 raid.recruitment-scan과 raid.recruitment-deliver-pending 작업의 cron, 실행 claim, lease, 재시도, 실행 이력, idempotency를 소유함.
  • 기본 작업은 수집·분석을 10분 tick(3-59/10 * * * *, timeout 300초), 보류 알림 발송을 5분마다(*/5 * * * *, timeout 60초) 실행하며 최대 시도는 3회, backoff는 60초임.
  • 수집 실행 여부(알림 시간·전역 수집 주기·차단·처리 대기)는 앱이 판정하고, 해당하지 않으면 요청 없이 skipped 사유와 noop으로 응답함.
  • 선택 재판정은 Automation의 raid.recruitment-rejudge를 사용함. 현재 분석 지침으로 인벤 본문을 다시 분석하고 저장된 프로필 조건을 적용함. 성공한 매칭의 수동 판정을 해제하고 rejudge_analysis_json을 저장하며 실패한 글은 유지함.
  • 동일 실행 키와 매칭 ID의 재판정 이력은 한 번만 저장함. 수동 판정과 선택 재판정은 구인글 알림을 새로 예약하지 않으며 부적합으로 바꿀 때 발송 대기를 해제함.

4.7 함께한 공대원 수집·저장 계약​

  • tb_raid_companion_character_m은 앱 전역 등록 캐릭터의 이름, 정규화 이름, SERVER 코드와 표시명, WCL 서버 slug·region, WCL 캐릭터 ID, 마지막 수집 완료 시각을 저장함. (character_name_key, server_region, server_slug) 유니크 제약을 사용함.
  • tb_raid_companion_sync_state_n은 캐릭터별 WCL ID와 수집 대상 보스·난이도를, tb_raid_companion_rank_stage_n은 대상별 WCL 처치 랭킹 응답을 저장함. 실패 후 재실행 시 완료된 대상의 응답을 다시 요청하지 않음.
  • tb_raid_companion_raid_name_m은 보스 ID별 레이드 이름을 저장함. 랭킹의 대표 보고서 전투에서 이름을 확인하고, 확인할 수 없으면 zone 이름을 사용함.
  • tb_raid_companion_encounter_n은 등록 캐릭터와 함께 보스를 처치한 상대 캐릭터, 상대 서버, 레이드, 난이도, 날짜, 첫·마지막 처치 시각, 처치 횟수, 대표 보고서 코드와 fight ID를 저장함. 상대 이름 기준 검색 인덱스와 최근 처치 기준 인덱스를 사용함. 앱 시작 시 user_id 컬럼이 남은 기존 테이블은 컬럼 없이 재구성하는 멱등 이관이 수행됨.
  • WCL worldData.zones에서 일반·영웅·신화 난이도 3·4·5를 확인하고, 캐릭터의 zoneRankings에서 처치 이력이 있는 보스·난이도만 수집 대상으로 삼음. 대상별 encounterRankings(includeOtherPlayers:true)의 처치 목록과 참여자를 조회하므로 recentReports 페이지 500건 제한을 사용하지 않음.
  • 반환된 처치 목록 길이가 WCL totalKills보다 작거나 필수 처치 정보가 빠지면 기존 기록을 유지한 채 수집을 중단함. (report_code, fight_id)로 같은 처치를 중복 제거하고, 상대·서버·레이드·난이도·날짜별 처치 횟수를 합산함. 트라이는 저장하지 않음.
  • 캐릭터별 모든 대상 수집이 끝나면 기존 집계 행을 새 결과로 교체하고 last_synced_at을 갱신한 뒤 중간 상태를 삭제함. 캐릭터 삭제는 해당 캐릭터의 중간 상태와 처치 기록을 함께 삭제함.
  • 수집은 wow-api 프로세스에서 한 번에 하나만 실행함. 진행 중인 수집이 있으면 Automation 재시도·수동 갱신 요청이 그 수집에 합류해 같은 결과를 받고, 호출자 연결이 끊겨도 수집은 계속됨. 중간 상태 저장은 ON CONFLICT 갱신이라 중복에도 안전함.
  • WCL 요청 한도(429)를 받으면 Retry-After(없으면 60초)만큼 기다렸다가 같은 요청을 이어 보내며, 한 수집의 누적 대기가 60분을 넘으면 503으로 중단하고 중간 상태를 남겨 다음 실행에서 이어 감.
  • GET /api/raid/companions/sync는 Automation 실행 상태에 더해, 실행이 FAILED이면 실패 원문을 가공한 사용자용 failure_reason을 돌려줌. 응답 원문(HTML 등)은 노출하지 않음.
  • GET /api/raid/companions/encounters는 등록 캐릭터 전체 범위에서 상대 캐릭터 이름 일부 검색과 page·size 페이지 조회를 제공함. API와 웹 진입점은 WOW module 권한을 요구함.

5. API와 화면 진입​

5.1 인증 API​

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

5.2 레이드 기능 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}
  • GET /api/raid/companions/characters
  • POST /api/raid/companions/characters
  • DELETE /api/raid/companions/characters/{character_id}
  • GET /api/raid/companions/encounters
  • GET /api/raid/companions/sync
  • POST /api/raid/companions/sync
  • GET /api/raid/recruitment/profiles
  • POST /api/raid/recruitment/profiles
  • PUT /api/raid/recruitment/profiles/{profile_id}
  • DELETE /api/raid/recruitment/profiles/{profile_id}
  • GET /api/raid/recruitment/profiles 응답의 각 프로필은 읽지 않음 건수(unread_count)를 포함함.
  • GET /api/raid/recruitment/profiles/{profile_id}/results는 include_unsuitable(기본 제외), 제목 부분 일치 title, 읽음 여부 is_read를 적용한 뒤 최신 100건을 반환함. 응답에는 표시 판정과 읽음 여부가 포함되며 없는 프로필은 404임.
  • POST /api/raid/recruitment/profiles/{profile_id}/results/read-state: match_ids와 is_read로 해당 프로필의 매칭 읽음 여부만 바꾸고 갱신 건수와 읽지 않음 건수를 반환함.
  • POST /api/raid/recruitment/profiles/{profile_id}/results/judgement는 match_ids의 수동 판정을 바꾸고 실제 변경 건수를 반환함.
  • POST /api/raid/recruitment/profiles/{profile_id}/results/rejudge는 선택한 match_ids의 재판정 작업을 요청함. 같은 경로의 GET은 해당 프로필의 최신 실행 상태와 결과 건수를 반환함.
  • GET /api/raid/recruitment/status: 마지막 수집 시각·결과, 차단 해제 시각, 처리 대기 여부, 전역 수집 주기, 활성 프로필 수, 전역 알림 시간과 알림 시간 안 여부(in_window)를 반환함.
  • GET·PUT /api/raid/recruitment/settings: 전역 수집 주기(scan_interval_minutes)와 선택 가능한 값 목록, 전역 알림 시작·종료 시각(notify_start_time, notify_end_time)을 조회·저장함.
  • GET /api/raid/companions/encounters는 상대 이름 search와 내 캐릭터 이름 own_search를 함께 받아 등록 캐릭터의 함께한 처치 기록을 필터링함. 일반 입력은 이름 일부 포함, =는 이름 정확 일치이며 같은 조건을 목록과 총 건수에 적용함.

공대원 목록 조회·저장 계약​

  • GET /api/raid/members는 raid_id, difficulty_code, 반복 가능 쿼리 member_category_codes를 수용함.
  • member_category_codes를 생략하면 활성 공대원 구분 전체를 조회함. 값이 전달되면 서버는 전달값과 무관하게 SELF를 항상 조회 대상에 포함함.
  • 응답 행은 공통코드 RAID_MEMBER_CATEGORY.sort_order_no와 레이드 멤버 정렬 순서를 기준으로 정렬함.
  • 응답의 server_slug는 SERVER.attribute02 값이며, UI가 Warcraft Logs 캐릭터 URL을 만들 때 사용함.
  • 응답의 wow_check_url은 https://wow-check.ryuar.in/ 고정 base URL에 선택 difficulty_code를 d 값으로, 캐릭터명과 SERVER.attribute01을 결합한 값을 q 값으로 사용해 구성함.
  • POST /api/raid/members/manage는 공대원 풀 저장 시 member_category_code를 함께 저장함. 신규 공대원 풀 행의 기본 구분은 RAID_MEMBER임.

5.3 Automation 내부 API​

  • POST /api/raid/internal/automation/recruitment-scan은 알림 시간·수집 주기·차단 상태를 판정한 뒤 게시판 목록 수집, 신규 글 본문 분석, 프로필 매칭, 묶음 리포트 발송을 수행함. 요청 body의 dry_run은 선택값임.
  • POST /api/raid/internal/automation/recruitment-deliver-pending은 보류 중인 매칭을 전역 알림 시간과 처리 대기 여부로 판정한 뒤 묶음 리포트로 Message internal API에 전달함.
  • POST /api/raid/internal/automation/companions-sync는 raid.companions-sync 작업으로 전달된 payload 없이 등록된 모든 캐릭터를 수집함. 작업 도중 실패하면 다음 실행에서 저장된 수집 중간 상태를 이어 사용함.
  • POST /api/raid/internal/automation/recruitment-rejudge는 선택한 매칭을 재판정하고 요청·갱신·실패 건수를 반환함.
  • 내부 작업 경로는 각각의 require_automation_job 인증을 적용함.
  • 호출자는 AUTOMATION_SERVICE_TOKEN, X-Junkbox-Service: automation, 허용된 X-Junkbox-Job-Type, Idempotency-Key를 제공해야 함.
  • WOW 앱이 Automation 수동 실행 API를 호출할 때는 X-Junkbox-Service: wow와 AUTOMATION_SERVICE_TOKEN을 사용함. Automation의 레이드 작업 유형 raid.*와 /api/raid/* 경로는 기능 식별자로 유지함.

5.4 웹 화면​

  • GET /raid/members
  • GET /raid/members/manage
  • GET /raid/recruitment, GET /raid/recruitment/new, GET /raid/recruitment/{profile_id}: 같은 recruitment 화면으로 진입하며 화면 안에서 경로로 보기를 나눔.
  • GET /raid/settings
  • GET /raid/companions
  • GET /error/403
  • /error/403은 하위 호환 진입점이며 권한 없음 처리는 코어 가이드 인증 절의 실패 정책을 따름.

5.5 화면 진입 데이터 구성​

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

5.6 API 계약 특성​

  • 두 화면 모두 기본적으로 풀 로딩형 Tabulator 편집 화면을 사용함.
  • 공대원 목록 저장은 역할, 근/원, 참여 여부, 정렬 순서 같은 레이드 소속 정보를 기준으로 처리함.
  • 공대원 관리 저장은 공대원 풀 자체의 생성, 수정, 삭제와 공대원 구분 저장을 기준으로 처리함.
  • 신규 행 삭제는 프런트 메모리에서만 제거되고, 저장된 행 삭제만 실제 삭제 API를 호출함.
  • 공대원 관리의 일괄 삭제는 선택 체크박스 기반으로 수행함.
  • 공대 구인 프로필 CRUD, 프로필별 구인글 조회·읽음 표시, 수집 상태 조회와 전역 설정 조회·저장은 전용 JSON API를 사용함.
  • 함께한 공대원 화면은 앱 전역 캐릭터 등록·삭제, 상대 이름 검색, 수동 수집 실행·상태 조회를 전용 JSON API로 처리함.

6. 관련 문서​

  • 프로젝트 전체 구조는 docs/junkbox/common/guide-jb-overview.md, 공통 원칙은 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-wow-ui.md를 따름.