# Money Forward + Vertex AI 구현 요약

## 📅 프로젝트 정보

- **날짜**: 2025-11-30
- **프로젝트**: Money Forward Business API + Vertex AI 재무 분석 도구
- **기술 스택**: TypeScript, pnpm, axios, Vertex AI (Gemini 1.5 Flash)

## 🎯 구현 완료 사항

### 1. OAuth 2.0 인증 (v4)

✅ **성공한 구현**:
- Money Forward Business API OAuth 2.0 인증
- CLIENT_SECRET_BASIC 인증 방식
- Authorization Code Grant 플로우
- Access Token 자동 갱신
- 토큰 파일 저장 (`.tokens/mf-tokens.json`)

**핵심 URL**:
- Authorization: `https://api.biz.moneyforward.com/authorize`
- Token: `https://api.biz.moneyforward.com/token`
- Scope: `mfc/admin/tenant.read`

**발급된 토큰**:
```json
{
  "access_token": "vpKqn9E_9B6yk3ykDDTbp7Gp1ii5da1JfCUI2hPozvc",
  "refresh_token": "zPaqXGDYDo-NYT3OWEKNNCxtL34H7M4q2zIhNpD-ulE",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

### 2. Money Forward API 클라이언트 (v5)

✅ **조회 가능한 데이터**:
- Tenant 정보: `GET /v2/tenant`
  - tenant_code: "1911-2783"
  - tenant_name: "株式会社PlanitAI"

❌ **제한사항**:
- 현재 scope로는 tenant 정보만 조회 가능
- 거래 내역, 계정, 파트너 데이터는 추가 scope 필요

**구현 파일**:
- `src/moneyforward/client.ts` - API 클라이언트
- `src/cli-test-api.ts` - 테스트 CLI

### 3. Vertex AI 클라이언트 (v6-v7)

✅ **구현 완료**:
- Gemini 1.5 Flash 모델 연동
- 재무 분석 프롬프트 엔진
- 구조화된 응답 파싱 (요약/인사이트/권장사항)

**구현 파일**:
- `src/vertexai/client.ts`

⏸️ **Google Cloud 설정 필요**:
- 프로젝트 ID 설정
- Vertex AI API 활성화
- 서비스 계정 키 생성

### 4. 통합 시스템 (v8-v9)

✅ **구현 완료**:
- Money Forward + Vertex AI 완전 통합
- 컬러풀한 CLI 인터페이스 (chalk)
- 에러 핸들링

**메인 파일**:
- `src/index.ts`

## 🔧 주요 트러블슈팅

### 문제 1: 클라이언트 인증 실패
**에러**: "クライアント認証は失敗しました"

**원인**: CLIENT_SECRET_POST를 사용했으나 Business API는 CLIENT_SECRET_BASIC 필요

**해결**:
```typescript
// Authorization 헤더에 Base64 인코딩된 credentials 전송
const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
headers: {
  'Authorization': `Basic ${credentials}`
}
```

### 문제 2: axios JSON 변환
**원인**: axios가 객체를 자동으로 JSON으로 변환

**해결**: URLSearchParams 사용
```typescript
const params = new URLSearchParams();
params.append('code', code);
params.append('grant_type', 'authorization_code');
await axios.post(url, params); // form-urlencoded로 전송
```

### 문제 3: Scope 무효
**에러**: "scopeパラメータが設定されていないか無効です"

**원인**: Personal API scope 형식 사용

**해결**: Business API scope 형식 (`mfc/admin/tenant.read`)

### 문제 4: State 파라미터 누락
**원인**: Business API는 state 필수

**해결**:
```typescript
const state = Math.random().toString(36).substring(2, 15);
```

### 문제 5: SSH 포트 포워딩
**원인**: 원격 서버의 OAuth callback을 로컬 브라우저에서 처리 필요

**해결**:
```bash
ssh -L 3000:localhost:3000 user@server.com
```

## 📊 API vs 실제 구현 비교

| 항목 | 원래 계획 (ME API) | 실제 구현 (Business API) |
|------|-------------------|------------------------|
| Base URL | `moneyforward.com` | `api.biz.moneyforward.com` |
| Authorization | `/oauth/authorize` | `/authorize` |
| Token | `/oauth/v2/token` | `/token` |
| Scope | `accounts transactions` | `mfc/admin/tenant.read` |
| 인증 방식 | CLIENT_SECRET_POST | CLIENT_SECRET_BASIC |
| State | 선택 | **필수** |
| 데이터 | 개인 거래 내역 | 사업체 정보 |

## 🚀 실행 명령어

```bash
# 1. OAuth 인증
pnpm run auth

# 2. API 테스트
pnpm run test:api

# 3. AI 분석 (Google Cloud 설정 후)
pnpm run analyze
```

## 📁 주요 파일 구조

```
src/
├── moneyforward/
│   ├── auth.ts           # OAuth 인증 로직
│   ├── client.ts         # API 클라이언트
│   └── oauth-server.ts   # Callback 서버
├── vertexai/
│   └── client.ts         # Vertex AI 클라이언트
├── types/
│   └── index.ts          # TypeScript 타입
├── cli-auth.ts           # OAuth CLI
├── cli-test-api.ts       # API 테스트 CLI
└── index.ts              # 통합 메인 스크립트
```

## 🔗 참고 문서

### Money Forward Business API
- App Portal: https://app-portal.moneyforward.com/apps/
- Developers Guide: https://developers.biz.moneyforward.com/
- GitHub (Expense API): https://github.com/moneyforward/expense-api-doc

### Vertex AI
- Vertex AI 문서: https://cloud.google.com/vertex-ai/docs
- Gemini API: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/gemini

### OAuth 2.0
- RFC 6749: https://datatracker.ietf.org/doc/html/rfc6749
- OAuth 2.0 가이드: https://oauth.net/2/

## 📈 다음 단계

### 단기 (기능 확장)
1. ✅ Tenant 정보 조회
2. ⏸️ 추가 scope 설정 (deal:read, account_item:read 등)
3. ⏸️ 거래 내역 조회 구현
4. ⏸️ 더 상세한 AI 분석 프롬프트

### 중기 (Google Cloud 설정)
1. ⏸️ Google Cloud 프로젝트 생성
2. ⏸️ Vertex AI API 활성화
3. ⏸️ 서비스 계정 키 생성
4. ⏸️ .env 파일 업데이트

### 장기 (프로덕션)
1. ⏸️ 데이터베이스 토큰 저장
2. ⏸️ 웹 대시보드 구현
3. ⏸️ 정기 분석 스케줄링
4. ⏸️ 리포트 이메일 발송

## 💡 핵심 학습 내용

### Business API의 특징
1. Personal API와 완전히 다른 URL 체계
2. Scope 형식이 다름 (`mfc/` prefix)
3. CLIENT_SECRET_BASIC 인증 필수
4. State 파라미터 필수
5. 서비스별로 다른 Base URL (Expense, Invoice 등)

### OAuth 구현 시 주의사항
1. URLSearchParams로 form-urlencoded 보장
2. Authorization 헤더로 Basic 인증 전달
3. State 파라미터로 CSRF 방지
4. SSH 포트 포워딩으로 로컬 테스트

### Vertex AI 통합
1. 프롬프트 엔지니어링의 중요성
2. 구조화된 응답 파싱
3. 에러 핸들링 및 재시도 로직

## ✅ 테스트 결과

### OAuth 인증
- ✅ Authorization URL 생성
- ✅ 브라우저 인증 플로우
- ✅ Authorization Code 수신
- ✅ Access Token 발급
- ✅ Refresh Token 저장
- ✅ 자동 토큰 갱신

### API 호출
- ✅ Tenant 정보 조회 성공
- ✅ Bearer Token 인증 정상 작동
- ❌ 다른 엔드포인트 (scope 제한)

### Vertex AI
- ✅ 클라이언트 초기화
- ✅ 프롬프트 생성
- ⏸️ API 호출 (Google Cloud 설정 필요)

## 📝 환경 변수

```.env
# Money Forward Business API
MONEYFORWARD_CLIENT_ID=189577719042326
MONEYFORWARD_CLIENT_SECRET=QViocLCAx0m1oQvwCT9iuL8qbxIaQPTKwhhIjMgVIWMVG2x7SRmvY1rLZl49krTTztGluW_oQZ8HMmd5HfebIg
MONEYFORWARD_REDIRECT_URI=http://localhost:3000/callback

# Google Cloud Vertex AI (설정 필요)
GOOGLE_CLOUD_PROJECT=실제-프로젝트-ID
GOOGLE_APPLICATION_CREDENTIALS=./service-account-key.json
VERTEX_AI_LOCATION=us-central1
VERTEX_AI_MODEL=gemini-1.5-flash
```

---

**작성일**: 2025-11-30
**작성자**: Claude + User
**프로젝트 상태**: OAuth 인증 완료, API 클라이언트 구현 완료, Vertex AI 통합 완료