# v1: Money Forward + Vertex AI로 재무 자동 분석하기 - 프로젝트 소개

## 프로젝트를 시작하며

안녕하세요! 이번 프로젝트는 **Money Forward API**와 **Google Cloud Vertex AI**를 결합하여 개인/비즈니스 재무 데이터를 자동으로 수집하고 AI로 인사이트를 도출하는 시스템을 만들어보는 여정입니다.

## 왜 이 프로젝트를 시작했나?

많은 사람들이 Money Forward를 사용하여 일상적인 재무 관리를 하고 있습니다. Money Forward 앱은 훌륭하지만, 매일매일의 지출을 사람이 이해하기 쉬운 언어로 분석하고 조언해주는 기능은 제한적입니다.

**"이번 달 지출이 어땠어? 어디서 돈을 많이 썼지?"**

이 간단한 질문에 대한 답을 얻기 위해:
- 앱에 로그인하고
- 여러 차트와 그래프를 확인하고
- 카테고리별 수치를 비교하고
- 머릿속으로 패턴을 분석해야 합니다

만약 AI가 이 모든 과정을 대신 분석하고 자연어로 설명해준다면 어떨까요?

## 프로젝트 목표

이 프로젝트에서 만들 시스템은:

1. **Money Forward API로 거래 데이터 수집**
   - OAuth 2.0 인증을 통한 안전한 데이터 접근
   - 실제 거래 내역, 계좌 정보 조회
   - 카테고리별, 기간별 필터링

2. **TypeScript로 클린한 코드 작성**
   - 타입 안정성 확보
   - 유지보수 가능한 구조
   - 확장 가능한 아키텍처

3. **Vertex AI (Gemini)로 재무 분석**
   - 수치를 사람이 읽기 쉬운 문장으로 변환
   - 지출 패턴과 트렌드 도출
   - 개인화된 재무 조언 제공

## 기술 스택

### Money Forward API
- **역할**: 재무 데이터 수집 및 관리
- **인증 방식**: OAuth 2.0
- **왜 선택했나**: 일본에서 가장 인기 있는 재무 관리 서비스, 강력한 API

### TypeScript
- **역할**: 메인 개발 언어
- **왜 선택했나**: 타입 안정성, 개발 경험 향상, API 응답 타입 정의 용이

### Google Cloud Vertex AI (Gemini)
- **역할**: 재무 데이터 분석 및 인사이트 생성
- **왜 선택했나**:
  - Gemini 모델의 강력한 자연어 이해 능력
  - 대용량 컨텍스트 윈도우 (긴 거래 내역 처리 가능)
  - Google Cloud 통합

### Node.js
- **역할**: 런타임 환경
- **추가 라이브러리**:
  - `axios`: HTTP 클라이언트
  - `@google-cloud/aiplatform`: Vertex AI SDK
  - `dotenv`: 환경 변수 관리

## 예상 결과물

프로젝트가 완성되면 다음과 같은 결과를 얻을 수 있습니다:

```bash
$ npm run analyze -- --month 2025-11

=== 재무 요약 (2025-11-01 ~ 2025-11-30) ===

📊 기본 통계
총 수입: ¥500,000
총 지출: ¥320,000
순자산 변동: +¥180,000
거래 건수: 87건

🤖 Vertex AI (Gemini) 분석

11월 한 달간 총 87건의 거래가 발생했으며, 수입 50만엔,
지출 32만엔으로 18만엔의 흑자를 기록했습니다.

💡 주요 인사이트:
• 식비 지출이 전월 대비 15% 증가했습니다 (¥85,000)
  - 외식 빈도가 늘어난 것으로 보입니다
• 교통비는 재택근무 증가로 20% 감소 (¥12,000)
• 온라인 쇼핑 지출이 크게 늘었습니다 (¥45,000)

📈 개선 제안:
• 식비 절감을 위해 주 2-3회 도시락 준비를 권장합니다
• 사용하지 않는 구독 서비스가 3개 발견되었습니다 (월 ¥2,400)
• 비상금 목표 달성률 90% - 연말까지 목표 달성 가능합니다

🎯 다음 달 목표:
• 식비 목표: ¥70,000 이하
• 저축 목표: ¥200,000
```

## 프로젝트 구조

```
20251130-post-money-forward-vertex-ai/
├── src/
│   ├── moneyforward/
│   │   ├── client.ts          # Money Forward 클라이언트
│   │   ├── auth.ts             # OAuth 인증 처리
│   │   └── transactions.ts     # 거래 데이터 조회
│   ├── vertexai/
│   │   ├── client.ts           # Vertex AI 클라이언트
│   │   └── analyzer.ts         # 재무 분석 요청
│   ├── utils/
│   │   ├── formatter.ts        # 데이터 포맷팅
│   │   └── prompt.ts           # AI 프롬프트 템플릿
│   ├── types/
│   │   └── index.ts            # TypeScript 타입 정의
│   └── index.ts                # 메인 엔트리 포인트
├── .env                        # 환경 변수 (API 키, Secret)
├── .env.example                # 환경 변수 예시
├── package.json
├── tsconfig.json
└── README.md
```

## 학습 목표

이 프로젝트를 통해 다음을 배울 수 있습니다:

1. **Money Forward API 활용**
   - OAuth 2.0 인증 플로우 구현
   - API 엔드포인트 이해 및 호출
   - 거래 데이터 조회 및 필터링

2. **Google Cloud Vertex AI 통합**
   - Vertex AI API 설정 및 인증
   - Gemini 모델 사용법
   - 프롬프트 엔지니어링 (재무 데이터 분석)
   - 대규모 컨텍스트 처리

3. **TypeScript 모범 사례**
   - API 응답 타입 정의
   - 모듈 구조화
   - 환경 변수 관리
   - 에러 핸들링

4. **API 통합 패턴**
   - 여러 외부 API 연동
   - OAuth 2.0 토큰 관리
   - Refresh Token 자동 갱신
   - Rate Limiting 처리

## Money Forward vs Stripe 비교

이전 프로젝트 (Stripe + ChatGPT)와의 차이점:

| 항목 | Stripe | Money Forward |
|------|--------|---------------|
| 인증 방식 | API Key | OAuth 2.0 |
| 데이터 | 결제 데이터 (판매자 관점) | 재무 데이터 (개인 관점) |
| 난이도 | 낮음 | 중간 |
| 실제 사용 | Sandbox 테스트 | 실제 개인 데이터 |

Money Forward는 OAuth 인증이 필요하므로 조금 더 복잡하지만, 실제 개인 재무 데이터를 다룬다는 점에서 더 실용적입니다.

## 주의사항

### 보안
- OAuth Secret과 Access Token은 절대 코드에 하드코딩하지 않기
- `.env` 파일은 `.gitignore`에 추가
- 개인 재무 데이터는 민감 정보 - 절대 공개 저장소에 업로드 금지

### 개인정보 보호
- 실제 거래 데이터를 다루므로 개인정보 보호 중요
- 테스트용 스크린샷은 데이터 마스킹 필수
- 블로그 포스트 작성 시 실제 금액/상점명 변경

### API 제한
- Money Forward API Rate Limit 확인
- Vertex AI 호출 비용 모니터링
- 불필요한 API 호출 최소화

## 다음 단계

v2에서는 Money Forward 계정을 만들고 API 애플리케이션을 등록하여 OAuth 인증 정보를 발급받는 과정을 다룹니다.

준비물:
- [ ] Money Forward 계정 (무료 가입 가능)
- [ ] Google Cloud 계정 (무료 크레딧 제공)
- [ ] Node.js 설치 (v18 이상 권장)
- [ ] TypeScript 기본 지식

---

**작성일**: 2025-11-30
**상태**: ✅ 완료
**다음**: v2 - Money Forward API 계정 설정