본문으로 건너뛰기

JunkBox apps/wow-ui 가이드

1. 역할과 실행​

  • apps/wow-ui는 WoW 서비스 화면용 React + Vite 프런트엔드 앱임.
  • 공대원 목록, 공대원 관리, 함께한 공대원, 공대 구인 알림, 설정 화면을 제공함.
  • 공대원 목록과 관리는 PC/FHD 우선 단일 작업형 화면이며, 공대 구인 알림과 설정은 모바일 우선 단일 열 화면임.
  • 스타일은 shared-ui 공통 자산만 사용함.

1.1 런타임 구성​

  • 번들러는 Vite 6 계열을 사용함.
  • React + TypeScript strict 기준으로 구현함.
  • 개발 서버 기본 포트는 15009임.
  • 빌드 산출물은 apps/wow-ui/dist에 생성됨.
  • 운영에서는 wow-api가 이 산출물을 /wow-ui 경로로 직접 서빙함.

1.2 엔트리와 화면 분기​

  • 메인 엔트리는 src/entries/wow.tsx임.
  • 루트 마운트 지점은 wow-ui-root임.
  • 메인 화면 컴포넌트는 src/pages/RaidPage.tsx임.
  • 서버가 주입한 page_props.view 값을 기준으로 members, manage, recruitment, settings, companions 화면을 분기함.
  • 초기 props에는 레이드/난이도/직업/서버/역할/근원/공대원 구분 코드 목록이 포함됨.
  • 공대 구인 알림은 BrowserRouter의 /raid/recruitment(프로필 목록), /raid/recruitment/new(새 프로필), /raid/recruitment/{profile_id}(프로필 상세, ?tab=edit이면 수정 탭) SPA 경로로 진입함. 서버 렌더링 진입 경로와 Vite 개발 서버의 /wow-ui/raid/recruitment 하위 경로는 모두 이 화면으로 연결되며 경로 해석은 RecruitmentPage가 담당함.
  • 설정은 /raid/settings 서버 렌더링 진입점을 사용하며 SPA 이동 없이 전체 로드로 진입함. 공대 구인 알림 안에서만 SPA 이동을 사용함.
  • 함께한 공대원은 /raid/companions 서버 렌더링 진입점을 사용함. Vite 개발 서버는 /raid/companions를 WOW API에 프록시하고 /wow-ui/raid/companions를 /raid/companions로 리다이렉트함.
  • WoW 상단 메뉴는 공대원 목록, 공대원 관리, 함께한 공대원, 공대 구인 알림, 설정 순서로 표시하며 각 항목은 기존 /raid/* 화면 경로로 이동함.
  • SPA 내부 이동은 junkbox:spa-navigate, SpaRouteTransition, useSpaRouteSettling 공통 계약을 사용함.

1.3 개발 및 빌드 기준​

  • 타입 계약은 앱 내부 src/types/models.ts를 기준으로 관리함.
  • 브라우저 전역 타입과 import.meta.env 타입은 앱 내부 선언 파일에서 관리함.
  • 개발 모드 엔트리 경로는 /wow-ui/src/entries/*.tsx 기준을 사용함.
  • Vite dev client 경로는 /wow-ui/@vite/client임.
  • React refresh runtime 경로는 /wow-ui/@react-refresh임.

2. 공통 UI 계약​

2.1 공통 UI 규칙 반영 방식​

  • WoW 앱의 레이드 화면은 hub-ui-base.css + hub-ui-desktop.css + junkbox-tabulator.css 조합을 사용함.
  • 페이지 전체 스크롤보다 내부 그리드 스크롤을 우선함.
  • 그리드는 부모 패널 높이를 채우고, 데이터가 많아도 패널 내부에서만 스크롤됨.
  • 컬럼 폭은 가능하면 가로 스크롤이 생기지 않도록 타이트하게 조정함.
  • 공통 버튼 위계는 docs/junkbox/common/guide-jb-common-ui.md의 저장/조회 기준을 그대로 따름.
  • 상단 필터 셀렉트와 그리드 내부 셀렉트는 모두 공통 다크 테마 규칙을 사용함.
  • 공대 구인 모바일 화면은 전용 CSS를 만들지 않고 shared-ui의 모바일 폭, 패널, 카드, 시트, 하단 고정 액션바 자산을 조합함.
  • 프로필의 활성화는 Switch로 즉시 조작하며 프로필 수정 폼 최상단에 둠. 구인글 선택은 Checkbox를 사용하며 네이티브 체크박스를 사용하지 않음.
  • 카드 목록의 활성·비활성 배지는 공통 UI 문서의 모바일 카드 상태 배지 규칙을 사용하며 줄바꿈되지 않아야 함.

2.2 Tabulator 연동 규칙​

  • 편집형 그리드는 Tabulator 기준으로 구현함.
  • list editor 셀에는 공통 클래스 jb-cell-editor-list를 적용하여 편집 가능 셀임을 우측 chevron으로 표시함.
  • list editor 드롭다운은 브라우저 기본 흰색 팝업 대신 공통 다크 스타일을 사용함.
  • 체크박스 선택 컬럼, hover/selected 행 강조, 줄무늬 제거는 공통 Tabulator CSS가 담당함.
  • 헤더 필터는 별도 검색 패널 대신 컬럼별 직접 검색 수단으로 사용함.

3. 화면 구조​

3.1 공대원 목록 화면​

  • 상단 제어 영역은 레이드, 난이도, 구분, 조회 상태, 작업 그룹을 한 행에 배치함.
  • 구분은 추적, 공대원 멀티 체크를 하나의 선택 영역으로 제공함. 나는 체크 항목으로 노출하지 않으며 서버가 항상 포함함. 초기값은 추적과 공대원을 모두 선택한 상태임.
  • 조회 상태 그룹에는 총 n건과 선택 레이드·난이도의 최근 업데이트 시각을 배치함.
  • 액션 버튼은 wow-check, 조회, 점수 갱신, 저장을 사용함.
  • 그리드는 풀 로딩형 Tabulator를 사용함.
  • 구분 컬럼은 캐릭터명 바로 앞에 배치하며, 공통코드 정렬 순서인 나, 추적, 공대원 순으로 행을 표시함.
  • 최근 업데이트는 목록 전체 갱신 상태이므로 행별 컬럼으로 표시하지 않고 상단 조회 상태에만 표시함.
  • 캐릭터명 셀은 새 탭으로 Warcraft Logs 캐릭터 페이지를 여는 링크임. URL은 https://ko.warcraftlogs.com/character/kr/{server_slug}/{character_name}?difficulty={difficulty_code}&zone={raid_code}이며, server_slug는 서버 공통코드 SERVER.attribute02 값임.
  • 역할, 근/원, 참여 여부, 정렬 순서를 인라인 편집함.
  • 보스 점수 컬럼은 선택된 레이드와 난이도 기준으로 동적으로 구성됨.
  • 점수 셀은 기본적으로 숫자만 색상으로 표시하며, 미확정 점수만 셀 전체 강조색으로 표현함.
  • 개별 행 점수 갱신 UI는 제공하지 않음.
  • 행 재정렬은 드래그앤드롭으로 수행하고 저장 시 정렬 순서를 서버에 반영함.

3.2 공대원 관리 화면​

  • 상단 필터 영역에서 레이드를 선택함.
  • 작업 패널 헤더에는 총 n건, 우측 액션 버튼 영역을 배치함.
  • 액션 버튼은 조회, 추가, 삭제, 저장을 사용함.
  • 그리드는 풀 로딩형 Tabulator를 사용함.
  • 저장형 마스터 화면이므로 신규 행 추가, 인라인 편집, 일괄 저장을 한 화면에서 처리함.
  • 첫 컬럼은 선택 체크박스 컬럼이며, 일괄 삭제는 선택 행 기준으로 수행함.
  • 서버, 직업, 역할, 근/원 같은 코드성 컬럼은 list editor를 사용함.
  • 구분 컬럼은 캐릭터명 바로 앞에 배치하고 RAID_MEMBER_CATEGORY 코드 목록을 list editor로 편집함.
  • 신규 행은 구분=공대원과 나머지 빈값 + 필수 검증 기준으로 시작함.
  • 저장 전 신규 행 삭제는 프런트 메모리에서만 제거함.

3.3 공대 구인 알림 화면​

  • 고정 폭 모바일 레이아웃에서 프로필 목록 → 프로필 상세(구인글·프로필 수정 탭) 구조로 구성하며 경로는 1.1절을 따름.

프로필 목록​

  • 프로필 카드는 첫 줄에 번호 칩(#{profile_id})과 제목을 한 줄 전체로 표시하고, 아래에 요일·주 n회·가능 시간대(시간 무관이면 시간 무관, 종료가 시작보다 이르면 다음 날을 붙여 표시), 프로필별 수집 상태 줄, 맨 아래 줄에 활성·비활성 배지와 읽지 않음 n건 배지(0건이면 생략)를 표시함. 카드를 누르면 프로필 상세로 이동함.
  • 수집 상태 줄은 우선순위대로 비활성, 알림 시간 밖 휴지, 처리 대기 중(밀린 글을 이어서 확인하고 있습니다.), 마지막 수집 시각과 전역 수집 주기, 수집 이력 없음을 표시함. 수집과 알림 시간은 모든 프로필이 공유하므로 마지막 수집 시각과 알림 시간 휴지는 같고 활성 상태만 프로필마다 다름.
  • 수집이 차단된 동안은 목록 상단에 NoticeCard(error)로 해제 시각을 안내함. 화면 상단에 설명 문구나 통합 수집 상태를 두지 않음.
  • 하단 고정 액션바는 새로고침 아이콘 버튼(접근성 이름 새로고침, 재조회만 수행)과 새 프로필 버튼 순서임.

프로필 상세​

  • SegmentedTabs로 구인글(기본)과 프로필 수정 탭을 전환하며 탭은 ?tab=edit 쿼리로 구분함. 헤더에는 번호 칩과 제목을 표시함. 삭제된 프로필이면 오류 NoticeCard와 목록 복귀 버튼만 표시함.
  • 구인글 탭은 프로필 탐색 결과와 자리별 일정 요약을 카드로 표시함. 검색 아이콘은 제목·읽음 상태·부적합 글 포함을 설정하는 검색 조건 모달을 엶. 부적합 글은 기본값에서 숨김.
  • 조회에서 검색 조건을 목록에 반영함. 초기화는 모달 입력을 기본값으로 되돌리며 닫기는 미적용 입력을 버림. 검색 결과에서 사라진 글은 선택에서 제외함.
  • 구인글 카드의 어느 곳을 눌러도 Checkbox 선택이 토글되며 원문은 열리지 않음. 카드는 제목(읽은 글은 흐린 글자), 일정 요약, 판정 사유, 알림 상태(발송 완료는 실제 발송 시각), 맨 아래 줄의 읽음 배지·판정 StatusBadge(적합·확인 필요·부적합)와 오른쪽 끝 원문 보기 링크 순서임. 링크는 선택과 읽음 상태를 바꾸지 않음.
  • 하단 고정 액션바 순서는 목록, 전체 선택·해제, 검색 아이콘, 판정 변경, 상태 변경임. 전체 선택은 화면에 보이는 결과에 적용함.
  • 판정 변경은 적합·확인 필요·부적합 또는 현재 기준으로 재판정을, 상태 변경은 읽음·읽지 않음을 선택한 글에 적용함. 선택 시트와 확인 모달을 거침.
  • 재판정 실행 중에는 공통 진행 색 안내를 목록 위에 표시함. 완료하면 목록을 갱신하고 안내를 숨기며 실패한 작업 또는 건수는 토스트로 안내함.
  • 프로필 수정 탭과 새 프로필 화면은 같은 폼을 사용함. 입력값은 활성화(Switch, 폼 최상단), 제목, 허용 요일, 주간 횟수, 찾을 모집 자리·제외할 모집 자리·글 제외 검색어, 가능 시간대(시간 무관 Switch와 가능 시작·종료 시각)이며 수집 주기와 알림 시간은 프로필에 없음. 프로필 제목은 식별용 자유 입력값이고 자동완성이나 기본 제목을 제공하지 않음.
  • 주간 횟수는 주 [n] 회 숫자 입력(1~7)임. 허용 요일 수보다 크면 저장 버튼을 비활성화하고 오류 NoticeCard로 이유를 안내함. 허용 요일은 가능한 요일이며 모두 진행한다는 뜻이 아님.
  • 가능 시간대는 공대 진행 시간이 이 범위 안에 있는 글만 알려 준다는 뜻임. 시간 무관은 기본으로 켜져 있고 끄면 가능 시작·종료 입력(기본 18:00~01:00)과 안내 NoticeCard가 나타남. 범위를 꽉 채울 필요가 없고, 종료가 시작보다 이르면 다음 날로 보며, 공대 시간이 적히지 않은 글은 확인 필요로 알린다는 점을 안내함.
  • 세 모집 조건 입력은 쉼표로 구분함. 입력 중에는 원문을 유지하고 저장 시 빈 항목과 앞뒤 공백을 제거함. 제외할 모집 자리는 자리 단위, 글 제외 검색어는 글 단위로 적용함. 원본은 와우 인벤 파티찾기 > 레이드로 고정 표시함.
  • 수정 보기의 하단 고정 액션바는 왼쪽부터 목록 아이콘 버튼(접근성 이름 프로필 목록으로 이동, 저장 없이 이동하는 jb-button-ghost), 휴지통 아이콘 삭제 버튼(기존 프로필에서만 표시, jb-button-danger, 접근성 이름 프로필 삭제), 남은 폭을 채우는 저장 버튼임. 저장·삭제 버튼을 폼 본문 안에 두지 않으며 폭 분배는 공통 UI 가이드 7.4의 혼합 버튼 규칙을 따름.
  • 삭제는 FormModal 확인을 거쳐 실행하고 확인 버튼은 danger 색을 사용함. 저장·삭제는 LoadingModal로 진행을 표시함.

설정​

  • 설정 화면의 공대 구인 알림 구역에서 전역 수집 주기(10·20·30·60분, 기본 10분)를 SelectTrigger와 BottomOptionPicker로 선택함. 모든 프로필에 공통 적용되며 인벤 차단이 걱정되면 늘리도록 안내함.
  • 같은 구역에서 전역 알림 시작·종료 시각(기본 08:00~23:00)을 입력함. 게시판 확인과 알림이 모두 이 시간 안에서만 이뤄지고 시작 시각에는 그사이 올라온 글을 모아서 알린다는 안내 NoticeCard를 함께 표시하며, 시작이 종료보다 늦으면 자정을 넘는 구간으로 해석함. 두 시각이 같으면 오류 NoticeCard를 표시하고 저장을 막음.
  • 하단 고정 액션바의 저장 버튼은 수집 주기·알림 시각 중 하나라도 저장된 값과 다를 때만 활성화됨.

3.4 함께한 공대원 화면​

  • PC/FHD 우선 화면의 내 캐릭터 n명 버튼은 관리 모달을 엶. 모달에서 캐릭터 이름과 서버를 등록·삭제하고, 등록 목록의 캐릭터별 마지막 수집 완료 시각을 yyyy-mm-dd hh24:mi:ss 형식으로 표시함.
  • 기록 갱신은 Automation 수동 작업을 등록하고 즉시 반환함. 시작 토스트 뒤 수집 중 상태를 표시하며 실행 중에는 중복 갱신·캐릭터 등록·삭제 버튼을 비활성화함.
  • 화면을 열어 둔 동안 실행 상태를 5초마다 조회함. 완료 시 캐릭터 목록과 기록 그리드를 다시 읽고, 실패 시 서버가 준 failure_reason을 오류 토스트와 그리드 헤더 아래 NoticeCard(error)로 표시함. 화면에 다시 진입하면 저장된 최신 실행 상태를 조회함.
  • 그리드 상단 한 줄에 함께한 기록, 총 건수, 수집 상태, 캐릭터 관리 버튼, 기록 갱신 버튼을 표시함. 상태는 조회 전용 표시임.
  • Tabulator의 함께한 캐릭터와 내 캐릭터 컬럼 헤더 필터가 각각 search, own_search를 서버로 전달하고, 내장 원격 페이지네이션으로 100건씩 조회함. 두 조건은 함께 적용되며 일반 입력은 일부 포함, =는 정확 일치 검색임. 결과 컬럼은 상대 이름·서버, 내 캐릭터·서버, 날짜, 레이드, 일반·영웅·신화 난이도, 함께한 처치 횟수, 대표 WCL 보고서 전투 링크임.
  • 대표 로그 셀은 외부 링크 아이콘을 표시하고 선택 시 Warcraft Logs 보고서 전투 링크를 새 탭으로 엶. 링크의 접근성 이름과 툴팁은 대표 로그 새 탭에서 열기임.
  • 수집은 등록 캐릭터의 WCL 보스 처치 랭킹을 기준으로 하며, 트라이를 제외하고 같은 상대·서버·레이드·난이도·날짜의 처치를 한 행으로 집계함. 상세 계약은 docs/junkbox/apps/guide-apps-wow-api.md를 따름.

4. 데이터 계약​

4.1 데이터 흐름​

  • React 화면은 wow-api JSON API만 호출함.
  • 사용자 피드백은 shared-ui 공통 토스트 유틸을 통해 처리함.
  • 사용자 노출 텍스트는 화면 컴포넌트에 한국어 문구로 직접 작성함.
  • 공통코드 라벨과 메타 설정값처럼 데이터 자체가 마스터데이터인 값만 DB 조회 구조를 사용함.
  • 저장 성공/실패, 점수 갱신, 정렬 저장, 삭제 결과는 공통 토스트로 표기함.
  • WCL 점수 갱신은 전체 페이지 단위 액션만 호출함.
  • wow-check 액션은 목록 API가 반환한 wow_check_url을 새 탭으로 열며, 선택 난이도 코드에 맞는 외부 조회 URL을 직접 조합하지 않음.
  • 공대 구인 화면은 프로필 목록·등록·수정, 프로필별 구인글·읽음 표시, 수집 상태 API를 호출하고 설정 화면은 전역 설정 API를 호출함.
  • 함께한 공대원 화면은 WOW JSON API로 앱 전역 등록 캐릭터, 상대 검색 결과, Automation에 저장된 최신 수동 실행 상태를 조회함.

5. 관련 문서​

  • 프로젝트 전체 구조는 docs/junkbox/common/guide-jb-overview.md, 공통 원칙은 docs/junkbox/common/guide-jb-core.md를 따름.
  • 레이드 백엔드 구조는 docs/junkbox/apps/guide-apps-wow-api.md를 따름.
  • 공통 UI 자산 구조는 docs/junkbox/libs/guide-lib-shared-ui.md를 따름.
  • 공통 UI 규칙은 docs/junkbox/common/guide-jb-common-ui.md를 따름.