# v6: Vertex AI 연동

## 이번 단계에서 할 일

1. Vertex AI API 설정
2. Gemini 모델 호출 구현
3. 재무 데이터 분석 프롬프트 설계
4. AI 분석 결과 파싱

## 1. Vertex AI 설정

### Google Cloud Console에서 API 활성화

```bash
# gcloud CLI 사용 시
gcloud services enable aiplatform.googleapis.com
```

### 환경 변수 확인 (.env)

```env
GOOGLE_PROJECT_ID=your-project-id
GOOGLE_APPLICATION_CREDENTIALS=./service-account-key.json
VERTEX_AI_LOCATION=asia-northeast1
```

## 2. Vertex AI 클라이언트 (src/vertexai/client.ts)

```typescript
/**
 * Vertex AI (Gemini) 클라이언트
 */

import { VertexAI } from '@google-cloud/vertexai';

export class VertexAIClient {
  private vertexAI: VertexAI;
  private model: string;

  constructor() {
    const projectId = process.env.GOOGLE_PROJECT_ID;
    const location = process.env.VERTEX_AI_LOCATION || 'asia-northeast1';

    if (!projectId) {
      throw new Error('GOOGLE_PROJECT_ID 환경 변수가 설정되지 않았습니다.');
    }

    this.vertexAI = new VertexAI({
      project: projectId,
      location: location,
    });

    this.model = 'gemini-1.5-flash';
  }

  /**
   * 텍스트 생성 요청
   */
  async generateText(prompt: string): Promise<string> {
    const generativeModel = this.vertexAI.getGenerativeModel({
      model: this.model,
      generationConfig: {
        maxOutputTokens: 2048,
        temperature: 0.7,
        topP: 0.8,
        topK: 40,
      },
    });

    const request = {
      contents: [
        {
          role: 'user',
          parts: [{ text: prompt }],
        },
      ],
    };

    const response = await generativeModel.generateContent(request);
    const result = response.response;

    if (result.candidates && result.candidates.length > 0) {
      const content = result.candidates[0].content;
      if (content && content.parts && content.parts.length > 0) {
        return content.parts[0].text || '';
      }
    }

    return '';
  }

  /**
   * JSON 형식으로 응답 요청
   */
  async generateJSON<T>(prompt: string): Promise<T | null> {
    const jsonPrompt = `${prompt}

응답은 반드시 유효한 JSON 형식으로만 해주세요.`;

    const response = await this.generateText(jsonPrompt);

    try {
      // JSON 추출 (```json ... ``` 형식 처리)
      const jsonMatch = response.match(/```json\s*([\s\S]*?)\s*```/);
      const jsonStr = jsonMatch ? jsonMatch[1] : response;
      return JSON.parse(jsonStr.trim());
    } catch (error) {
      console.error('JSON 파싱 실패:', error);
      return null;
    }
  }
}
```

## 3. 재무 AI 분석기 (src/vertexai/analyzer.ts)

```typescript
/**
 * Vertex AI 재무 분석기
 */

import { VertexAIClient } from './client';
import { MonthlySummary, CategoryBreakdown, AIInsight } from '../types';

export class FinancialAIAnalyzer {
  private client: VertexAIClient;

  constructor() {
    this.client = new VertexAIClient();
  }

  /**
   * 종합 재무 분석 요청
   */
  async analyzeFinancials(
    monthlySummaries: MonthlySummary[],
    categoryBreakdown: CategoryBreakdown[],
    annualStats: {
      totalIncome: number;
      totalExpense: number;
      netSavings: number;
      savingsRate: number;
    }
  ): Promise<AIInsight> {
    const prompt = this.buildAnalysisPrompt(
      monthlySummaries,
      categoryBreakdown,
      annualStats
    );

    const response = await this.client.generateJSON<AIInsight>(prompt);

    if (!response) {
      return this.generateDefaultInsight(annualStats, categoryBreakdown);
    }

    return response;
  }
}
```

## 4. 분석 프롬프트 설계

### 프롬프트 구조

```
당신은 전문 재무 분석가입니다. 아래 재무 데이터를 분석하고 인사이트를 제공해주세요.

## 연간 요약
- 총 수입: ¥5,343,495
- 총 지출: ¥4,224,666
- 순 저축: ¥1,118,829
- 저축률: 20.9%

## 월별 데이터
2024-01: 수입 ¥358,432, 지출 ¥352,456
2024-02: 수입 ¥345,678, 지출 ¥298,432
...

## 카테고리별 지출
주거비: ¥1,116,000 (26.4%)
식비: ¥924,000 (21.9%)
...

## 요청사항
다음 JSON 형식으로 분석 결과를 제공해주세요:

{
  "summary": "전체 재무 상태에 대한 2-3문장 요약",
  "keyFindings": ["발견사항1", "발견사항2", "발견사항3"],
  "recommendations": ["제안1", "제안2", "제안3"],
  "monthlyGoals": [
    {"category": "식비", "targetAmount": 70000, "currentAmount": 77000}
  ]
}
```

## 5. AI 응답 예시

```json
{
  "summary": "2024년 연간 저축률 20.9%로 건전한 재무 상태를 유지하고 있습니다. 주거비와 식비가 전체 지출의 약 48%를 차지하며, 식비에서 절감 여지가 있습니다.",
  "keyFindings": [
    "6월과 12월 보너스 시즌에 저축률이 50% 이상으로 크게 상승",
    "식비 중 외식 비중이 35%로 높은 편",
    "구독 서비스(Netflix, Spotify 등) 월 약 ¥4,000 지출"
  ],
  "recommendations": [
    "외식 빈도를 주 3회에서 2회로 줄이면 월 ¥15,000 절약 가능",
    "미사용 구독 서비스 정리 시 월 ¥2,000 절약",
    "대중교통 정기권 활용으로 교통비 10% 절감 가능"
  ],
  "monthlyGoals": [
    {"category": "식비", "targetAmount": 70000, "currentAmount": 77000},
    {"category": "쇼핑", "targetAmount": 25000, "currentAmount": 34333},
    {"category": "엔터테인먼트", "targetAmount": 12000, "currentAmount": 15000}
  ]
}
```

## 6. 테스트 스크립트

### src/test-vertexai.ts

```typescript
import * as dotenv from 'dotenv';
dotenv.config();

import { SheetsClient } from './sheets/client';
import { DataAggregator } from './analysis/aggregator';
import { FinancialAIAnalyzer } from './vertexai/analyzer';

async function main() {
  const spreadsheetId = process.env.TEST_SPREADSHEET_ID;

  if (!spreadsheetId) {
    console.error('❌ TEST_SPREADSHEET_ID가 설정되지 않았습니다.');
    process.exit(1);
  }

  // 1. 데이터 분석
  const client = new SheetsClient();
  const aggregator = new DataAggregator(client);
  const result = await aggregator.runFullAnalysis(spreadsheetId);

  // 2. AI 분석
  console.log('\n🤖 Vertex AI 분석 시작...\n');
  const aiAnalyzer = new FinancialAIAnalyzer();

  const insight = await aiAnalyzer.analyzeFinancials(
    result.monthlySummaries,
    result.categoryBreakdown,
    result.annualStats
  );

  // 3. 결과 출력
  console.log('='.repeat(50));
  console.log('🤖 AI 분석 결과');
  console.log('='.repeat(50));
  console.log('\n📝 요약:');
  console.log(`   ${insight.summary}`);

  console.log('\n🔍 주요 발견사항:');
  insight.keyFindings.forEach((finding, i) => {
    console.log(`   ${i + 1}. ${finding}`);
  });

  console.log('\n💡 개선 제안:');
  insight.recommendations.forEach((rec, i) => {
    console.log(`   ${i + 1}. ${rec}`);
  });

  console.log('\n🎯 월별 목표:');
  insight.monthlyGoals.forEach((goal) => {
    const diff = goal.currentAmount - goal.targetAmount;
    console.log(`   ${goal.category}: ¥${goal.targetAmount.toLocaleString()} (현재 ¥${goal.currentAmount.toLocaleString()}, -¥${diff.toLocaleString()})`);
  });

  console.log('='.repeat(50));
}

main().catch(console.error);
```

### 실행

```bash
npx ts-node src/test-vertexai.ts
```

### 예상 출력

```
📊 재무 분석 시작...

✅ 544건의 거래 데이터 로드
✅ 12개월 요약 계산 완료
✅ 9개 카테고리 분석 완료

🤖 Vertex AI 분석 시작...

==================================================
🤖 AI 분석 결과
==================================================

📝 요약:
   2024년 연간 저축률 20.9%로 건전한 재무 상태를 유지하고 있습니다.
   주거비와 식비가 전체 지출의 약 48%를 차지합니다.

🔍 주요 발견사항:
   1. 6월과 12월 보너스 시즌에 저축률이 크게 상승
   2. 식비 중 외식 비중이 35%로 높은 편
   3. 구독 서비스 월 약 ¥4,000 지출

💡 개선 제안:
   1. 외식 빈도를 줄이면 월 ¥15,000 절약 가능
   2. 미사용 구독 서비스 정리 시 월 ¥2,000 절약
   3. 대중교통 정기권 활용으로 교통비 절감

🎯 월별 목표:
   식비: ¥70,000 (현재 ¥77,000, -¥7,000)
   쇼핑: ¥25,000 (현재 ¥34,333, -¥9,333)
   엔터테인먼트: ¥12,000 (현재 ¥15,000, -¥3,000)
==================================================
```

## 7. Vertex AI 모델 옵션

| 모델 | 특징 | 용도 |
|------|------|------|
| `gemini-1.5-flash` | 빠른 응답, 저비용 | 일반 분석 (권장) |
| `gemini-1.5-pro` | 높은 정확도 | 복잡한 분석 |
| `gemini-1.0-pro` | 안정성 | 레거시 호환 |

## 현재 프로젝트 구조

```
project/src/
├── sheets/
│   ├── client.ts          ✅
│   ├── reader.ts          ✅
│   ├── writer.ts          ✅
│   └── template.ts        ✅
├── analysis/
│   ├── categories.ts      ✅
│   ├── calculator.ts      ✅
│   ├── aggregator.ts      ✅
│   └── validator.ts       ✅
├── vertexai/
│   ├── client.ts          ✅ Vertex AI 클라이언트
│   └── analyzer.ts        ✅ 재무 AI 분석기
├── types/
│   └── index.ts           ✅
└── test-vertexai.ts       ✅
```

## 다음 단계

v7에서는:
- 대시보드 시트 자동 생성
- 요약 정보 레이아웃 배치
- 셀 서식 및 조건부 서식 적용

---

**작성일**: 2025-12-01
**상태**: ✅ 완료
**다음**: v7 - 대시보드 시트 자동 생성