1. 애플리케이션 역할
apps/raid-ui는 레이드 운영 화면용 React + Vite 프런트엔드 앱임.- 공대원 목록과 공대원 관리 두 화면을 제공함.
- 모든 화면은 PC/FHD 우선 단일 작업형 화면 기준으로 설계됨.
- 스타일은
shared-ui 공통 자산만 사용함.
2. 런타임 구성
- 번들러는 Vite 6 계열을 사용함.
- React + TypeScript strict 기준으로 구현함.
- 개발 서버 기본 포트는
15009임.
- 빌드 산출물은
apps/raid-ui/dist에 생성됨.
- 운영에서는
raid-api가 이 산출물을 /raid-ui 경로로 직접 서빙함.
3. 엔트리와 화면 분기
- 메인 엔트리는
src/entries/raid.tsx임.
- 루트 마운트 지점은
raid-ui-root임.
- 메인 화면 컴포넌트는
src/pages/RaidPage.tsx임.
- 서버가 주입한
page_props.view 값을 기준으로 members와 manage 화면을 분기함.
- 초기 props에는 현재 사용자, 레이드/난이도/직업/서버/역할/근원 코드 목록이 포함됨.
4. 화면 구조
4.1 공대원 목록 화면
- 상단 필터 영역에서
레이드, 난이도를 선택함.
- 작업 패널 헤더에는
총 n건, 최근 업데이트, 우측 액션 버튼 영역을 배치함.
- 액션 버튼은
wow-check, 조회, 점수 갱신, 저장을 사용함.
- 그리드는 풀 로딩형 Tabulator를 사용함.
- 역할, 근/원, 참여 여부, 정렬 순서를 인라인 편집함.
- 보스 점수 컬럼은 선택된 레이드와 난이도 기준으로 동적으로 구성됨.
- 점수 셀은 기본적으로 숫자만 색상으로 표시하며, 미확정 점수만 셀 전체 강조색으로 표현함.
- 개별 행 점수 갱신 UI는 제공하지 않음.
- 행 재정렬은 드래그앤드롭으로 수행하고 저장 시 정렬 순서를 서버에 반영함.
4.2 공대원 관리 화면
- 상단 필터 영역에서
레이드를 선택함.
- 작업 패널 헤더에는
총 n건, 우측 액션 버튼 영역을 배치함.
- 액션 버튼은
조회, 추가, 삭제, 저장을 사용함.
- 그리드는 풀 로딩형 Tabulator를 사용함.
- 저장형 마스터 화면이므로 신규 행 추가, 인라인 편집, 일괄 저장을 한 화면에서 처리함.
- 첫 컬럼은 선택 체크박스 컬럼이며, 일괄 삭제는 선택 행 기준으로 수행함.
- 서버, 직업, 역할, 근/원 같은 코드성 컬럼은
list editor를 사용함.
- 신규 행은 빈값 + 필수 검증 기준으로 시작함.
- 저장 전 신규 행 삭제는 프런트 메모리에서만 제거함.
5. 공통 UI 규칙 반영 방식
- 레이드 화면은
hub-ui-base.css + hub-ui-desktop.css + junkbox-tabulator.css 조합을 사용함.
- 페이지 전체 스크롤보다 내부 그리드 스크롤을 우선함.
- 그리드는 부모 패널 높이를 채우고, 데이터가 많아도 패널 내부에서만 스크롤됨.
- 컬럼 폭은 가능하면 가로 스크롤이 생기지 않도록 타이트하게 조정함.
- 공통 버튼 위계는
docs/junkbox/common/guide-jb-common-ui.md의 저장/조회 기준을 그대로 따름.
- 상단 필터 셀렉트와 그리드 내부 셀렉트는 모두 공통 다크 테마 규칙을 사용함.
6. Tabulator 연동 규칙
- 편집형 그리드는 Tabulator 기준으로 구현함.
list editor 셀에는 공통 클래스 jb-cell-editor-list를 적용하여 편집 가능 셀임을 우측 chevron으로 표시함.list editor 드롭다운은 브라우저 기본 흰색 팝업 대신 공통 다크 스타일을 사용함.- 체크박스 선택 컬럼, hover/selected 행 강조, 줄무늬 제거는 공통 Tabulator CSS가 담당함.
- 헤더 필터는 별도 검색 패널 대신 컬럼별 직접 검색 수단으로 사용함.
7. 데이터 흐름
- React 화면은
raid-api JSON API만 호출함.
- 사용자 피드백은
shared-ui 공통 토스트 유틸을 통해 처리함.
- 사용자 노출 텍스트는 화면 컴포넌트에 한국어 문구로 직접 작성함.
- 공통코드 라벨과 메타 설정값처럼 데이터 자체가 마스터데이터인 값만 DB 조회 구조를 사용함.
- 저장 성공/실패, 점수 갱신, 정렬 저장, 삭제 결과는 공통 토스트로 표기함.
- WCL 점수 갱신은 전체 페이지 단위 액션만 호출함.
8. 개발 및 빌드 기준
- 타입 계약은 앱 내부
src/types/models.ts를 기준으로 관리함.
- 브라우저 전역 타입과
import.meta.env 타입은 앱 내부 선언 파일에서 관리함.
- 개발 모드 엔트리 경로는
/raid-ui/src/entries/*.tsx 기준을 사용함.
- Vite dev client 경로는
/raid-ui/@vite/client임.
- React refresh runtime 경로는
/raid-ui/@react-refresh임.
9. 관련 문서
- 프로젝트 전체 구조는
docs/junkbox/common/guide-jb-core.md를 따름.
- 레이드 백엔드 구조는
docs/junkbox/apps/guide-apps-raid-api.md를 따름.
- 공통 UI 자산 구조는
docs/junkbox/libs/guide-lib-shared-ui.md를 따름.
- 공통 UI 규칙은
docs/junkbox/common/guide-jb-common-ui.md를 따름.