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

[![배포 상태](https://img.shields.io/badge/배포-Vercel-000000?style=flat&logo=vercel)](https://vercel.com)
[![빌드 상태](https://github.com/hansoo./zellyy-finance/workflows/Vercel%20Deployment%20Workflow/badge.svg)](https://github.com/hansoo./zellyy-finance/actions)
[![React](https://img.shields.io/badge/React-18-61DAFB?style=flat&logo=react)](https://reactjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?style=flat&logo=typescript)](https://www.typescriptlang.org/)
[![Vite](https://img.shields.io/badge/Vite-5-646CFF?style=flat&logo=vite)](https://vitejs.dev/)

React와 TypeScript로 구축된 현대적인 개인 가계부 관리 애플리케이션입니다.

## 🚀 라이브 데모

- **프로덕션**: [zellyy-finance.vercel.app](https://zellyy-finance.vercel.app)
- **스테이징**: Preview 배포는 PR 생성 시 자동으로 생성됩니다.

## 🚀 시작하기

이 프로젝트를 로컬 환경에서 설정하고 실행하는 방법입니다.

**사전 요구 사항**

- Node.js (v18 이상)
- npm (v9 이상)

**로컬에서 실행하기**

The only requirement is having Node.js & npm installed - [install with nvm](https://github.com/nvm-sh/nvm#installing-and-updating)

Follow these steps:

```sh
# Step 1: Clone the repository using the project's Git URL.
git clone <YOUR_GIT_URL>

# Step 2: Navigate to the project directory.
cd <YOUR_PROJECT_NAME>

# Step 3: Install the necessary dependencies.
npm i

# Step 4: Start the development server with auto-reloading and an instant preview.
npm run dev
```

**Edit a file directly in GitHub**

- Navigate to the desired file(s).
- Click the "Edit" button (pencil icon) at the top right of the file view.
- Make your changes and commit the changes.

**Use GitHub Codespaces**

- Navigate to the main page of your repository.
- Click on the "Code" button (green button) near the top right.
- Select the "Codespaces" tab.
- Click on "New codespace" to launch a new Codespace environment.
- Edit files directly within the Codespace and commit and push your changes once you're done.

## 🛠️ 주요 기술 스택

- **Backend**: Supabase (Cloud)
- **Frontend**: React, Vite, TypeScript
- **UI**: shadcn-ui, Tailwind CSS
- **State Management**: Zustand, Tanstack Query
- **Deployment**: Vercel

## 🔧 TypeScript 타입 시스템

이 프로젝트는 강력한 타입 안전성을 위해 중앙화된 타입 시스템을 구축했습니다.

### 주요 특징

- **Strict Mode**: 모든 TypeScript strict 옵션 활성화
- **중앙화된 타입**: `src/types/`에서 모든 타입 관리
- **타입 가드**: 런타임 타입 검증 지원
- **성능 최적화**: 조기 반환 및 Set 기반 검증

### 문서

- 📚 [타입 시스템 가이드](./docs/TYPE_SYSTEM_GUIDE.md) - 상세한 사용법과 구조 설명
- ⚡ [빠른 참조](./docs/TYPE_SYSTEM_QUICK_REFERENCE.md) - 자주 사용하는 패턴들

### 타입 검증

```bash
# 타입 오류 검사
npm run type-check

# 또는 직접
npx tsc --noEmit
```

## 🚀 배포 가이드

이 프로젝트는 Vercel을 통해 자동 배포됩니다.

### 자동 배포

- **프로덕션**: `main` 브랜치에 푸시하면 자동으로 프로덕션 배포
- **프리뷰**: PR 생성 시 자동으로 미리보기 배포 생성
- **스테이징**: `develop` 브랜치는 스테이징 환경으로 배포

### 배포 설정

자세한 배포 설정 방법은 [DEPLOYMENT.md](./DEPLOYMENT.md)를 참조하세요.

### 필수 환경 변수

프로젝트를 로컬에서 실행하려면 루트 디렉토리에 `.env` 파일을 생성하고 Supabase 프로젝트의 환경 변수를 추가해야 합니다.

```env
# Supabase
VITE_SUPABASE_URL="YOUR_SUPABASE_URL"
VITE_SUPABASE_ANON_KEY="YOUR_SUPABASE_ANON_KEY"
```

## 🔗 커스텀 도메인

Vercel을 통해 커스텀 도메인을 쉽게 연결할 수 있습니다:

1. Vercel 프로젝트 Settings > Domains
2. 원하는 도메인 입력
3. DNS 설정 업데이트
4. SSL 인증서 자동 설정