ZELLYY/zellyy-finance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4d9effce4103991d40f60c31fcb0ff60e548b277
zellyy-finance/CLAUDE.md
hansoo 4d9effce41 fix: ESLint 오류 수정 - 사용하지 않는 변수들에 underscore prefix 추가 
- AddTransactionButton.tsx: useEffect import 제거
- BudgetProgressCard.tsx: localBudgetData를 _localBudgetData로 변경
- Header.tsx: isMobile을 _isMobile로 변경
- RecentTransactionsSection.tsx: isDeleting을 _isDeleting로 변경
- TransactionCard.tsx: cn import 제거
- ExpenseForm.tsx: useState import 제거
- cacheStrategies.ts: QueryClient, Transaction import 제거
- Analytics.tsx: Separator import 제거, 미사용 변수들에 underscore prefix 추가
- Index.tsx: useMemo import 제거
- Login.tsx: setLoginError를 _setLoginError로 변경
- Register.tsx: useEffect dependency 수정 및 useCallback 추가
- Settings.tsx: toast, handleClick에 underscore prefix 추가
- authStore.ts: setError, setAppwriteInitialized에 underscore prefix 추가
- budgetStore.ts: ranges를 _ranges로 변경
- BudgetProgressCard.test.tsx: waitFor import 제거

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-12 20:49:36 +09:00

251 lines
7.3 KiB
Markdown
Raw Blame History

# Zellyy Finance - 개인 가계부 애플리케이션
## 프로젝트 개요
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. 오프라인 모드
- 네트워크 상태 감지
- 오프라인 데이터 로컬 저장
- 온라인 복구 시 자동 동기화
## 개발 명령어
### 기본 명령어
```bash
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 명령어
```bash
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% 이상
## 환경 변수
개발에 필요한 환경 변수들:
```env
# 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 공식 문서](https://react.dev/)
- [TypeScript 핸드북](https://www.typescriptlang.org/docs/)
- [Tailwind CSS 문서](https://tailwindcss.com/docs)
- [Appwrite 문서](https://appwrite.io/docs)
- [Vitest 문서](https://vitest.dev/)
### 프로젝트 관리
- Task Master AI를 통한 작업 추적
- 이슈 및 버그 리포팅
- 기능 요청 및 개선 사항
---
이 문서는 Zellyy Finance 프로젝트의 개발과 유지보수를 위한 종합 가이드입니다. 프로젝트에 기여하거나 개발을 진행할 때 참조하세요.
Reference in New Issue View Git Blame Copy Permalink