# AI 기능

> **상태**: API 구현 완료
> **최종 갱신**: 2026-03-18

---

## 1. 개요

SAM 서비스의 AI 관련 기능을 통합 관리한다. AI 리포트 생성, 토큰 사용량 추적, 비용 계산을 포함한다.

**핵심 기능:**
- 일간/주간/월간 재무 분석 리포트 자동 생성 (Gemini)
- 토큰 사용량 자동 추적 및 비용 계산 (USD/KRW)
- AI 모델별 단가 설정 및 환율 관리
- 저장소(R2) 비용 추적

---

## 2. 모델

| 모델 | 테이블 | 설명 |
|------|--------|------|
| `AiReport` | `ai_reports` | AI 리포트 (유형, 내용, 상태) |
| `AiTokenUsage` | `ai_token_usages` | 토큰 사용량 추적 (모델, 메뉴, 비용) |
| `AiPricingConfig` | `ai_pricing_configs` | AI 모델별 단가 설정 (1시간 캐시) |

---

## 3. AI 리포트

Google Gemini API를 활용한 재무 분석 리포트 자동 생성 시스템. 테넌트의 비즈니스 데이터를 자동 수집하여 AI 기반 분석 리포트를 생성한다.

**리포트 유형:** daily, weekly, monthly

**리포트 상태:** pending → completed / failed

**분석 영역 (6개):** 지출, 매출, 매입, 입출금, 카드/계좌, 미수금

### 3.1 서비스

| 서비스 | 주요 메서드 | 설명 |
|--------|-----------|------|
| `AiReportService` | list | 리포트 목록 (필터: report_type, status, 날짜) |
| | show | 리포트 상세 |
| | generate | 리포트 생성 (데이터 수집 → Gemini API → 저장) |
| | delete | 리포트 삭제 |

### 3.2 API 엔드포인트

| HTTP | URI | 설명 |
|------|-----|------|
| GET | `/v1/reports/ai` | AI 리포트 목록 |
| POST | `/v1/reports/ai/generate` | AI 리포트 생성 |
| GET | `/v1/reports/ai/{id}` | AI 리포트 상세 |
| DELETE | `/v1/reports/ai/{id}` | AI 리포트 삭제 |

---

## 4. AI 토큰 사용량

테넌트별 AI 서비스 사용량을 추적하고 비용을 계산한다. 서비스 사용자가 **설정 > 토큰사용량** 메뉴에서 자기 테넌트의 사용 내역을 확인할 수 있다.

### 4.1 헬퍼

| 클래스 | 메서드 | 용도 |
|--------|--------|------|
| `AiTokenHelper` | `saveGeminiUsage()` | Gemini API 호출 후 토큰 기록 |
| | `saveClaudeUsage()` | Claude API 호출 후 토큰 기록 |
| | `saveR2StorageUsage()` | R2 파일 업로드 비용 기록 |
| | `saveSttUsage()` | STT 사용 시간 비용 기록 |

### 4.2 서비스

| 서비스 | 주요 메서드 | 설명 |
|--------|-----------|------|
| `AiTokenUsageService` | list | 사용량 목록 + 통계 (필터: 기간, 메뉴명) |
| | getPricing | 단가 설정 조회 (읽기 전용) |

### 4.3 API 엔드포인트

| HTTP | URI | 설명 |
|------|-----|------|
| GET | `/v1/settings/ai-token-usage` | 토큰 사용량 목록 + 통계 |
| GET | `/v1/settings/ai-token-usage/pricing` | 단가 설정 조회 |

> 상세 API 명세: [frontend/api-specs/ai-token-usage-api.md](../../frontend/api-specs/ai-token-usage-api.md)

---

## 5. 단가 설정 (AiPricingConfig)

| provider | model_name | 과금 방식 | 용도 |
|----------|-----------|----------|------|
| `gemini` | gemini-2.0-flash | 입력/출력 토큰당 | AI 리포트 등 |
| `claude` | claude-3-haiku | 입력/출력 토큰당 | Claude 호출 |
| `google-stt` | latest_long | 15초당 $0.009 | 음성인식 (MNG) |
| `google-gcs` | cloud-storage | 1000건당 $0.005 | GCS 저장소 (MNG) |
| `cloudflare-r2` | cloud-storage | 1M건당 $0.0045 | R2 저장소 (서비스) |

> 환율 기본값: 1 USD = 1,400 KRW (활성 레코드의 `exchange_rate` 필드)
> 캐시: 1시간 TTL (`ai_pricing_{provider}`)

---

## 6. MNG vs 서비스 차이

| 항목 | MNG (백오피스) | 서비스 (API+React) |
|------|---------------|-------------------|
| 테넌트 범위 | 전체 테넌트 조회 | 자기 테넌트만 |
| 저장소 | GCS | R2 |
| 단가 관리 | 편집 가능 | 조회만 |
| STT 추적 | 있음 | 해당 없음 |

---

## 관련 문서

- [DB 스키마 — 공통](../../system/database/commons.md)
- [프론트엔드 API 명세](../../frontend/api-specs/ai-token-usage-api.md)
- [이관 기획서](../../plans/ai-token-usage-service-migration.md)
- Swagger: `/api-docs` → Reports 섹션

---

**최종 업데이트**: 2026-03-18