diff --git a/.gitignore b/.gitignore index d849f5293..a23acf185 100644 --- a/.gitignore +++ b/.gitignore @@ -7,4 +7,5 @@ dailyNote/ -/.omc \ No newline at end of file +/.omc +.gstack/ diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md index 9fb87dbd1..3a2046832 100644 --- a/frontend/CLAUDE.md +++ b/frontend/CLAUDE.md @@ -34,173 +34,6 @@ npm run chromatic # Chromatic으로 시각적 테스트 배포 npm run generate:sitemap # sitemap.xml 생성 ``` -## 아키텍처 개요 - -### 기술 스택 - -- React 19 + TypeScript -- Vite 번들러 (webpack 설정도 있으나 Vite가 주력) -- styled-components 스타일링 -- TanStack React Query v5 서버 상태 관리 -- Zustand 클라이언트 상태 관리 -- React Router v7 -- date-fns 날짜 처리 -- Framer Motion 애니메이션 -- Swiper 캐러셀 -- react-datepicker 날짜 선택 -- react-markdown 마크다운 렌더링 - -### 외부 서비스 통합 - -- **Mixpanel**: 사용자 분석 및 이벤트 트래킹 -- **Sentry**: 에러 모니터링 및 성능 추적 -- **Channel.io**: 고객 지원 채팅 -- **Kakao SDK**: 카카오 공유 기능 - -모든 SDK는 `src/utils/initSDK.ts`에서 초기화되며, 각각 환경 변수 필요. - -### 환경 변수 - -`.env` 파일에 다음 환경 변수 설정 필요 (모두 `VITE_` 접두사 사용): - -- `VITE_API_URL` - 백엔드 API URL -- `VITE_MIXPANEL_TOKEN` - Mixpanel 프로젝트 토큰 -- `VITE_SENTRY_DSN` - Sentry DSN -- `VITE_SENTRY_RELEASE` - Sentry 릴리즈 버전 -- `VITE_ENABLE_SENTRY_IN_DEV` - 개발 환경에서 Sentry 활성화 여부 (true/false) -- `VITE_CHANNEL_PLUGIN_KEY` - Channel.io 플러그인 키 -- `VITE_KAKAO_JAVASCRIPT_KEY` - Kakao JavaScript 키 - -### 프로젝트 구조 - -**경로 별칭**: `@/*`는 `src/*`로 매핑 - -**주요 디렉토리**: - -- `src/apis/` - 도메인별 API 함수 (club, auth, application, applicants) -- `src/hooks/Queries/` - API를 래핑하는 React Query 훅 (useClub, useApplication, useApplicants) -- `src/store/` - Zustand 스토어 (useCategoryStore, useSearchStore) -- `src/pages/` - 라우트 기반 페이지 컴포넌트 -- `src/components/` - 공용 UI 컴포넌트 -- `src/context/` - React Context 프로바이더 (AdminClubContext - SSE 상태 관리) -- `src/experiments/` - A/B 테스트 실험 정의 및 관리 -- `src/mocks/` - MSW(Mock Service Worker) 핸들러 -- `src/utils/` - 유틸리티 함수 (날짜 파싱, 유효성 검사, 디바운스, WebView 브릿지 등) -- `src/errors/` - 커스텀 에러 클래스 -- `src/types/` - 공용 타입 정의 -- `src/constants/` - 상수 관리 (queryKeys, storageKeys, status, eventName, api, snsConfig 등) - -### API 레이어 패턴 - -API는 `src/apis/utils/apiHelpers.ts`의 헬퍼 함수를 사용하는 일관된 패턴을 따름: - -- `handleResponse()` - 응답 파싱, `{ data: {...} }` 형식 자동 언래핑 -- `secureFetch()` - 인증된 요청, 403 시 토큰 자동 갱신 - -쿼리 키는 `src/constants/queryKeys.ts`에 중앙 관리. - -### 인증 플로우 - -- JWT는 localStorage에 저장 (`accessToken` 키, `src/constants/storageKeys.ts`에서 관리) -- 리프레시 토큰은 쿠키로 처리 -- `src/apis/auth/secureFetch.ts`의 `secureFetch()`가 자동 토큰 갱신 담당 -- 어드민 라우트는 `PrivateRoute` 컴포넌트로 보호 - -### 실험(A/B 테스트) 프레임워크 - -`src/experiments/`에서 Mixpanel 기반 실험 관리: - -- `definitions.ts` - 실험 정의 (key, variants, weights) -- `ExperimentRepository.ts` - 실험 할당 및 변형 조회 로직 -- `initializeExperiments.ts` - 앱 시작 시 실험 초기화 -- `useExperiment()` 훅으로 컴포넌트에서 실험 변형 사용 - -**예시**: - -```typescript -const { variant } = useExperiment(mainBannerExperiment); -// variant는 'A' 또는 'B' -``` - -### MSW (Mock Service Worker) - -`src/mocks/`에서 API 모킹 관리: - -- `handlers/` - 도메인별 모킹 핸들러 -- `browser.ts` - MSW 브라우저 워커 설정 -- Storybook 및 개발 환경에서 사용 - -### 주요 유틸리티 함수 - -`src/utils/`에 공용 유틸리티 함수 모음: - -- `formatRelativeDateTime.ts` - 상대적 시간 표시 ("2시간 전") -- `recruitmentDateParser.ts` - 모집 기간 파싱 -- `debounce.ts` - 디바운스 함수 -- `validateSocialLink.ts` - SNS 링크 유효성 검사 -- `isInAppWebView.ts` - 인앱 WebView 감지 -- `webviewBridge.ts` - 네이티브 앱과 통신 -- `initSDK.ts` - 외부 SDK 초기화 (Mixpanel, Sentry, Channel.io, Kakao) - -### 반응형 브레이크포인트 - -`src/styles/mediaQuery.ts`에 정의: - -- mini_mobile: 375px -- mobile: 500px -- tablet: 700px -- laptop: 1280px -- Desktop: 1280px 초과 (기본값) - -### 테마 시스템 - -테마는 `src/styles/theme/`에 colors, typography, transitions로 정의. styled-components `ThemeProvider`를 통해 접근. - -### 상수 관리 - -`src/constants/`에 모든 상수 중앙 관리: - -- `queryKeys.ts` - React Query 쿼리 키 (도메인.액션 형식) -- `storageKeys.ts` - localStorage 키 (`accessToken`, `hasConsentedPersonalInfo`) -- `status.ts` - 지원 상태 정의 (PENDING, APPROVED, REJECTED 등) -- `eventName.ts` - Mixpanel 이벤트명 -- `api.ts` - API 엔드포인트 URL -- `snsConfig.ts` - SNS 플랫폼 설정 -- `applicationForm.ts` - 지원서 폼 설정 -- `uploadLimit.ts` - 파일 업로드 제한 - -### 실시간 업데이트 - -지원자 상태 업데이트를 위해 SSE(Server-Sent Events) 사용, `AdminClubContext`에서 관리. - -### 날짜 처리 - -- `date-fns` 라이브러리 사용 (Moment.js 대신) -- `formatRelativeDateTime` 유틸로 상대 시간 표시 -- `react-datepicker` 컴포넌트로 날짜 입력 - -### 애니메이션 - -- `framer-motion` 라이브러리로 페이지 전환, 모달, 제스처 등 애니메이션 구현 -- `src/styles/theme/transitions.ts`에 공통 트랜지션 정의 - -### 캐러셀 - -- `swiper` 라이브러리로 이미지 슬라이더, 카드 캐러셀 구현 - -## 테스트 - -- Jest + React Testing Library -- MSW로 API 모킹 -- 테스트 파일은 `*.test.ts` 또는 `*.test.tsx` 형식 -- 커버리지 리포트: `npm run coverage` - -## Storybook - -- 컴포넌트 독립 개발 환경 -- MSW addon으로 API 모킹 지원 -- Chromatic으로 시각적 회귀 테스트 - ## Claude Code Agent `.claude/agents/` 디렉토리에 전담 agent 정의: @@ -209,11 +42,13 @@ const { variant } = useExperiment(mainBannerExperiment); Agent 사용 시 해당 문서를 참조하여 일관된 패턴 유지. -## 코딩 컨벤션 +--- + +## 도메인별 상세 문서 -- **네이밍**: camelCase (변수, 함수), PascalCase (컴포넌트, 타입) -- **파일명**: 컴포넌트는 PascalCase.tsx, 유틸은 camelCase.ts -- **Import 순서**: 외부 라이브러리 → 내부 모듈 → 타입 → 스타일 -- **스타일**: styled-components 사용, 테마 시스템 활용 -- **타입**: any 금지, 명시적 타입 정의 -- **상수**: UPPER_SNAKE_CASE, `src/constants/`에서 관리 +@docs/claude/architecture.md +@docs/claude/api.md +@docs/claude/ui.md +@docs/claude/testing.md +@docs/claude/features.md +@docs/claude/conventions.md diff --git a/frontend/docs/claude/api.md b/frontend/docs/claude/api.md new file mode 100644 index 000000000..745dc37f5 --- /dev/null +++ b/frontend/docs/claude/api.md @@ -0,0 +1,39 @@ +# API & 인증 + +## API 레이어 패턴 + +API는 `src/apis/utils/apiHelpers.ts`의 헬퍼 함수를 사용하는 일관된 패턴을 따름: + +- `handleResponse()` - 응답 파싱, `{ data: {...} }` 형식 자동 언래핑 +- `secureFetch()` - 인증된 요청, 401 시 토큰 자동 갱신 + +쿼리 키는 `src/constants/queryKeys.ts`에 중앙 관리. + +## 인증 플로우 + +- JWT는 localStorage에 저장 (`accessToken` 키, `src/constants/storageKeys.ts`에서 관리) +- 리프레시 토큰은 쿠키로 처리 +- `src/apis/auth/secureFetch.ts`의 `secureFetch()`가 자동 토큰 갱신 담당 +- 어드민 라우트는 `PrivateRoute` 컴포넌트로 보호 + +## 외부 서비스 통합 + +- **Mixpanel**: 사용자 분석 및 이벤트 트래킹 +- **Sentry**: 에러 모니터링 및 성능 추적 +- **Channel.io**: 고객 지원 채팅 +- **Kakao SDK**: 카카오 공유 기능 + +모든 SDK는 `src/utils/initSDK.ts`에서 초기화되며, 각각 환경 변수 필요. + +## 상수 관리 + +`src/constants/`에 모든 상수 중앙 관리: + +- `queryKeys.ts` - React Query 쿼리 키 (도메인.액션 형식) +- `storageKeys.ts` - localStorage 키 (`accessToken`, `hasConsentedPersonalInfo`) +- `status.ts` - 지원 상태 정의 (PENDING, APPROVED, REJECTED 등) +- `eventName.ts` - Mixpanel 이벤트명 +- `api.ts` - API 엔드포인트 URL +- `snsConfig.ts` - SNS 플랫폼 설정 +- `applicationForm.ts` - 지원서 폼 설정 +- `uploadLimit.ts` - 파일 업로드 제한 diff --git a/frontend/docs/claude/architecture.md b/frontend/docs/claude/architecture.md new file mode 100644 index 000000000..d2f6a0a75 --- /dev/null +++ b/frontend/docs/claude/architecture.md @@ -0,0 +1,46 @@ +# 아키텍처 + +## 기술 스택 + +- React 19 + TypeScript +- Vite 번들러 (webpack 설정도 있으나 Vite가 주력) +- styled-components 스타일링 +- TanStack React Query v5 서버 상태 관리 +- Zustand 클라이언트 상태 관리 +- React Router v7 +- date-fns 날짜 처리 +- Framer Motion 애니메이션 +- Swiper 캐러셀 +- react-datepicker 날짜 선택 +- react-markdown 마크다운 렌더링 + +## 환경 변수 + +`.env` 파일에 다음 환경 변수 설정 필요 (모두 `VITE_` 접두사 사용): + +- `VITE_API_URL` - 백엔드 API URL +- `VITE_MIXPANEL_TOKEN` - Mixpanel 프로젝트 토큰 +- `VITE_SENTRY_DSN` - Sentry DSN +- `VITE_SENTRY_RELEASE` - Sentry 릴리즈 버전 +- `VITE_ENABLE_SENTRY_IN_DEV` - 개발 환경에서 Sentry 활성화 여부 (true/false) +- `VITE_CHANNEL_PLUGIN_KEY` - Channel.io 플러그인 키 +- `VITE_KAKAO_JAVASCRIPT_KEY` - Kakao JavaScript 키 + +## 프로젝트 구조 + +**경로 별칭**: `@/*`는 `src/*`로 매핑 + +**주요 디렉토리**: + +- `src/apis/` - 도메인별 API 함수 (club, auth, application, applicants) +- `src/hooks/Queries/` - API를 래핑하는 React Query 훅 (useClub, useApplication, useApplicants) +- `src/store/` - Zustand 스토어 (useCategoryStore, useSearchStore) +- `src/pages/` - 라우트 기반 페이지 컴포넌트 +- `src/components/` - 공용 UI 컴포넌트 +- `src/context/` - React Context 프로바이더 (AdminClubContext - SSE 상태 관리) +- `src/experiments/` - A/B 테스트 실험 정의 및 관리 +- `src/mocks/` - MSW(Mock Service Worker) 핸들러 +- `src/utils/` - 유틸리티 함수 (날짜 파싱, 유효성 검사, 디바운스, WebView 브릿지 등) +- `src/errors/` - 커스텀 에러 클래스 +- `src/types/` - 공용 타입 정의 +- `src/constants/` - 상수 관리 (queryKeys, storageKeys, status, eventName, api, snsConfig 등) diff --git a/frontend/docs/claude/conventions.md b/frontend/docs/claude/conventions.md new file mode 100644 index 000000000..f3cfb0acc --- /dev/null +++ b/frontend/docs/claude/conventions.md @@ -0,0 +1,18 @@ +# 코딩 컨벤션 + +## 네이밍 + +- 변수, 함수: camelCase +- 컴포넌트, 타입: PascalCase +- 파일명: 컴포넌트는 PascalCase.tsx, 유틸은 camelCase.ts +- 상수: UPPER_SNAKE_CASE + +## Import 순서 + +외부 라이브러리 → 내부 모듈 → 타입 → 스타일 + +## 스타일 + +- styled-components 사용, 테마 시스템 활용 +- `any` 금지, 명시적 타입 정의 +- 상수는 `src/constants/`에서 관리 diff --git a/frontend/docs/claude/features.md b/frontend/docs/claude/features.md new file mode 100644 index 000000000..0a92498a2 --- /dev/null +++ b/frontend/docs/claude/features.md @@ -0,0 +1,31 @@ +# 주요 기능 + +## 실험(A/B 테스트) 프레임워크 + +`src/experiments/`에서 Mixpanel 기반 실험 관리: + +- `definitions.ts` - 실험 정의 (key, variants, weights) +- `ExperimentRepository.ts` - 실험 할당 및 변형 조회 로직 +- `initializeExperiments.ts` - 앱 시작 시 실험 초기화 +- `useExperiment()` 훅으로 컴포넌트에서 실험 변형 사용 + +```typescript +const { variant } = useExperiment(mainBannerExperiment); +// variant는 'A' 또는 'B' +``` + +## 실시간 업데이트 + +지원자 상태 업데이트를 위해 SSE(Server-Sent Events) 사용, `AdminClubContext`에서 관리. + +## 주요 유틸리티 함수 + +`src/utils/`에 공용 유틸리티 함수 모음: + +- `formatRelativeDateTime.ts` - 상대적 시간 표시 ("2시간 전") +- `recruitmentDateParser.ts` - 모집 기간 파싱 +- `debounce.ts` - 디바운스 함수 +- `validateSocialLink.ts` - SNS 링크 유효성 검사 +- `isInAppWebView.ts` - 인앱 WebView 감지 +- `webviewBridge.ts` - 네이티브 앱과 통신 +- `initSDK.ts` - 외부 SDK 초기화 (Mixpanel, Sentry, Channel.io, Kakao) diff --git a/frontend/docs/claude/testing.md b/frontend/docs/claude/testing.md new file mode 100644 index 000000000..a758dc2de --- /dev/null +++ b/frontend/docs/claude/testing.md @@ -0,0 +1,23 @@ +# 테스트 & Storybook + +## 테스트 + +- Jest + React Testing Library +- MSW로 API 모킹 +- 테스트 파일은 `*.test.ts` 또는 `*.test.tsx` 형식 +- 커버리지 리포트: `npm run coverage` +- 단일 파일 실행: `npx jest path/to/file.test.ts` + +## MSW (Mock Service Worker) + +`src/mocks/`에서 API 모킹 관리: + +- `handlers/` - 도메인별 모킹 핸들러 +- `browser.ts` - MSW 브라우저 워커 설정 +- Storybook 및 개발 환경에서 사용 + +## Storybook + +- 컴포넌트 독립 개발 환경 (포트 6006) +- MSW addon으로 API 모킹 지원 +- Chromatic으로 시각적 회귀 테스트 diff --git a/frontend/docs/claude/ui.md b/frontend/docs/claude/ui.md new file mode 100644 index 000000000..adca95ebd --- /dev/null +++ b/frontend/docs/claude/ui.md @@ -0,0 +1,30 @@ +# UI & 스타일 + +## 반응형 브레이크포인트 + +`src/styles/mediaQuery.ts`에 정의: + +- mini_mobile: 375px +- mobile: 500px +- tablet: 700px +- laptop: 1280px +- Desktop: 1280px 초과 (기본값) + +## 테마 시스템 + +테마는 `src/styles/theme/`에 colors, typography, transitions로 정의. styled-components `ThemeProvider`를 통해 접근. + +## 애니메이션 + +- `framer-motion` 라이브러리로 페이지 전환, 모달, 제스처 등 애니메이션 구현 +- `src/styles/theme/transitions.ts`에 공통 트랜지션 정의 + +## 캐러셀 + +- `swiper` 라이브러리로 이미지 슬라이더, 카드 캐러셀 구현 + +## 날짜 처리 + +- `date-fns` 라이브러리 사용 (Moment.js 대신) +- `formatRelativeDateTime` 유틸로 상대 시간 표시 +- `react-datepicker` 컴포넌트로 날짜 입력