🌸 수학강사 가계부

사업용·생활용·개인용 지출을 한눈에 관리하는 스마트 가계부입니다. AI가 카테고리를 자동으로 분류하고, 영수증 사진만 찍어도 자동으로 입력돼요!

---

📋 목차

1. 프로젝트 소개
2. 사전 준비
3. 로컬 실행 방법
4. Vercel 배포 방법
5. 사용법
6. 자주 묻는 질문

---

🌷 프로젝트 소개

주요 기능

• 📊 엑셀 형태의 가계부 - 생활용/사업용/개인용 지출 구분 관리
• 🤖 AI 자동 카테고리 분류 - 내역·구매처를 입력하면 Claude AI가 자동으로 카테고리를 추천
• 📸 영수증 OCR - 영수증 사진을 업로드하면 자동으로 항목 추출
• 📁 엑셀 백업/복원 - 언제든 엑셀 파일로 저장하고 다른 기기에서 불러올 수 있음
• 📈 월별 대시보드 - 지출 통계, 카테고리 비율, 일별 추이 차트
• 🔍 필터/검색 - 목적별·카테고리별·금액 범위 등 다양한 필터

기술 스택

• 프레임워크: Next.js 14 (App Router) + TypeScript
• 스타일: Tailwind CSS (파스텔 테마)
• AI: Anthropic Claude API (카테고리 분류, 영수증 OCR)
• 엑셀: SheetJS (xlsx)
• 차트: Recharts
• 상태관리: Zustand (localStorage 자동 저장)

---

🛠️ 사전 준비

아래 4가지를 준비하세요. 모두 무료로 시작할 수 있어요!

1. Node.js 설치

1. nodejs.org 접속
2. LTS 버전 다운로드 및 설치
3. 설치 확인: 터미널(명령 프롬프트)에서 node --version 입력 → 버전 번호가 나오면 OK

2. GitHub 계정 만들기

1. github.com 접속 → Sign up 클릭
2. 이메일·비밀번호로 계정 생성 (무료)

3. Vercel 계정 만들기

1. vercel.com 접속 → Start Deploying 클릭
2. GitHub 계정으로 가입 (무료)

4. Anthropic API 키 발급

1. console.anthropic.com 접속
2. 계정 생성 후 로그인
3. 왼쪽 메뉴에서 API Keys 클릭
4. Create Key 버튼 클릭
5. 생성된 키(sk-ant-...)를 안전한 곳에 복사해두세요

⚠️ API 키는 절대 다른 사람에게 공유하거나 GitHub에 올리지 마세요!

---

💻 로컬 실행 방법

1단계: 코드 다운로드

이 프로젝트 폴더를 원하는 위치에 복사하거나, GitHub에 올렸다면:

git clone https://github.com/본인아이디/budget-app.git
cd budget-app

2단계: 패키지 설치

터미널에서 프로젝트 폴더로 이동 후:

npm install

설치 완료까지 1~2분 정도 걸려요.

3단계: 환경변수 설정

프로젝트 폴더에 .env.local 파일을 만들고 아래 내용을 입력하세요:

ANTHROPIC_API_KEY=sk-ant-여기에본인의API키를붙여넣으세요

.env.local 파일은 .gitignore에 포함되어 있어서 GitHub에 올라가지 않아요. 안전합니다! ✅

4단계: 개발 서버 실행

npm run dev

브라우저에서 http://localhost:3000 접속하면 가계부가 열려요! 🌸

---

🚀 Vercel 배포 방법

1단계: GitHub에 코드 올리기

1. GitHub에서 새 저장소(repository) 만들기
2. 터미널에서:

   git init
   git add .
   git commit -m "첫 커밋 🌸"
   git branch -M main
   git remote add origin https://github.com/본인아이디/budget-app.git
   git push -u origin main
   

2단계: Vercel에서 가져오기

1. vercel.com 로그인
2. Add New Project 클릭
3. GitHub 저장소 목록에서 budget-app 선택 → Import 클릭

3단계: 환경변수 등록

Vercel 배포 화면에서:

1. Environment Variables 항목 클릭
2. Name: ANTHROPIC_API_KEY
3. Value: sk-ant-... (발급받은 API 키)
4. Add 클릭

4단계: 배포!

Deploy 버튼 클릭 → 2~3분 후 완료!

배포된 URL(예: budget-app.vercel.app)로 접속하면 어디서든 가계부를 사용할 수 있어요 🎉

---

📱 사용법

처음 시작

1. 처음 접속하면 환영 모달이 나타나요
2. 설정 바로가기 를 눌러서 지출한 사람(본인 이름 등)을 먼저 등록해요
3. 카테고리 관리에서 기본 카테고리를 확인하고 필요하면 수정해요

지출 추가하기

방법 1: 직접 입력

1. 메인 화면에서 + 새 지출 추가하기 클릭
2. 사용목적·날짜·내역·금액 입력
3. ✨ AI 버튼을 누르면 카테고리 자동 추천
4. 추가하기 클릭

방법 2: 영수증 사진 업로드

1. 상단의 📸 영수증 버튼 클릭
2. 영수증 사진을 드래그하거나 클릭해서 업로드
3. AI가 자동으로 항목을 인식해요 ✨
4. 내용을 확인·수정 후 일괄 추가 클릭

지출 수정하기

• 표에서 셀을 더블클릭하면 바로 수정 가능해요
• Enter 키로 저장, Esc 키로 취소

AI 카테고리 분류

• 내역이나 구매처를 입력하면 AI가 자동으로 적절한 카테고리를 추천해요
• 노란색 ⚠️ 표시가 있으면 AI 확신도가 낮은 것이니 직접 확인해주세요

엑셀 백업·복원

백업 (주 1회 권장)

1. 상단 📤 엑셀 내보내기 클릭
2. 전체 데이터 선택 → 파일 다운로드
3. 구글 드라이브나 USB에 저장해두세요

복원

1. 상단 📥 엑셀 불러오기 클릭
2. 저장해둔 엑셀 파일 선택
3. 병합 (기존 데이터 유지) 또는 덮어쓰기 선택

---

❓ 자주 묻는 질문

Q: API 키 비용은 얼마나 들어요?

영수증 1장당 약 $0.01~$0.03 (한화 1545원) 정도예요. 카테고리 자동 분류는 1회당 약 $0.001$0.005 수준으로 매우 저렴해요. Anthropic 신규 가입 시 무료 크레딧도 주어져요!

Q: 데이터가 사라졌어요!

데이터는 브라우저 localStorage에 저장됩니다.

• 같은 브라우저에서는 새로고침해도 유지돼요
• 브라우저 캐시를 지우면 사라질 수 있어요 ⚠️
• 엑셀 백업을 정기적으로 해두세요! (주 1회 권장)

Q: 다른 기기(스마트폰, 다른 컴퓨터)에서 쓰고 싶어요

엑셀 파일로 내보내기 → 다른 기기에서 불러오기로 데이터를 이동할 수 있어요. 또는 Vercel에 배포한 경우, 같은 URL로 접속하되 데이터는 기기별로 별도 저장됩니다. (데이터 동기화는 엑셀 파일을 통해서만 가능해요)

Q: 브라우저를 바꿨더니 데이터가 없어요

localStorage는 브라우저별로 독립적으로 저장되어요. 이전 브라우저에서 엑셀로 내보내고, 새 브라우저에서 불러오세요.

Q: AI 기능이 작동하지 않아요

.env.local 파일에 ANTHROPIC_API_KEY가 올바르게 입력됐는지 확인해주세요. Vercel 배포 시에는 환경변수를 Vercel 대시보드에도 등록해야 해요.

Q: 카테고리를 추가/수정하고 싶어요

우측 상단 ⚙️ 설정 → 카테고리 관리 탭에서 자유롭게 추가·수정·삭제 가능해요.

---

📝 데이터 보안 안내

• 모든 데이터는 본인의 브라우저(localStorage)에만 저장됩니다
• 서버나 외부로 개인 재무 데이터가 전송되지 않아요
• AI 분류 시에는 내역·구매처·금액 정보만 Anthropic API로 전송됩니다
• .env.local 파일과 API 키는 절대 공개 저장소에 올리지 마세요

---

만든 날짜: 2026년 5월 | 문의: [email protected]