zellyy-finance/PROJECT_IMPROVEMENT_PLAN.md

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

목차

1. 프로젝트 현황 분석
2. 주요 개선사항
3. 기술 스택 개선 계획
4. 인증 시스템 개선
5. CI/CD 도입 계획
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 설정 강화

// 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)

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

개선 후 (Zustand)

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

데이터 페칭: 수동 → TanStack Query

현재

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

개선 후

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

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

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

추가 도입 필요 도구

{
  "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 (인증 전문)

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 (데이터베이스)

// 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)

# .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)

# .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 (이미 설정됨)

# 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 공식 문서
• TanStack Query 공식 문서
• Clerk 공식 문서
• GitHub Actions 가이드
• Task Master AI

---

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