SlipScan
영수증 사진과 카드 명세서 PDF를 올리면 Claude가 거래 내역을 읽어 표로 정리하고, 월별 지출 통계와 보고서를 만드는 웹 앱.
가입할 필요 없습니다. 랜딩의 "시연 계정으로 들어가기" 를 누르면 미리 채워진 대시보드로 바로 들어갑니다.
포트폴리오·데모용 MVP입니다. 실제 회계 업무에 쓰기 위한 것이 아닙니다. 의도적으로 뺀 기능과 알고 감수한 한계는 docs/PRD.md 10절에 전부 적어 두었습니다.
시연 계정은 방문자가 함께 씁니다. 다른 사람이 올린 문서가 섞여 보일 수 있고, 관리자가 가끔 초기 상태로 되돌립니다.
5분 시연 흐름
- "시연 계정으로 들어가기" — 아이디·비밀번호 없이 입장 (서버가 일회용 로그인 표를 발급)
- 대시보드 — 문서 10건, 거래 14행, 지난달 보고서 1건이 미리 들어 있음
- "샘플로 해보기" — 준비된 영수증 1장이 업로드되고 처리가 시작됨
- 결과 확인 — 가맹점·금액·날짜·카테고리가 표로. 그 달 통계에 방금 건이 더해짐
- "이 달 보고서 만들기" — 글이 실시간으로 써지는 것을 봄
초 단위 여정과 화면 문구는 docs/USER_FLOWS.md에 있습니다.
설계에서 신경 쓴 것
| |
|---|
| 브라우저 → 저장소 직접 업로드 | 서버 요청 본문 한도(4.5MB)가 10MB 사진을 막습니다. 파일 본문은 서버를 거치지 않고 Vercel Blob으로 바로 올라갑니다 |
| 숫자는 SQL, 서술만 Claude | 통계 금액·건수는 전부 SQL이 계산합니다. Claude는 그 숫자를 받아 문장만 씁니다. 계산 오류가 원천적으로 없습니다 |
| 구조화 출력 + zod 이중 검증 | 추출은 JSON 스키마로 받고 zod로 한 번 더 검사합니다. 형식이 깨진 응답이 DB로 흘러가지 않습니다 |
| 사용량은 토큰 발급 시점에 기록 | 업로드 허가를 내주는 순간 1회로 셉니다. 토큰만 받아 가는 방식으로 저장소 월 한도를 우회하는 길을 막습니다 |
| 보고서는 스트리밍, 문서는 비동기 | 보고서는 글이 써지는 것이 보여야 해서 동기 스트리밍, 문서 처리는 after() 후처리로 |
| 중복 감지 | 같은 결제가 영수증과 명세서에 함께 들어오면 배지를 붙이고 집계에서 뺍니다 |
모든 조회에 user_id 조건 | 남의 id로 요청하면 404. 예외 없습니다 |
결정의 이유와 검토한 대안은 docs/ARCHITECTURE.md 12절에 ADR 29개로 정리돼 있습니다.
기술 스택
- Next.js 16 (App Router, 루트
app/, 라우트 가드는 proxy.ts) · TypeScript strict
- Tailwind CSS + shadcn/ui — 라이트 전용
- Clerk — 초대 전용(Restricted) 모드, 이메일+비밀번호
- Neon Postgres + Drizzle ORM
- Vercel Blob — 브라우저 직접 업로드
- Claude API (
@anthropic-ai/sdk) — claude-opus-5
- Vitest (단위 278개) · Cypress (화면 3개 시나리오)
- Vercel Hobby 배포, 전 구성요소 싱가포르
sin1
문서
설계 기준(SOT)은 앞의 셋입니다. 어긋나면 PRD가 기준입니다.
| 문서 | 무엇이 들어 있나 |
|---|
docs/PRD.md | 무엇을 만드는가. 범위, 기능, 제외 목록, 감수한 한계 |
docs/ARCHITECTURE.md | 어떻게 만드는가. 구조, 스키마, API, 배포·운영, ADR 29개 |
docs/USER_FLOWS.md | 흐름과 문구. 여정, 유스케이스, 화면 문장, 리허설 체크리스트 |
docs/design.md | 색·글꼴·부품·배치 |
docs/setup.md | 처음부터 직접 띄우는 순서 |
로컬에서 돌려보기
외부 서비스 계정 4개(Vercel·Neon·Clerk·Anthropic)가 필요합니다. 순서는 docs/setup.md에 있습니다.
npm install
cp .env.example .env.local # 값을 채운다 (setup.md 참고)
npm run db:migrate # 테이블 생성
npm run dev
명령어
| |
|---|
npm run dev | 개발 서버 |
npm run build | 프로덕션 빌드 (타입 검사 포함) |
npm run lint | ESLint |
npm run test | Vitest 단일 실행 |
npm run e2e | Cypress (테스트 모드 fixture 사용) |
npm run db:migrate | 마이그레이션 적용 |
npm run seed:demo | 시연 데이터 넣기 (--verify로 확인) |
테스트는 실제 Claude·Blob·Clerk를 호출하지 않습니다. SLIPSCAN_TEST_MODE=1의 fixture를 씁니다.
