CatchHole Frontend
웹소설/웹툰 작가·편집자가 회차 원고를 업로드하면 기존 설정집(인물/아이템/스킬/타임라인 등)과의 충돌·모순을 AI로 검사해주는 툴 CatchHole의 프론트엔드(React SPA)입니다.
기술 스택
- React 18 + TypeScript(strict) + Vite 6
- Hey API + TanStack Query 5
- Tailwind CSS v4 + MUI 7 + Radix UI(shadcn 스타일 컴포넌트)
- react-router 7
시작하기
npm install
# 환경변수 설정
cp .env.example .env
# .env에서 VITE_API_BASE_URL을 백엔드 API 주소로 설정 (기본값: http://localhost:8080)
npm run dev
| 명령어 | 설명 |
|---|
npm run dev | 개발 서버 실행 (Vite) |
npm run build | 타입 체크(tsc -b) + 프로덕션 빌드 |
npm run preview | 빌드 결과 로컬 프리뷰 |
npm run lint | ESLint 검사 |
npm run test:e2e | Playwright E2E 테스트 |
npm run api:generate | 백엔드 OpenAPI에서 타입·SDK·TanStack Query 옵션 생성 |
기본적으로 http://localhost:8080/v3/api-docs의 계약을 사용합니다. 백엔드 포트가 다르면 입력 URL을 지정합니다.
CATCHHOLE_OPENAPI_INPUT=http://localhost:18080/v3/api-docs npm run api:generate
생성 결과는 src/app/api/generated/에 저장되며 직접 수정하지 않습니다.
실제 Backend·DB를 사용하는 설정집 live E2E는 매 실행마다 새 회원을 만들지 않습니다. 휴대폰 인증이 완료된 전용 계정과 아래 환경변수를 사용합니다.
CATCHHOLE_E2E_API_BASE_URL=http://localhost:8080 \
[email protected] \
CATCHHOLE_E2E_PASSWORD='<password>' \
npx playwright test e2e/setting-book-live.spec.ts
비로그인 사용자는 백엔드 연결이나 .env 없이도 /demo에서 10문단 가상 원고를 이용한 fixture 기반 단일 시나리오를 체험할 수 있습니다. 후보 검토 뒤 실제 형식의 캐릭터·세계관 설정 DB에서 5명의 캐릭터 카드와 설정 행을 눌러 상세·회차별 변화 이력·원문 근거까지 확인합니다. 이 공개 데모만 API를 호출하지 않으며, 보호 화면은 연결 실패를 목 데이터 전환 조건으로 사용하지 않습니다.
주요 라우트
| 경로 | 화면 | 설명 |
|---|
/landing | SLanding | 비로그인 서비스 소개와 Auth 모달 공통 배경 (공개) |
/login | SLogin | 랜딩 위 로그인 라우트 모달 (공개) |
/signup | SSignup | 랜딩 위 회원가입 라우트 모달 (공개) |
/demo | SInteractiveDemo | 딤 없이 타깃 바깥의 고정 여백 윤곽선이 중앙 기준으로 나타나고 호흡하는 코치마크로 후보 검토와 캐릭터·세계관 상세/변화 이력/원문 근거를 확인하는 fixture 단일 시나리오 (공개, API 호출 없음) |
/ | S0WorkPicker | 작품 선택 (진입점) |
/dashboard | S1Dashboard | 선택된 작품의 대시보드 |
/editor | S2Editor | 원고 에디터 |
/chat | S3Chat | 챗봇 |
/loading | S4Loading | 분석 진행률 |
/report | S5Report | 충돌/모순 리포트 |
/episode-upload | SEpisodeUpload | 회차 업로드 (모드 선택 → 파일 업로드 → 회차 분리 확인 → 설정집 분석) |
/setting-review | SSettingReview | 추출된 설정 후보 검토 |
/episode-validation-report | SEpisodeValidationReport | 회차 검사(충돌/모순) 결과 |
/landing, /login, /signup, /demo를 제외한 모든 라우트는 인증(accessToken)이 필요합니다.
프로젝트 구조
src/app/
api/ # Hey API 런타임 설정과 OpenAPI 생성 코드
components/catchhole/ # 화면 컴포넌트, 디자인 토큰(constants.ts), 타입, 목 데이터
context/ # AppContext, BackendStatusContext
lib/ # API/인증 fetch, QueryClient, worksApi, fileValidation
상세 구조, 디자인 시스템(토큰), 디자인 워크플로우, 커밋 컨벤션 등은 CLAUDE.md를 참고하세요.
배포
Vercel을 사용하며, vercel.json에 SPA 라우팅(파일시스템 우선 + index.html 폴백)이 설정되어 있습니다.
참고 문서
가족 관계 가계도 미리보기
가계도는 기본 공개이며 사이드바 관계도 또는 /dashboard?workId=<id>&nav=graph에서 확인한다. VITE_RELATIONSHIP_WORKSPACE_ENABLED가 정확히 문자열 false인 빌드에서만 숨기며 미설정·빈 문자열·그 외 값은 공개한다. 기존 명시적 가족 관계를 자동 배치하고 인물 프로필·관계 근거·후보 검토로 연결한다. 화면/API 계약 · React Flow/ELK·Mermaid 비교와 배치 테스트. npm run test:layout으로 순수 배치 검증을 실행한다.
