# 젤리의 적자탈출 프로젝트 개선 계획

## 목차

1. [프로젝트 현황 분석](#프로젝트-현황-분석)
2. [주요 개선사항](#주요-개선사항)
3. [기술 스택 개선 계획](#기술-스택-개선-계획)
4. [인증 시스템 개선](#인증-시스템-개선)
5. [CI/CD 도입 계획](#cicd-도입-계획)
6. [프로젝트 관리 도구](#프로젝트-관리-도구)
7. [실행 로드맵](#실행-로드맵)

## 프로젝트 현황 분석

### 프로젝트 개요

- **프로젝트명**: 젤리의 적자탈출 (Zellyy Finance)
- **목적**: 개인 재무/예산 관리 모바일 앱
- **플랫폼**: 웹 + iOS/Android (Capacitor)
- **현재 상태**: Supabase → Appwrite 마이그레이션 완료

### 현재 기술 스택

```
Frontend: React 18 + TypeScript + Vite
UI: Tailwind CSS + shadcn/ui (뉴모픽 디자인)
상태관리: Context API
백엔드: Appwrite (self-hosted)
모바일: Capacitor
```

## 주요 개선사항

### 🔴 긴급 개선 필요 (보안/안정성)

#### 1. TypeScript 설정 강화

```json
// tsconfig.json 수정 필요
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true,
    "noImplicitAny": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}
```

#### 2. 테스트 코드 추가

- 현재 테스트 코드 전무
- Vitest + React Testing Library 도입 필요
- 핵심 비즈니스 로직부터 단위 테스트 작성

#### 3. 보안 취약점 해결

- API 키 클라이언트 노출 문제
- 환경 변수 관리 개선 필요

### 🟡 중요 개선사항 (성능/품질)

#### 4. React 성능 최적화

- React.memo, useMemo, useCallback 활용 부족
- 불필요한 리렌더링 방지 필요
- 세션 체크 주기 최적화 (현재 5초 → 30초)

#### 5. 코드 품질 개선

- console.log 81개 제거
- 빌드 오류 수정
- ESLint 규칙 강화

#### 6. 번들 크기 최적화

- 74개 dependencies 정리
- 사용하지 않는 패키지 제거
- 코드 스플리팅 적용

### 🟢 사용성 개선사항

#### 7. UX 개선

- 스켈레톤 UI 활용도 증대
- 접근성 개선 (ARIA 라벨, 키보드 네비게이션)
- 에러 메시지 사용자 친화적으로 개선

## 기술 스택 개선 계획

### 상태 관리: Context API → Zustand

**현재 (Context API)**

```typescript
const BudgetContext = createContext();
// 복잡한 보일러플레이트 코드
```

**개선 후 (Zustand)**

```typescript
const useBudgetStore = create<BudgetState>((set) => ({
  budgets: [],
  transactions: [],
  addTransaction: (transaction) =>
    set((state) => ({
      transactions: [...state.transactions, transaction],
    })),
}));
```

### 데이터 페칭: 수동 → TanStack Query

**현재**

```typescript
useEffect(() => {
  fetchTransactions().then(setTransactions);
}, []);
```

**개선 후**

```typescript
const { data, isLoading, error } = useQuery({
  queryKey: ["transactions"],
  queryFn: fetchTransactions,
  staleTime: 5 * 60 * 1000,
});
```

### 차트 라이브러리: Recharts → Chart.js

- 번들 크기 감소 (300KB → 100KB)
- 모바일 성능 향상

### 추가 도입 필요 도구

```json
{
  "devDependencies": {
    "prettier": "^3.0.0",
    "husky": "^8.0.0",
    "lint-staged": "^13.0.0",
    "@testing-library/react": "^14.0.0",
    "vitest": "^1.0.0"
  }
}
```

## 인증 시스템 개선

### 현재: Appwrite Auth

- 모든 인증 로직 직접 구현
- 소셜 로그인 구현 복잡
- 고급 기능 구현 어려움

### 권장: Clerk + Supabase 조합

#### Clerk (인증 전문)

```typescript
import { useUser, SignIn } from '@clerk/clerk-react';

function App() {
  const { user, isLoaded } = useUser();
  if (!user) return <SignIn />;
  return <Dashboard user={user} />;
}
```

**장점:**

- 카카오/네이버 로그인 즉시 사용 가능
- 2FA, 생체인증 내장
- 10,000명까지 무료
- 뛰어난 UX/UI 컴포넌트

#### Supabase (데이터베이스)

```typescript
// Clerk JWT를 Supabase에 전달
const supabase = createClient(url, key, {
  global: {
    headers: async () => {
      const token = await getToken({ template: "supabase" });
      return { Authorization: `Bearer ${token}` };
    },
  },
});
```

### 마이그레이션 계획

1. Supabase 프로젝트 생성 및 스키마 설정
2. Clerk 통합 및 JWT 템플릿 구성
3. 데이터 마이그레이션 (Appwrite → Supabase)
4. 점진적 기능 전환

## CI/CD 도입 계획

### GitHub Actions 워크플로우

#### 1. 지속적 통합 (CI)

```yaml
# .github/workflows/ci.yml
name: CI

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main, develop]

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: "18"
          cache: "npm"
      - run: npm ci
      - run: npm run lint
      - run: npx tsc --noEmit
      - run: npm test -- --coverage
      - run: npm run build
```

#### 2. 자동 배포 (CD)

```yaml
# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy-web:
    runs-on: ubuntu-latest
    steps:
      # Vercel 자동 배포
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-args: "--prod"
```

### 브랜치 전략

```
main       → 프로덕션 (자동 배포)
develop    → 스테이징 (자동 배포)
feature/*  → 기능 개발 (PR 체크만)
```

### 추가 통합

- SonarCloud: 코드 품질 분석
- Codecov: 테스트 커버리지 추적
- Sentry: 에러 모니터링

## 프로젝트 관리 도구

### 권장: Task Master AI + Linear 하이브리드

#### Task Master AI (이미 설정됨)

```bash
# AI 기반 태스크 생성
task-master parse-prd .taskmaster/docs/prd.txt --research

# 다음 작업 확인
task-master next

# 상태 업데이트
task-master set-status --id=1.2 --status=done
```

#### Linear (선택적 - 시각적 관리)

- 개발자 친화적 UI
- GitHub 자동 통합
- 무료 티어 충분

### 워크플로우

1. Task Master로 PRD 파싱 → 태스크 자동 생성
2. Linear로 시각적 관리 (필요시)
3. GitHub PR과 자동 연결
4. 진행 상황 추적

## 실행 로드맵

### Phase 1: 즉시 시작 (1주일)

- [ ] TypeScript strict 모드 점진적 활성화
- [ ] console.log 제거 및 빌드 오류 수정
- [ ] ESLint + Prettier 설정
- [ ] GitHub Actions CI 파이프라인 구축
- [ ] 환경 변수 보안 강화

### Phase 2: 핵심 개선 (2-3주)

- [ ] Zustand로 상태 관리 마이그레이션
- [ ] TanStack Query 도입
- [ ] 핵심 비즈니스 로직 테스트 작성
- [ ] React 성능 최적화 (메모이제이션)
- [ ] Vercel 자동 배포 설정

### Phase 3: 고급 기능 (1개월)

- [ ] Clerk 인증 시스템 도입
- [ ] Supabase 데이터베이스 마이그레이션
- [ ] Chart.js로 차트 라이브러리 교체
- [ ] PWA 기능 추가
- [ ] 접근성 개선

### Phase 4: 최적화 (2개월)

- [ ] 번들 크기 최적화
- [ ] 모바일 빌드 자동화
- [ ] 에러 모니터링 (Sentry) 구축
- [ ] 성능 모니터링 도입

## 예상 효과

### 개발 효율성

- 코드 품질 향상으로 버그 감소
- CI/CD로 배포 시간 90% 단축
- 타입 안전성으로 런타임 오류 방지

### 사용자 경험

- 성능 개선으로 앱 속도 2배 향상
- 카카오/네이버 로그인으로 가입률 증가
- 안정성 향상으로 사용자 만족도 개선

### 유지보수성

- 테스트 코드로 리팩토링 안전성 확보
- 모니터링으로 문제 조기 발견
- 문서화로 향후 개발 용이

## 참고 자료

- [Zustand 공식 문서](https://github.com/pmndrs/zustand)
- [TanStack Query 공식 문서](https://tanstack.com/query)
- [Clerk 공식 문서](https://clerk.com/docs)
- [GitHub Actions 가이드](https://docs.github.com/en/actions)
- [Task Master AI](https://github.com/cline/task-master-ai)

---

_이 문서는 젤리의 적자탈출 프로젝트의 기술적 개선을 위한 종합적인 계획서입니다. 각 단계는 프로젝트 상황에 맞게 조정 가능합니다._