카드 혜택 트래커 (Card Benefit Tracker)
국내 카드 카탈로그를 둘러보고, 내 카드를 담아 지출 패턴에 맞는 최적의 카드를 추천해주는 개인용 웹앱
📌 목차
✨ 주요 기능
- 카드 갤러리: 카드고릴라에서 수집한 1,400여 개 국내 신용/체크카드를 카드명·카드사·종류로 검색/필터링하며 둘러볼 수 있습니다.
- 다중 정렬 옵션: 기본 추천순 외에 연회비 낮은순/높은순, 카드명 가나다순, 최신순 다중 정렬 옵션을 제공하여 원하는 조건의 카드를 빠르게 탐색할 수 있습니다.
- 내 카드 담기 및 백업 관리: 관심 있거나 보유한 카드를 "내 카드"에 담아 관리하고, 담은 카드들의 연회비 합계를 한눈에 확인할 수 있습니다.
- JSON 백업 및 가져오기: 담아둔 내 카드 목록을 JSON 파일로 안전하게 내보내거나, 스키마 유효성 검증을 거쳐 손쉽게 복구 및 불러오기를 수행할 수 있습니다.
- 혜택 시뮬레이터: 카테고리별 예상 월 지출액을 입력하면 맞춤형 혜택을 분석합니다.
- 내 카드 중 추천: 담아둔 카드 중 순혜택(혜택액 − 월 환산 연회비)이 가장 큰 카드와, 카테고리별 최적 카드 조합을 계산합니다.
- 전체 카드 중 추천: 즐겨찾기 여부와 무관하게 카탈로그의 전체 카드를 대상으로 동일하게 계산합니다.
- 지출 프로필 영구 저장 & 슬라이더 스케일링: 설정한 지출 내역은 브라우저 LocalStorage에 영구 보존되며, 전체 예산 슬라이더로 카테고리 비율을 유지한 채 일괄 스케일링하거나 기본값으로 초기화할 수 있습니다.
- 스마트 외부 지출 내역 가져오기: 결제 문자/카드사 알림 텍스트나 영수증 이미지를 업로드하면 지출 항목을 자동으로 카테고리별로 분류해 시뮬레이터에 반영합니다.
- 환불 내역 음수 금액 자동 차감: 결제 취소 및 환불 건(-금액)을 정확히 인식하여 해당 카테고리의 지출 총액에서 자동으로 상쇄 차감합니다.
- 파싱 결과 검토 및 직접 추가/일괄 삭제: 지출 파싱 결과 테이블에서 누락된 결제 내역을 직접 행 추가하거나, 불필요한 항목들을 다중 선택하여 일괄 삭제할 수 있습니다.
- 영수증 파일 용량 및 포맷 사전 검증: 영수증 업로드 시 파일 크기(최대 10MB) 및 지원 확장자(JPEG, PNG, WEBP 등)를 사전에 검증하여 안정적인 파싱을 보장합니다.
- Gemini API Key 보안 스토리지: Gemini 2.0 Flash 기반 고정밀 AI 분석을 위해 API Key를 등록할 수 있으며, 서버 전송 없이 브라우저 로컬 스토리지에 격리 보관 및 마스킹 처리되어 안전하게 관리됩니다 (미등록 시 로컬 규칙 기반 파서로 기본 동작).
🛠 기술 스택 및 선정 이유
Frontend
- Vite + React: 가볍고 빠른 빌드 속도로 즉각적인 화면 렌더링 및 생산성을 높이기 위해 선정.
- TypeScript: 카드 데이터 및 계산 로직 내의 데이터 구조(Type) 안정성 및 오차 예방.
- Tailwind CSS v4:
@tailwindcss/vite 기반으로 빠르고 조화로운 UI 레이아웃 설계.
- Vitest: 계산 로직과 추천 알고리즘의 정확성을 보장하기 위한 단위 테스트 환경 제공.
- @google/generative-ai (Gemini): 지출 내역 텍스트/영수증 이미지에서 상호명·금액·카테고리를 추출하는 AI 분석기에 사용. API Key는 브라우저 LocalStorage에만 저장되며 서버로 전송되지 않습니다.
🏗 아키텍처 및 폴더 구조
유지보수성과 계산 로직의 격리를 고려한 구조 채택. 서버 없이 전부 클라이언트에서 동작하는 SPA입니다.
card-recommend/
├── 📁 data/
│ ├── categories.json # 지출 카테고리 정의 파일
│ ├── 📁 catalog/ # fetch:catalog로 수집한 전체 카드 원본 데이터 (cards-catalog.json)
│ └── 📁 cards/ # (선택) 전월실적 구간까지 직접 구조화한 수동 카드 데이터
├── 📁 src/
│ ├── 📁 contexts/ # 전역 상태 관리 (GeminiApiKeyContext - API Key 로컬 보안 보관)
│ ├── 📁 hooks/ # 커스텀 훅 (useDebounce 등)
│ ├── 📁 types/ # Card, CatalogEntry, SpendingProfile 등 공통 타입 정의
│ ├── 📁 lib/ # 혜택 계산기, 추천 엔진, 지출 파서, myCards(JSON 백업/검증), spendingProfile(영구저장/스케일링)
│ ├── 📁 components/
│ │ ├── 📁 catalog/ # CatalogGallery(카드 갤러리/다중정렬), MyCardsPage(내 카드/백업 UI), CardDetailModal(카드 상세 모달)
│ │ ├── SimulatorPage.tsx # 혜택 시뮬레이터 탭 (내 카드 / 전체 카드 추천, 지출 입력, 결과)
│ │ ├── SpendingSimulator.tsx # 지출 금액 슬라이더 및 전체 예산 스케일링/초기화 컴포넌트
│ │ ├── SpendingImporter.tsx # 외부 지출 내역 가져오기 (데모/텍스트/이미지 영수증 검증 탭)
│ │ ├── ParsedItemsTable.tsx # 지출 파싱 결과 검토/수정, 행 직접 추가 및 일괄 삭제 테이블
│ │ ├── ApiKeySettings.tsx # Gemini API Key 보안 등록/관리 모달 팝오버
│ │ ├── ErrorBoundary.tsx # 전역 런타임 오류 포착 및 안전 복구 폴백 UI
│ │ └── RecommendationResult.tsx # 추천 결과 카드 및 세부 혜택 계산 내역 표시
│ └── App.tsx # 탭 전환 셸 (카드 갤러리 / 내 카드 / 혜택 시뮬레이터)
├── 📁 tests/ # Vitest 단위 테스트 파일 (컴포넌트, 유틸리티, 접근성 검증)
└── 📁 scripts/
├── fetchCardCatalog.ts # 카드고릴라 카탈로그 수집 스크립트
└── validateCardData.ts # data/cards 스키마 유효성 검사 스크립트
데이터 흐름
- 카드 갤러리·내 카드·혜택 시뮬레이터는 모두
data/catalog/cards-catalog.json(카탈로그)을 기준으로 동작합니다.
src/lib/cardConverter.ts가 카탈로그의 자연어 혜택 요약(benefitSummary)을 키워드 매칭으로 파싱해, 계산기가 이해하는 카테고리별 할인/적립률(Card 타입)로 변환합니다. 카탈로그에는 전월실적 구간 정보가 없어, 모든 카탈로그 카드는 실적 조건 없이(0원부터) 혜택이 적용되는 것으로 근사합니다.- 전월실적 구간까지 정확히 반영하고 싶다면 카드 데이터 직접 입력하기를 참고해
data/cards/*.json에 수동으로 작성할 수 있습니다.
🤝 협업 및 자동화 규칙
- Git Branch Strategy:
main 브랜치 직접 커밋 금지, BE-전기헌-(이슈번호) 형태의 Feature 브랜치 전략 준수.
- Commit Message Convention: 규칙적인 이모지 및 태그를 사용한 Conventional Commit 스타일 엄수.
🚀 시작하기
아래 명령어를 통해 프로젝트 패키지를 설치하고 개발 서버를 가동합니다.
npm install
npm run dev
기타 스크립트:
npm run build # 타입 체크 + 프로덕션 빌드
npm run test # Vitest 단위 테스트 실행
npm run test:coverage # Vitest 테스트 커버리지 리포트 생성
npm run lint # oxlint 코드 정적 분석
npm run lint:a11y # jsx-a11y 웹 접근성 정적 분석
npm run fetch:catalog # 카드 카탈로그 수집/갱신
🔄 카드 카탈로그 자동 수집
scripts/fetchCardCatalog.ts는 카드고릴라(card-gorilla.com) 상세 페이지에 SEO용으로 정적 렌더링되는 application/ld+json을 읽어 카드명 / 카드사 / 연회비 / 이미지 URL / 혜택 요약을 data/catalog/cards-catalog.json에 모아줍니다. 앱의 카드 갤러리·내 카드·혜택 시뮬레이터는 이 파일을 기준으로 동작합니다.
npm run fetch:catalog # 전체 카드 수집
npm run fetch:catalog -- --limit=50 # 개수 제한 (테스트용)
- 사이트맵(
sitemap-cards.xml)에서 카드 ID 목록을 가져온 뒤, 요청 간 0.3초 간격을 두고 순회합니다.
- 카드고릴라 이용약관에 크롤링 제한 조항이 있는지 정기적으로 직접 확인하고, 과도한 요청은 피해주세요.
- 이 스크립트는 전월실적 구간별 상세 혜택(
tiers)까지는 수집하지 않으므로, 실적 구간을 정확히 반영하려면 아래 방법으로 직접 작성해야 합니다.
⚡️ 성능 최적화
약 1,400여 개의 대용량 카드 카탈로그 데이터(768KB)를 쾌적하게 렌더링하고 검색하기 위해 다양한 성능 최적화를 적용했습니다.
- 검색 입력 디바운스 (
useDebounce): 입력 반응성은 0ms로 즉각 유지하면서, 250ms 디바운스를 적용하여 1,400여 개 배열의 연속적인 필터링 부하를 대폭 줄였습니다.
- 번들 청크 분할 및 지연 로드 (Code Splitting & Lazy Loading): Vite
manualChunks로 대용량 카탈로그 JSON과 벤더 라이브러리를 분리하고, 서브 페이지를 React.lazy로 지연 로드하여 진입 JS 크기를 **953kB에서 18kB(98.1% 절감)**로 최적화했습니다.
- 네이티브 가상화 & 무한 스크롤: CSS
content-visibility: auto와 IntersectionObserver를 적용하여 반응형 Grid 구조를 유지하면서 뷰포트 밖의 렌더링 비용을 0으로 단축했습니다.
자세한 전/후 벤치마크 및 가상화 비교 분석은 성능 최적화 보고서에서 확인하실 수 있습니다.
