Files

김보곤 8cb8bd4c6c docs: [ai] AI 토큰사용량 API 문서화

- features/ai/README.md: 토큰사용량, 단가설정, R2 비용추적 내용 추가
- frontend/api-specs/ai-token-usage-api.md: React 프론트엔드 개발자용 API 명세 신규 작성

2026-03-18 09:49:40 +09:00

4.1 KiB

Raw Blame History

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

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 추적	있음	해당 없음

4.1 KiB Raw Blame History