# Money Forward + Vertex AI 자동 요약 프로젝트

## 프로젝트 개요

Money Forward API를 활용하여 TypeScript로 거래 데이터를 수집하고, Google Cloud Vertex AI를 통해 재무 데이터를 자동으로 분석하고 요약하는 시스템을 구축합니다.

## 최종 목표

- Money Forward API로 실제 거래 데이터 수집
- TypeScript 기반의 클린한 코드 작성
- Vertex AI(Gemini)를 활용한 재무 인사이트 도출
- 블로그 포스트로 전체 과정 공유

## 기술 스택

- **재무 데이터**: Money Forward API
- **언어**: TypeScript
- **AI 분석**: Google Cloud Vertex AI (Gemini API)
- **런타임**: Node.js
- **주요 라이브러리**: axios, @google-cloud/aiplatform, dotenv

## 단계별 전략 (v1-v10)

### v1: 프로젝트 소개 및 목표
- 프로젝트의 배경과 동기
- 해결하고자 하는 문제
- Money Forward + Vertex AI 조합의 장점
- 사용할 기술 스택 소개
- 예상 결과물

### v2: Money Forward API 소개 및 계정 설정
- Money Forward 서비스 개요
- Money Forward Developers 계정 생성
- API 애플리케이션 등록
- OAuth 2.0 인증 이해하기
- API 키(Client ID/Secret) 발급
- 보안 고려사항

### v3: 개발 환경 설정
- TypeScript 프로젝트 초기화 (`npm init`, `tsconfig.json`)
- 필요한 패키지 설치
  - `axios`: HTTP 클라이언트
  - `@google-cloud/aiplatform`: Vertex AI SDK
  - `dotenv`: 환경 변수 관리
  - `@types/node`: TypeScript 타입 정의
- 프로젝트 디렉토리 구조 설계
- `.env` 파일 설정

### v4: Money Forward OAuth 인증 구현
- OAuth 2.0 Authorization Code Flow 이해
- 인증 URL 생성 및 리다이렉트
- Authorization Code 받기
- Access Token 발급
- Refresh Token 관리
- TypeScript로 인증 클라이언트 구현

### v5: Money Forward API - 거래 데이터 조회
- Transactions API 엔드포인트 이해
- 날짜 범위별 거래 내역 조회
- 계좌별 필터링
- 데이터 구조 파싱
  - 거래 ID, 날짜, 금액
  - 카테고리 정보
  - 계좌 정보
- 페이지네이션 처리

### v6: Google Cloud 및 Vertex AI 설정
- Google Cloud 프로젝트 생성
- Vertex AI API 활성화
- 서비스 계정 생성 및 권한 설정
- JSON 키 파일 다운로드
- 환경변수 설정 (`GOOGLE_APPLICATION_CREDENTIALS`)
- Vertex AI 클라이언트 초기화

### v7: Vertex AI API 연동 및 기본 테스트
- `@google-cloud/aiplatform` SDK 사용법
- Gemini 모델 선택 (1.5 Flash / Pro)
- 기본 텍스트 생성 테스트
- 프롬프트 파라미터 설정
  - temperature: 창의성 조절
  - maxOutputTokens: 출력 길이
- 응답 파싱

### v8: 거래 데이터 전처리 및 프롬프트 작성
- Money Forward 거래 데이터 정제
- AI가 이해하기 쉬운 형식으로 변환
- 효과적인 프롬프트 엔지니어링
  - 재무 요약 요청
  - 카테고리별 분석 요청
  - 지출 패턴 분석
  - 인사이트 및 조언 요청
- 컨텍스트 윈도우 최적화

### v9: 통합 및 자동 요약 실행
- Money Forward 데이터 조회 + Vertex AI 분석 통합
- 전체 워크플로우 구현
  1. Money Forward에서 거래 데이터 가져오기
  2. 데이터 전처리
  3. Vertex AI로 요약 생성
  4. 결과 출력
- 결과 포맷팅 (콘솔 출력, 파일 저장)
- CLI 인터페이스 구현

### v10: 에러 핸들링, 최적화 및 마무리
- API 호출 에러 처리
- Retry 로직 구현
- 토큰 만료 처리
- Rate limiting 고려
- 코드 리팩토링
- 로깅 추가
- README.md 작성
- 배운 점과 개선 사항
- 실전 활용 팁

## 진행 상황

- [ ] v1: 프로젝트 소개 및 목표
- [ ] v2: Money Forward API 소개 및 계정 설정
- [ ] v3: 개발 환경 설정
- [ ] v4: Money Forward OAuth 인증 구현
- [ ] v5: Money Forward API - 거래 데이터 조회
- [ ] v6: Google Cloud 및 Vertex AI 설정
- [ ] v7: Vertex AI API 연동 및 기본 테스트
- [ ] v8: 거래 데이터 전처리 및 프롬프트 작성
- [ ] v9: 통합 및 자동 요약 실행
- [ ] v10: 에러 핸들링, 최적화 및 마무리

## 주의사항

1. **보안**: API 키, OAuth Secret는 절대 GitHub에 커밋하지 않기 (`.env` 파일 사용)
2. **OAuth 인증**: Money Forward는 OAuth 2.0을 사용하므로 토큰 관리가 중요
3. **API 제한**: Money Forward API 호출 횟수 제한 확인
4. **GCP 비용**: Vertex AI API 사용량 모니터링
5. **타입 안정성**: TypeScript의 장점을 최대한 활용
6. **문서화**: 각 단계마다 코드 설명 및 스크린샷 포함

## 예상 결과물

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

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

🤖 Vertex AI 분석

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

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

📈 개선 제안:
• 식비 절감을 위해 주 2-3회 도시락 준비 권장
• 구독 서비스 재검토 (미사용 서비스 해지 고려)
• 비상금 목표 달성률 90% - 연말까지 목표 달성 가능
```

## 완료된 작업

### 2025-11-30: 블로그 문서 업데이트

#### 1. 보안 마스킹 적용
민감한 정보를 마스킹 처리함:

| 항목 | 원본 | 마스킹 후 |
|------|------|-----------|
| Tenant Code | `1911-2783` | `XXXX-XXXX` |
| GCP Project ID | `spatial-cargo-456805-u2` | `your-project-id` |
| 회사명 (출력 예시) | `株式会社PlanitAI` | `株式会社サンプル` |

#### 2. Vertex AI 설정 업데이트
최신 프로젝트 설정에 맞게 문서 업데이트:

| 항목 | 이전 | 업데이트 후 |
|------|------|-------------|
| AI 모델 | `Gemini 1.5 Flash` | `Gemini 2.5 Flash` |
| 리전 | `us-central1` | `asia-northeast1` |
| 모델명 | `gemini-1.5-flash` | `gemini-2.5-flash` |

#### 작업 결과
- `post-money-forward-vertex-ai-ja.md` 파일이 최신 설정으로 업데이트됨
- 보안상 민감한 정보가 마스킹됨
- 문서 내용이 실제 프로젝트 설정과 일치함

## 다음 단계

- 블로그 포스트 발행
- 한국어 버전 작성 (필요시)