풀스택
개인 포트폴리오 발표정리
텅~ 장 (Tung~jang)
자영업자를 위한 개인 웹 가계부 서비스 (PWA)
배포 URL: https://budget-3wb.pages.dev
1. 개발 목적
- 자영업자 기준 기존의 카드내역만 출력하는 방식의 가계부는 활용도가 너무 떨어져서 세세한 부분을 직접 컨트롤하고 관리가 편리한 가계부 서비스의 필요성을 알게 되면서 제작
- 카드 청구 기간 기준 정산, 고정지출 자동화, 카드 혜택 매칭까지 한 번에 관리할 수 있는 개인 웹 가계부가 필요해서 직접 제작
- 기존 가계부 앱에는 없는 개인화 기능(수입/지출 계산기, 배송 조회, 자영업자 카드매출 정산 등)까지 포함해 실사용 목적으로 개발
2. 주요 기능
- 거래 입력/관리: 카드 혜택 자동 매칭, 빠른 입력 템플릿, 저장 전 예산 미리보기
- 정산: 일/주/월/연 4단 뷰 (청구 기준 vs 거래일 기준 선택 가능)
- 예산 관리, 고정 수입/지출 자동 생성
- 수입/지출 개인화 계산기, 배송 조회, 자영업자용 카드매출 정산기
- 메모장(이미지 첨부), 통합 검색, 엑셀 내보내기
- 카드 정산 Push 알림, PWA(홈 화면 설치)
3. 기술 스택 (선택 이유)
| 영역 | 기술 | 선택 이유 |
|---|---|---|
| Frontend | React 19 + TypeScript | 화면이 많은 앱을 컴포넌트 단위로 관리 + 타입 안정성 |
| 스타일 | Tailwind CSS v4 | 다크모드·반응형을 빠르게 처리 |
| 빌드 | Vite | 빠른 개발 서버 + PWA 플러그인 지원 |
| 백엔드 | Cloudflare Pages Functions (Edge) | 프론트/API 한 프로젝트 배포, 서버리스라 운영 부담 최소화 Pages Functions가 서버리스 백엔드 역할 |
| DB | Cloudflare D1 (SQLite) | Pages와 같은 생태계라 바로 연동, 가볍고 저비용 |
| 스토리지 | Cloudflare R2 | 카드 이미지(공개)/메모 첨부(비공개) 접근 제어 필요해서 채택 |
| 인증 | PBKDF2 + 세션 쿠키 | 외부 서비스 의존 없이 직접 구현 ("왜 자체 구현했나" → "비용/의존성 줄이려고" + "왜 안전한가" → "PBKDF2 반복 해싱 + salt”) |
| 알림 | Web Push (VAPID) + Service Worker | 앱 설치 없이 브라우저 푸시 알림 구현 |
| 스케줄링 | Cloudflare Workers Cron | 매일 정해진 시간 배치 작업(정산 알림) 처리 |
| 내보내기 | xlsx (SheetJS) | 원금/할인/실결제 분리해서 엑셀 다운로드 |
4. 프론트엔드
컴포넌트 구조
components/하위에 화면 단위 컴포넌트 분리 (TransactionForm, OverviewView, CardManager, BudgetManager, NotesView 등)- 공통 UI는
ui/Card.tsx등으로 재사용
재사용 UI 패턴
- 분류/구매처/결제방법/메모분류처럼 “직접 추가·삭제·순서 변경”이 반복되는 기능은
ReorderableChipList.tsx공용 컴포넌트로 통일
전역 상태 관리 (Context API)
AuthContext: 로그인 상태ThemeContext: 라이트/다크 테마ToastContext: 토스트 알림(Undo 액션 버튼 지원)ConfirmContext: PWA standalone 모드에서window.confirm()이 안 먹는 문제 대응용 커스텀 확인 다이얼로그
API/캐시 레이어 (lib/)
api.ts: 공통 API 호출 + 에러 처리billing.ts,cardDateUtils.ts: 카드 청구 기간 계산 로직categories.ts,merchants.ts,paymentMethods.ts등: 서버 동기화 데이터 캐시exportExcel.ts: 엑셀 내보내기
PWA 처리
sw.ts(커스텀 Service Worker)에서 프리캐시 + Push 알림 핸들러 직접 구현
반응형
- 데스크탑은 상시 사이드바, 모바일은 햄버거+드로어 메뉴
- 모바일 좌우 스와이프로 월/일 이동
5. 백엔드 배포
main브랜치 push 시 GitHub Actions가 자동 빌드 → Cloudflare Pages 배포- 수동 배포:
npm run deploy - DB 마이그레이션은 배포와 별개로
npx wrangler d1 execute직접 실행 필요 - 카드 정산 알림용 Cron Worker는 메인 앱과 별도 프로젝트로 분리 배포 (
workers/card-settlement-notifier, 동일 D1 DB 공유) - 크론 실행 시각: 매일 한국시간 자정, 마감된 카드의 청구기간 사용액을 Push로 발송
