전역 후 1년, 내 소비를 아는 AI 비서
비식별화한 KB국민은행 거래내역으로 수입·지출·저축 패턴을 살펴보고 질문하는 개인용
AI 비서입니다. 원본 기준 기간은 2025.08.18~2026.08.18, 거래는 1,116건입니다.
추가·수정·삭제 후의 통계는 현재 데이터에서 다시 계산합니다.
주요 기능
- 빠른 조회: 채팅 화면에서 기간·항목 선택으로 입출금 요약·큰 출금 5건·입출금 내역 확인. AI 호출 없이 서버에서 계산하며 대화 기록에 저장하지 않음
- AI 채팅: 최신 전체·월별 요약을 시스템 프롬프트에 넣어 답변하고 대화를 자동 저장
- 거래 관리: 목록·페이지 이동·추가·수정·삭제, 미분류와 사용자 정의 분류 보존
- 대화 기록: 목록 조회·전체 불러오기·이어서 질문하기·개별 삭제(삭제 전 확인), 별도 저장 API
- 전체 요약: 수입·지출·순증감·평균·최대/최소 거래·최근 추세
- 선택 보너스 — 인사이트·UX 고도화: 월별 그래프·추가 지표·기간 선택·CSV/JSON·다크 모드
기존 Function Calling·MCP 보너스는 제거했습니다. 기본 AI는 도구 호출 없이 컨텍스트
주입 방식으로 동작합니다. 제공된 집계에 없는 가맹점·개별 거래 정보는 추측하지 않도록
안내합니다. AI 답변의 정확성은 실제 배포에서 별도로 검증해야 합니다.
2026-10-03 개별 거래·패턴 분석 확장
전체 거래를 1시간 동안 서버 메모리에 공유 캐시하고 같은 데이터로 요약과 거래 근거를 만듭니다.
빠른 조회·목록·내보내기도 공유하며 거래 CRUD 후에는 무효화합니다.
AI에는 날짜·금액·memo·category 명세, 전체 및 월별 출금 상위, 분류별 합계,
같은 memo·category의 반복 출금 집계를 전달합니다. 질문에 맞는 거래 확인과 연간 패턴·소비 방향
조언을 지원합니다. 기존 분류와 null은 그대로 사용하며 별도 도구 호출은 없습니다.
개별 명세는 최신 날짜순 최대 2,000건·직렬화 행 합계 160,000문자까지 전달하고 생략 건수를
표시합니다. 전체·월별 합계와 순위는 전체 거래에서 계산합니다. 반복 출금은 고정비 후보이며,
한 계좌의 출금·순유입을 실제 소비·저축으로 확정하지 않습니다. 양끝의 일부 월, 비식별화된
상대방, 데이터에 없는 소비 목적도 답변에서 구분하도록 지시합니다.
개별 내역 전달로 AI 입력 토큰·비용·지연이 증가할 수 있습니다. 요약·채팅의 실제 DB 전체
조회도 요청마다 발생합니다. 이번 검증은 합성 데이터와 가짜 DB·AI로 실행한 로컬 검증이며,
실제 AI 답변 품질·응답 시간과 배포 검증은 남아 있습니다. 원본 엑셀·실제 DB는 변경하지 않았습니다.
기술 스택
| 영역 | 구성 |
|---|
| 백엔드 | Python 3.10 이상, FastAPI, Pydantic, uvicorn |
| DB | Firebase Firestore, 서버의 Admin SDK |
| AI | OpenAI 호환 코디세이 프록시, gpt-5.5 |
| 프론트 | HTML/CSS/Vanilla JavaScript, SVG 그래프, 외부 그래프 라이브러리 없음 |
| 배포 | Render 백엔드, Vercel 정적 프론트 |
| 배포 설정 생성 | Node.js 기본 모듈로 API 주소 생성·정적 파일 복사, 프레임워크 없음 |
배포 주소와 현재 검증 범위
위 주소는 기존 배포입니다. 이번 UX 보너스 변경은 로컬 구현·검증 완료, 미커밋·미배포
상태입니다. 실제 Firestore·코디세이 AI·배포 URL 통합 검증까지 끝났다는 뜻이 아닙니다.
Render 무료 서비스는 첫 요청이 지연될 수 있어 전역 대기 안내를 표시합니다.
로컬 실행
백엔드(PowerShell):
cd backend
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
# .env.example을 참고해 backend/.env에 실제 값을 입력
uvicorn main:app --reload
로컬 Swagger에서 API를 확인합니다.
프론트는 frontend/js/config.js의 공개 주소를 로컬 백엔드 주소로 바꾼 뒤 실행합니다.
cd frontend
python -m http.server 5500
로컬 프론트에서 열고, 백엔드의 ALLOWED_ORIGINS에
http://localhost:5500을 포함합니다. 페이지를 파일 더블클릭으로 열지 않습니다.
환경변수
백엔드의 backend/.env 또는 Render 설정에 입력합니다.
기존 MCP_SHARED_SECRET·MCP_ALLOWED_HOSTS는 더 이상 사용하지 않습니다.
Render의 기존 값이나 Claude 커넥터는 코드 변경만으로 삭제되지 않으므로 계정에서 정리합니다.
프론트 Vercel 환경변수:
frontend/build.mjs가 이 값만 dist/js/config.js로 생성합니다. 공개 주소용이며 비밀키를
넣지 않습니다. 빌드 시 값이 없거나 HTTP(S) 주소가 아니면 실패합니다. Vercel에서는 HTTPS만
허용합니다. 환경변수 변경은 새 배포부터 반영됩니다.
배포 설정
| 서비스 | 설정 |
|---|
| Render | Root: backend / Build: pip install -r requirements.txt |
| Render | Start: uvicorn main:app --host 0.0.0.0 --port $PORT |
| Vercel | Root: frontend / Framework: Other |
| Vercel | Build: node build.mjs / Output: dist (vercel.json에 포함) |
Vercel의 기존 빈 Build Command·Output override가 있다면 위 설정과 맞춥니다.
API_BASE_URL을 Production과 필요한 Preview 환경에 각각 등록한 후 재배포합니다.
로컬에서 같은 산출물을 확인하려면:
cd frontend
$env:API_BASE_URL = "http://localhost:8000"
node build.mjs
python -m http.server 5500 --directory dist
설정 방식은 Vercel 빌드 안내와
환경변수 안내를 따릅니다.
보너스 사용 방법과 계산 규칙
- 데이터 요약에서 전체 / 최근 6개월 / 최근 3개월을 선택합니다.
- 선택 기간의 순저축률·월평균 지출·최대 지출 월과 월별 수입·지출 그래프를 확인합니다.
그래프 아래에서 같은 수치를 표로도 볼 수 있습니다. 모바일 그래프는 좌우로 이동합니다.
- CSV 또는 JSON을 골라 선택 기간 거래 다운로드를 누릅니다.
- 우측 상단에서 다크 모드를 전환합니다. 선택은 다음 방문에도 유지됩니다.
기간은 오늘이 아닌 데이터 최신월을 기준으로 합니다. 조회한 summary의 기간 선택은
추가 DB 요청 없이 화면에서 적용하며, 새로고침·화면 재진입은 최신 데이터를 조회합니다.
다운로드는 클릭 시 최신 데이터에서 해당 기간의 모든 거래를 조회합니다. 따라서 다른
곳에서 거래를 변경했다면 화면에 표시된 조회 시점과 다운로드 결과가 다를 수 있습니다.
- 수입: 양수 합계 / 지출: 음수 절댓값 합계 / 순증감: 수입 − 지출
- 순저축률: 순증감 ÷ 수입 × 100. 소수 1자리, 수입 0이면 계산 불가(null). 투자 수익률 아님
- 월평균 지출: 선택 기간 지출 ÷ 월 수. 거래 없는 중간 월도 0원으로 포함
- 최대 지출 월: 지출이 가장 큰 월. 동률이면 먼저 나온 월, 지출 없으면 표시하지 않음
- 첫 달·마지막 달은 부분 월일 수 있으므로 달 전체 실적처럼 해석하지 않음
summary에 monthly, insights, generated_at이 추가되고 기존 응답 필드는 유지됩니다.
GET /api/data/export?format=csv&months=3 또는 format=json&months=all로 내보냅니다.
CSV는 UTF-8 BOM으로 한글을 지원하고 텍스트 수식 실행을 방지합니다. JSON은 타입·null을
보존합니다. 필드는 id/date/value/memo/category이며 원본 엑셀·비밀키는 포함하지 않습니다.
데이터 흐름
거래 CRUD → Firestore data
↓ 요청당 전체 조회 1회
기본 통계 + 월별 통계 + 인사이트
↙ ↘
그래프·기간 선택 시스템 프롬프트 + 질문
↓
코디세이 GPT
↓
대화 자동 저장 → 답변
AI는 1200 토큰 예산을 사용합니다. 빈 length 응답이면 2400으로 한 번만 재시도하고,
계속 비어 있으면 안내 문구를 반환합니다. 이 완화책이 reasoning 문제의 해결 완료를 뜻하지는
않습니다. 채팅 저장 실패는 한 번 재시도한 뒤 실패 응답을 반환합니다.
개인정보·운영 범위
- 원본 엑셀·계정 키·.env·로그는 Git에 넣지 않습니다. 이미 비식별화된 거래만 사용합니다.
- 이름을 숨긴다는 이유로 거래를 삭제하지 않습니다. 실제 데이터 정리·재적재는 별도 작업입니다.
- 내보내기는 DB의 memo를 그대로 사용합니다. 민감한 내용을 새 거래에 입력하지 않습니다.
- 현재 개인 과제용 API에는 사용자 인증이 없습니다. CORS는 인증이 아니므로 공개 주소를
아는 외부 요청도 API에 접근할 수 있습니다. 별도 접근 보호 없이 실제 민감 자료를 추가하면 안 됩니다.
- 거래 캐시는 1시간이며 단일 프로세스에서 조회를 공유합니다. CRUD 후 다음 조회는 전체를 다시 읽습니다.
같은 캐시 유효기간 내 전체 조회 100회는 111,600건 대신 1,116건(99% 감소)을 읽습니다.
대화·CRUD 개별 문서 읽기는 별도입니다. 이미 소진된 할당량은 코드 변경으로 복구되지 않습니다.
- 현재 문서의 Render 시작 명령은 worker 옵션 없는 uvicorn입니다. 인스턴스 1개·프로세스 1개 운영이 전제입니다.
재시작/절전 후 캐시는 사라지고 프로세스·인스턴스끼리 캐시/무효화를 공유하지 않습니다.
콘솔·별도 적재 스크립트 변경은 최대 1시간 늦게 보일 수 있습니다.
- 조회 실패 시 만료 데이터를 숨겨서 반환하지 않고 503 안내를 표시합니다. 60초 오류 대기 중에는 추가 조회하지 않습니다.
구현·오프라인 검증·운영 한계를 확인하세요.
확인한 것과 남은 것
로컬: 기본 CRUD·요약·대화 저장/불러오기, 0건·수입 0·거래 없는 월, CSV/JSON 기간·형식,
CSV 수식 방지, 그래프·표·기간 전환, 다크 모드 유지, 모바일 가로 넘침 없음,
화면 오류·빈 데이터 처리, JavaScript 오류 0건을 확인했습니다. 외부 서비스 연결은 대체한
검증이므로 실제 Firestore 권한·데이터·코디세이 응답·CORS 배포 설정은 재배포 후 확인합니다.
화면 예시
아래 신규 캡처는 로컬 합성 데이터·가짜 AI 응답으로 UI를 확인한 자료입니다.
실제 1,116건 통계 또는 현재 배포 성공의 증거가 아닙니다.
기존 배포 당시 핵심 기능 캡처(현재 변경 전 화면):
제출 전에는 새 버전을 실제 배포하고 질문+답변+요약, 거래 관리, 대화 불러오기를 다시
촬영합니다. 상세 요구사항·작업 기록은 PRD, Task에 있습니다.
