zellyy-finance/CLAUDE.md

Zellyy Finance - 개인 가계부 애플리케이션

프로젝트 기본 rule

• 항상 한국어로 말해줘
• 로컬 웹서버는 항상 3000번 포트를 사용하고 사용 중이면 프로세스를 kill한 후에 재실행을 해줘
• MCP는 설치되어 있어 mcp 서버를 설치하려는 시도는 하지 말아줘
• playwright mcp 서버가 설치되어 있으니까 웹브라우저 콘솔 정보를 나에게 요청하지 말고 이것을 활용해줘
• 인터넷으로 최신 정보를 얻을 필요가 있을 때에는 context7 mcp 서버를 활용해줘

프로젝트 개요

Zellyy Finance는 React와 TypeScript로 구축된 개인 가계부 관리 애플리케이션입니다. 사용자가 수입과 지출을 추적하고 예산을 관리할 수 있는 직관적인 웹 애플리케이션입니다.

기술 스택

프론트엔드

• React 18 - 메인 UI 프레임워크
• TypeScript - 타입 안전성 보장
• Vite - 빠른 개발 서버 및 빌드 도구
• Tailwind CSS - 유틸리티 기반 CSS 프레임워크
• Shadcn/ui - 고품질 UI 컴포넌트 라이브러리
• React Router - 클라이언트 사이드 라우팅
• Zustand - 상태 관리

백엔드 및 인증

• Appwrite - 백엔드 서비스 (인증, 데이터베이스)
• React Hook Form - 폼 상태 관리 및 유효성 검사

테스팅

• Vitest - 테스트 러너
• React Testing Library - 컴포넌트 테스팅
• @testing-library/jest-dom - DOM 테스팅 유틸리티

개발 도구

• ESLint - 코드 품질 검사
• Prettier - 코드 포맷팅
• Task Master AI - 프로젝트 관리 및 작업 추적

프로젝트 구조

src/
├── components/          # 재사용 가능한 UI 컴포넌트
│   ├── ui/             # Shadcn/ui 기본 컴포넌트
│   ├── auth/           # 인증 관련 컴포넌트
│   ├── expenses/       # 지출 관리 컴포넌트
│   ├── budget/         # 예산 관리 컴포넌트
│   ├── transaction/    # 거래 관련 컴포넌트
│   ├── notification/   # 알림 컴포넌트
│   ├── offline/        # 오프라인 모드 컴포넌트
│   ├── query/          # 쿼리 관련 컴포넌트
│   └── sync/           # 동기화 컴포넌트
├── contexts/           # React Context API
│   └── budget/         # 예산 관련 컨텍스트
├── hooks/             # 커스텀 React 훅
│   ├── query/         # 쿼리 관련 훅
│   ├── sync/          # 동기화 관련 훅
│   └── transactions/  # 거래 관련 훅
├── lib/               # 라이브러리 및 설정
│   ├── appwrite/      # Appwrite 설정
│   └── query/         # 쿼리 관련 설정
├── pages/             # 페이지 컴포넌트
├── stores/            # Zustand 스토어
├── types/             # TypeScript 타입 정의
├── utils/             # 유틸리티 함수
└── __tests__/         # 테스트 파일

주요 기능

1. 사용자 인증

• 이메일/비밀번호 기반 로그인
• 회원가입 및 계정 관리
• 비밀번호 재설정
• 세션 관리

2. 거래 관리

• 수입/지출 등록 및 편집
• 카테고리별 분류
• 결제 수단 관리
• 거래 내역 검색 및 필터링

3. 예산 관리

• 월간/주간/일간 예산 설정
• 카테고리별 예산 분배
• 예산 대비 지출 현황 시각화
• 예산 초과 알림

4. 분석 및 통계

• 카테고리별 지출 분석
• 결제 수단별 통계
• 월간/연간 트렌드 분석
• 차트 및 그래프 시각화

5. 오프라인 모드

• 네트워크 상태 감지
• 오프라인 데이터 로컬 저장
• 온라인 복구 시 자동 동기화

개발 명령어

기본 명령어

npm run dev          # 개발 서버 시작
npm run build        # 프로덕션 빌드
npm run preview      # 빌드된 파일 미리보기
npm run lint         # ESLint 실행
npm run lint:fix     # ESLint 자동 수정
npm test             # 테스트 실행
npm run test:ui      # 테스트 UI 모드
npm run test:coverage # 테스트 커버리지 확인

Task Master 명령어

task-master next     # 다음 작업 확인
task-master list     # 모든 작업 목록
task-master show <id> # 특정 작업 상세 정보
task-master set-status --id=<id> --status=done # 작업 완료 표시

코딩 컨벤션

TypeScript

• 모든 파일에 엄격한 타입 정의 사용
• any 타입 사용 금지
• 인터페이스와 타입 별칭 적절히 활용
• Enum보다 const assertion 선호

React 컴포넌트

• 함수형 컴포넌트 사용
• Props 인터페이스 명시적 정의
• 커스텀 훅으로 로직 분리
• React.FC 타입 명시적 사용

스타일링

• Tailwind CSS 유틸리티 클래스 사용
• 커스텀 CSS는 최소화
• 반응형 디자인 고려
• 일관된 컬러 팔레트 사용

폴더 및 파일 명명

• 컴포넌트: PascalCase (예: TransactionCard.tsx)
• 훅: camelCase with 'use' prefix (예: useTransactions.ts)
• 유틸리티: camelCase (예: formatCurrency.ts)
• 타입: PascalCase (예: Transaction.ts)

테스트 전략

단위 테스트

• 모든 유틸리티 함수 테스트
• 컴포넌트 렌더링 테스트
• 사용자 상호작용 테스트
• 에러 케이스 테스트

통합 테스트

• API 호출 흐름 테스트
• 상태 관리 통합 테스트
• 라우팅 테스트

테스트 커버리지 목표

• 라인 커버리지: 80% 이상
• 함수 커버리지: 70% 이상
• 브랜치 커버리지: 70% 이상

환경 변수

개발에 필요한 환경 변수들:

# Appwrite 설정
VITE_APPWRITE_URL=https://your-appwrite-url
VITE_APPWRITE_PROJECT_ID=your-project-id
VITE_APPWRITE_DATABASE_ID=your-database-id
VITE_APPWRITE_TRANSACTIONS_COLLECTION_ID=your-collection-id

# 개발 모드 설정
NODE_ENV=development

성능 최적화

현재 적용된 최적화

• React.lazy를 통한 컴포넌트 지연 로딩
• React.memo를 통한 불필요한 리렌더링 방지
• useMemo, useCallback을 통한 계산 최적화
• 이미지 지연 로딩

예정된 최적화

• 번들 크기 최적화
• 코드 스플리팅 개선
• 메모리 사용량 최적화
• 네트워크 요청 최적화

배포 및 CI/CD

배포 환경

• 개발: Vite 개발 서버
• 프로덕션: 정적 파일 빌드 후 호스팅

CI/CD 파이프라인

• 코드 품질 검사 (ESLint, Prettier)
• 자동 테스트 실행
• 타입 체크
• 빌드 검증

문제 해결 가이드

일반적인 문제들

1. Appwrite 연결 오류

   • 환경 변수 확인
   • CORS 설정 검토
   • 네트워크 상태 확인

2. 테스트 실패

   • 모킹 설정 확인
   • 비동기 처리 검토
   • 환경 변수 설정 확인

3. 빌드 오류

   • TypeScript 에러 수정
   • 의존성 버전 확인
   • 환경 변수 설정 검토

기여 가이드

개발 워크플로우

1. 작업 브랜치 생성
2. Task Master에서 작업 선택
3. 코드 작성 및 테스트
4. 코드 리뷰 요청
5. 머지 후 배포

코드 리뷰 체크리스트

• TypeScript 타입 안전성
• 테스트 커버리지
• 성능 최적화
• 접근성 고려
• 보안 검토

추가 리소스

관련 문서

• React 공식 문서
• TypeScript 핸드북
• Tailwind CSS 문서
• Appwrite 문서
• Vitest 문서

프로젝트 관리

• Task Master AI를 통한 작업 추적
• 이슈 및 버그 리포팅
• 기능 요청 및 개선 사항

---

이 문서는 Zellyy Finance 프로젝트의 개발과 유지보수를 위한 종합 가이드입니다. 프로젝트에 기여하거나 개발을 진행할 때 참조하세요.