# 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 프로젝트의 개발과 유지보수를 위한 종합 가이드입니다. 프로젝트에 기여하거나 개발을 진행할 때 참조하세요.