# v3: 개발 환경 설정 - TypeScript 프로젝트 초기화

## 개발 환경 준비

이번 단계에서는 TypeScript 프로젝트를 초기화하고 필요한 패키지들을 설치합니다.

### 필요한 도구

- **Node.js**: v18 이상 (LTS 버전 권장)
- **npm** 또는 **pnpm**: 패키지 관리자
- **텍스트 에디터**: VS Code 권장

### Node.js 버전 확인

```bash
node --version  # v18.0.0 이상
npm --version   # 9.0.0 이상
```

## 프로젝트 초기화

### 1. 프로젝트 디렉토리 생성

```bash
mkdir moneyforward-vertexai-analyzer
cd moneyforward-vertexai-analyzer
```

### 2. npm 프로젝트 초기화

```bash
npm init -y
```

생성된 `package.json`:

```json
{
  "name": "moneyforward-vertexai-analyzer",
  "version": "1.0.0",
  "description": "Money Forward + Vertex AI 재무 분석 도구",
  "main": "dist/index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": ["moneyforward", "vertexai", "finance", "ai"],
  "author": "Your Name",
  "license": "MIT"
}
```

## TypeScript 설정

### 1. TypeScript 및 타입 정의 설치

```bash
npm install -D typescript @types/node tsx
```

- `typescript`: TypeScript 컴파일러
- `@types/node`: Node.js 타입 정의
- `tsx`: TypeScript 실행 도구 (빠른 개발용)

### 2. tsconfig.json 생성

```bash
npx tsc --init
```

또는 수동으로 `tsconfig.json` 생성:

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "moduleResolution": "node",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

### 주요 설정 설명

- `target: "ES2022"`: 최신 JavaScript 기능 사용
- `outDir: "./dist"`: 컴파일된 파일 위치
- `rootDir: "./src"`: 소스 코드 위치
- `strict: true`: 엄격한 타입 체크
- `esModuleInterop: true`: CommonJS 모듈 호환성

## 필요한 패키지 설치

### 1. HTTP 클라이언트

```bash
npm install axios
npm install -D @types/axios
```

Money Forward API 호출에 사용합니다.

### 2. Vertex AI SDK

```bash
npm install @google-cloud/aiplatform
```

Google Cloud Vertex AI 연동에 사용합니다.

### 3. 환경 변수 관리

```bash
npm install dotenv
```

`.env` 파일에서 API 키를 안전하게 불러옵니다.

### 4. 유틸리티 라이브러리

```bash
npm install date-fns        # 날짜 처리
npm install chalk           # 콘솔 출력 색상
```

### 5. 개발 도구

```bash
npm install -D nodemon      # 자동 재시작
npm install -D prettier     # 코드 포맷팅
npm install -D eslint       # 코드 린팅
```

## package.json 스크립트 설정

`package.json`의 `scripts` 섹션 수정:

```json
{
  "scripts": {
    "dev": "tsx src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "watch": "tsx watch src/index.ts",
    "format": "prettier --write \"src/**/*.ts\"",
    "lint": "eslint src --ext .ts"
  }
}
```

### 스크립트 설명

- `npm run dev`: TypeScript를 직접 실행 (개발용)
- `npm run build`: TypeScript → JavaScript 컴파일
- `npm start`: 컴파일된 JavaScript 실행
- `npm run watch`: 파일 변경 시 자동 재실행
- `npm run format`: 코드 자동 포맷팅
- `npm run lint`: 코드 스타일 검사

## 프로젝트 디렉토리 구조

```
moneyforward-vertexai-analyzer/
├── src/
│   ├── moneyforward/
│   │   ├── client.ts          # Money Forward API 클라이언트
│   │   ├── auth.ts             # OAuth 인증 로직
│   │   └── transactions.ts     # 거래 데이터 조회
│   ├── vertexai/
│   │   ├── client.ts           # Vertex AI 클라이언트
│   │   └── analyzer.ts         # 재무 분석 로직
│   ├── utils/
│   │   ├── formatter.ts        # 데이터 포맷팅
│   │   ├── prompt.ts           # AI 프롬프트 템플릿
│   │   └── logger.ts           # 로깅 유틸
│   ├── types/
│   │   ├── moneyforward.ts     # Money Forward 타입
│   │   ├── vertexai.ts         # Vertex AI 타입
│   │   └── index.ts            # 공통 타입
│   └── index.ts                # 메인 엔트리 포인트
├── .tokens/                    # OAuth 토큰 저장 (gitignore)
├── dist/                       # 컴파일된 JavaScript (gitignore)
├── node_modules/               # 의존성 (gitignore)
├── .env                        # 환경 변수 (gitignore)
├── .env.example                # 환경 변수 예시
├── .gitignore
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE
```

### 디렉토리 생성

```bash
mkdir -p src/moneyforward
mkdir -p src/vertexai
mkdir -p src/utils
mkdir -p src/types
mkdir -p .tokens
```

## 환경 변수 파일 설정

### .env.example 파일 생성

```bash
# Money Forward API
MONEYFORWARD_CLIENT_ID=your_client_id_here
MONEYFORWARD_CLIENT_SECRET=your_client_secret_here
MONEYFORWARD_REDIRECT_URI=http://localhost:3000/callback

# Google Cloud Vertex AI
GOOGLE_CLOUD_PROJECT=your-gcp-project-id
GOOGLE_APPLICATION_CREDENTIALS=./service-account-key.json
VERTEX_AI_LOCATION=us-central1
VERTEX_AI_MODEL=gemini-1.5-flash

# Application Settings
NODE_ENV=development
PORT=3000
```

### .env 파일 생성

`.env.example`을 복사하여 `.env` 생성 후 실제 값 입력:

```bash
cp .env.example .env
```

**중요**: `.env` 파일에는 실제 API 키를 입력하고, 절대 Git에 커밋하지 마세요!

## .gitignore 파일 생성

```
# 환경 변수
.env
.env.local
.env.*.local

# OAuth 토큰
.tokens/
tokens.json

# 의존성
node_modules/

# 빌드 결과
dist/
build/
*.tsbuildinfo

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db
.DS_Store?

# 로그
logs/
*.log
npm-debug.log*
yarn-debug.log*
pnpm-debug.log*

# Google Cloud 인증
service-account-key.json
*-key.json
```

## 기본 타입 정의

### src/types/moneyforward.ts

```typescript
/**
 * Money Forward API 응답 타입 정의
 */

export interface MFAccount {
  id: string;
  name: string;
  type: string;
  balance: number;
}

export interface MFTransaction {
  id: string;
  date: string;              // YYYY-MM-DD
  content: string;           // 거래 내용
  amount: number;            // 금액
  is_income: boolean;        // 수입 여부
  category: MFCategory;
  account: MFAccount;
}

export interface MFCategory {
  id: string;
  name: string;
  parent_category?: {
    id: string;
    name: string;
  };
}

export interface MFTokens {
  access_token: string;
  refresh_token: string;
  token_type: string;
  expires_in: number;
  expires_at: number;        // timestamp
}
```

### src/types/vertexai.ts

```typescript
/**
 * Vertex AI 타입 정의
 */

export interface VertexAIConfig {
  projectId: string;
  location: string;
  model: string;
}

export interface VertexAIRequest {
  prompt: string;
  temperature?: number;
  maxOutputTokens?: number;
  topP?: number;
  topK?: number;
}

export interface VertexAIResponse {
  text: string;
  safetyRatings?: Array<{
    category: string;
    probability: string;
  }>;
}
```

### src/types/index.ts

```typescript
/**
 * 공통 타입 정의
 */

export * from './moneyforward';
export * from './vertexai';

export interface FinancialSummary {
  period: {
    from: string;
    to: string;
  };
  totalIncome: number;
  totalExpense: number;
  netChange: number;
  transactionCount: number;
  categoryBreakdown: CategorySummary[];
}

export interface CategorySummary {
  categoryName: string;
  amount: number;
  percentage: number;
  count: number;
}
```

## 메인 엔트리 포인트 생성

### src/index.ts

```typescript
import 'dotenv/config';

async function main() {
  console.log('🚀 Money Forward + Vertex AI 재무 분석 시작');

  // 환경 변수 확인
  const requiredEnvVars = [
    'MONEYFORWARD_CLIENT_ID',
    'MONEYFORWARD_CLIENT_SECRET',
    'GOOGLE_CLOUD_PROJECT',
  ];

  const missingEnvVars = requiredEnvVars.filter(
    (key) => !process.env[key]
  );

  if (missingEnvVars.length > 0) {
    console.error('❌ 누락된 환경 변수:', missingEnvVars.join(', '));
    console.error('💡 .env 파일을 확인하세요');
    process.exit(1);
  }

  console.log('✅ 환경 변수 확인 완료');

  // TODO: v4에서 OAuth 인증 구현
  // TODO: v5에서 거래 데이터 조회 구현
  // TODO: v7에서 Vertex AI 연동 구현
}

main().catch((error) => {
  console.error('❌ 에러 발생:', error);
  process.exit(1);
});
```

## 첫 실행 테스트

### 1. 의존성 설치 확인

```bash
npm install
```

### 2. TypeScript 컴파일 테스트

```bash
npm run build
```

### 3. 실행 테스트

```bash
npm run dev
```

예상 출력:
```
🚀 Money Forward + Vertex AI 재무 분석 시작
✅ 환경 변수 확인 완료
```

또는 환경 변수가 없으면:
```
❌ 누락된 환경 변수: MONEYFORWARD_CLIENT_ID, MONEYFORWARD_CLIENT_SECRET, GOOGLE_CLOUD_PROJECT
💡 .env 파일을 확인하세요
```

## README.md 작성

```markdown
# Money Forward + Vertex AI 재무 분석 도구

Money Forward API로 거래 데이터를 수집하고 Vertex AI로 자동 분석하는 TypeScript 애플리케이션입니다.

## 요구사항

- Node.js v18 이상
- Money Forward 계정 및 API 키
- Google Cloud 계정 및 Vertex AI 접근 권한

## 설치

\`\`\`bash
npm install
\`\`\`

## 환경 설정

\`\`\`bash
cp .env.example .env
# .env 파일에 실제 API 키 입력
\`\`\`

## 실행

\`\`\`bash
npm run dev
\`\`\`

## 빌드

\`\`\`bash
npm run build
npm start
\`\`\`
```

## 체크리스트

v3을 완료하기 전에 다음을 확인하세요:

- [ ] Node.js v18 이상 설치 확인
- [ ] npm 프로젝트 초기화 완료
- [ ] TypeScript 설정 완료 (`tsconfig.json`)
- [ ] 필요한 패키지 모두 설치
- [ ] 프로젝트 디렉토리 구조 생성
- [ ] `.env.example` 파일 생성
- [ ] `.gitignore` 파일 생성
- [ ] 기본 타입 정의 작성
- [ ] `src/index.ts` 엔트리 포인트 생성
- [ ] `npm run dev` 정상 실행 확인

## 다음 단계

v4에서는 Money Forward OAuth 2.0 인증을 구현하여 실제 API에 접근할 수 있도록 합니다.

---

**작성일**: 2025-11-30
**상태**: ✅ 완료
**다음**: v4 - Money Forward OAuth 인증 구현