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 폴백)이 설정되어 있습니다.

참고 문서

• CLAUDE.md — 프로젝트 컨텍스트, 디자인 시스템, 워크플로우, 컨벤션

가족 관계 가계도 미리보기

가계도는 기본 공개이며 사이드바 관계도 또는 /dashboard?workId=<id>&nav=graph에서 확인한다. VITE_RELATIONSHIP_WORKSPACE_ENABLED가 정확히 문자열 false인 빌드에서만 숨기며 미설정·빈 문자열·그 외 값은 공개한다. 기존 명시적 가족 관계를 자동 배치하고 인물 프로필·관계 근거·후보 검토로 연결한다. 화면/API 계약 · React Flow/ELK·Mermaid 비교와 배치 테스트. npm run test:layout으로 순수 배치 검증을 실행한다.