아름드리꿈터 개인예산 관리 앱 (Personal Budgets App)

📋 프로젝트 개요

인증 방식

데모 모드

✨ 주요 기능

당사자 화면

실무자(지원자) 화면

관리자 화면

🏗️ 기술 스택

Frontend

Backend & Database

AI & 외부 서비스

기타 라이브러리

테스트

배포

📁 프로젝트 구조

Personal_Budgets_App/
├── src/
│ ├── app/
│ │ ├── (auth)/
│ │ │ └── login/ # 로그인 (데모 모드 역할 선택 포함)
│ │ ├── (participant)/ # 당사자 화면 (모바일 600px 중심)
│ │ │ ├── page.tsx # 홈 대시보드
│ │ │ ├── calendar/ # 달력 뷰
│ │ │ ├── evaluations/ # 자기 평가
│ │ │ ├── gallery/ # 활동 사진 갤러리
│ │ │ ├── guide/ # 앱 이용 가이드
│ │ │ ├── map/ # 활동 지도
│ │ │ ├── more/ # 더보기 메뉴
│ │ │ ├── my-plan/ # 내 계획 (읽기 전용)
│ │ │ ├── plan/ # 오늘 계획
│ │ │ ├── receipt/ # 영수증 입력
│ │ │ └── settings/profile/ # 프로필 설정
│ │ ├── (supporter)/
│ │ │ ├── admin/ # 관리자 전용
│ │ │ │ ├── page.tsx # 관리자 대시보드
│ │ │ │ ├── feedback/ # 피드백 관리
│ │ │ │ ├── participants/ # 당사자 관리 (목록·상세·신규·프리뷰·보고서)
│ │ │ │ └── settings/ # 시스템 설정
│ │ │ └── supporter/ # 실무자 공통
│ │ │ ├── page.tsx # 실무자 대시보드
│ │ │ ├── [participantId]/transactions/ # 당사자별 거래 장부
│ │ │ ├── budgets/[id]/ # 예산 상세
│ │ │ ├── documents/ # 서류 보관함
│ │ │ │ └── care-plans/[id]/[type]/ # 이용계획서
│ │ │ ├── evaluations/ # 계획·평가
│ │ │ │ └── [participantId]/[month]/ # 월별 평가
│ │ │ │ ├── plans/ # 월별계획
│ │ │ │ └── goals/ # 지원목표
│ │ │ ├── map/ # 활동 지도
│ │ │ ├── participants/ # 당사자 통합 대시보드
│ │ │ ├── review/ # 영수증 검토 대기열
│ │ │ └── transactions/ # 전체 거래 장부
│ │ ├── actions/ # Server Actions (21개)
│ │ │ ├── admin.ts # 관리자 작업
│ │ │ ├── budgetLineItem.ts # 예산 세목
│ │ │ ├── carePlan.ts # 이용계획서
│ │ │ ├── copyPlan.ts # 전월 복사
│ │ │ ├── document.ts # 문서 링크
│ │ │ ├── easyReadSummary.ts # AI 쉬운 요약
│ │ │ ├── evalTemplates.ts # 평가 템플릿
│ │ │ ├── evaluation.ts # 자기 평가
│ │ │ ├── feedback.ts # 피드백
│ │ │ ├── geocode.ts # 주소 → 좌표 변환
│ │ │ ├── goalEvaluation.ts # 목표 평가
│ │ │ ├── importTransactions.ts # CSV 거래 가져오기
│ │ │ ├── monthlyPlan.ts # 월별계획 CRUD
│ │ │ ├── ocr.ts # 영수증 OCR
│ │ │ ├── plan.ts # AI 계획 생성
│ │ │ ├── preferences.ts # UI 환경설정
│ │ │ ├── profile.ts # 프로필 수정
│ │ │ ├── sisAssessment.ts # SIS-A 사정
│ │ │ ├── storage.ts # 파일 스토리지
│ │ │ ├── supportGoal.ts # 지원목표
│ │ │ └── transaction.ts # 거래 CRUD
│ │ └── onboarding/ # 온보딩
│ ├── components/ # 81개 컴포넌트 (13개 카테고리)
│ │ ├── admin/ # 관리자 UI (8개)
│ │ ├── budgets/ # 예산 관리 UI (4개)
│ │ ├── documents/ # 서류 UI (5개)
│ │ ├── evaluations/ # 평가 UI (8개)
│ │ ├── help/ # 도움말 UI (5개)
│ │ ├── home/ # 홈 대시보드 UI (14개)
│ │ ├── layout/ # 레이아웃 (5개)
│ │ ├── map/ # 지도 (2개)
│ │ ├── participants/ # 당사자 관리 UI (2개)
│ │ ├── plans/ # 계획 UI (6개)
│ │ ├── transactions/ # 거래 UI (8개)
│ │ └── ui/ # 공통 UI (4개)
│ ├── hooks/
│ │ ├── useAccessibility.tsx # 7가지 테마 · Easy Read 설정
│ │ ├── useAuth.ts # 인증 상태
│ │ └── useFirstVisit.ts # 첫 방문 감지
│ ├── types/
│ │ └── database.ts # Supabase 자동 생성 타입
│ └── utils/
│ ├── supabase/
│ │ ├── client.ts # 브라우저 클라이언트
│ │ ├── server.ts # 서버 클라이언트 + admin 클라이언트
│ │ └── storage.ts # signed URL 헬퍼
│ ├── activityEmoji.ts
│ ├── api-logger.ts
│ ├── budget-visuals.ts # SVG 시각화 유틸
│ ├── date.ts # KST 타임존 처리
│ ├── emojiCatalog.ts
│ ├── openai.ts # OpenAI 클라이언트
│ ├── sis-a.ts # SIS-A 점수 계산
│ └── tts.ts # 브라우저 TTS
├── supabase/
│ ├── migrations/ # 마이그레이션 파일 (04~30번)
│ ├── schema.sql # 전체 DB 스키마
│ └── seed.sql # 테스트 데이터
└── public/

🗄️ 데이터베이스 마이그레이션

👥 역할(Role) 구조

관리자(Admin)
 └── 지원자(Supporter)
 └── 당사자(Participant)

🚀 개발 단계별 구현 현황

🔧 환경 설정

필수 환경 변수 (.env.local)

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key # 서버 전용, 절대 노출 금지
# 데모 모드 (true = 로그인 없이 체험 가능)
NEXT_PUBLIC_DEMO_MODE=true
# OpenAI (영수증 OCR 및 AI 계획 생성 — 선택사항)
OPENAI_API_KEY=your_openai_api_key
# 카카오맵
NEXT_PUBLIC_KAKAO_MAP_API_KEY=your_kakao_javascript_key # 지도 표시용
KAKAO_REST_API_KEY=your_kakao_rest_api_key # 장소 검색용

개발 서버 실행

npm install
npm run dev # localhost:3000
npm run build # 프로덕션 빌드 (배포 전 확인)
npm run test # Vitest 단위 테스트
npm run lint # ESLint
npm run generate-types # Supabase 타입 재생성

♿ 접근성 (Easy Read)

📸 영수증 OCR 흐름

📊 AI 기능 목록

🔗 관련 링크

기관 담당자용 배포 가이드

준비물 (모두 무료로 시작 가능)

Step 1 — Supabase 프로젝트 만들기

Step 2 — 데이터베이스 테이블 만들기 (마이그레이션)

Step 3 — 필요한 키(Key) 값 메모하기

Supabase API 키

카카오맵 API 키 (2가지 키 필요)

Step 4 — GitHub에 코드 올리기

git init
git add .
git commit -m "initial commit"
git remote add origin https://github.com/사용자명/저장소명.git
git push -u origin main

Step 5 — Vercel에 배포하기

Step 6 — 첫 관리자 계정 만들기

AI 기능 설정

저장 용량 안내

문제 해결