diff --git a/features/esign/handwriting-verification.md b/features/esign/handwriting-verification.md index a510d2c..94d9c81 100644 --- a/features/esign/handwriting-verification.md +++ b/features/esign/handwriting-verification.md @@ -814,17 +814,46 @@ SAM 프로젝트는 기존 GCS 서비스 계정(`/var/www/sales/apikey/google_se --- -## 12. 비용 추정 +## 12. 비용 및 AI 토큰 사용량 추적 -### HWR API 비용 (월간) +### 12.1 HWR API 비용 (월간) | 엔진 | 무료 한도 | 초과 단가 | 예상 월 사용량 | 예상 비용 | |------|----------|----------|:------------:|----------| -| Naver Clova | 300건/월 | ~$0.3/건 | 100~200건 | **무료** | -| Google Vision | 1,000건/월 | $1.5/1,000건 | 폴백 전용 | **무료~$1.5** | +| **Google Vision** (현재 사용) | 1,000건/월 | $1.5/1,000건 | 100~200건 | **무료** | +| Naver Clova | 300건/월 | ~$0.3/건 | — | — | +| Tesseract | 무제한 (로컬) | 무료 | — | — | > **참고**: 전자계약 월 50건 × 평균 2단계 × 평균 2회 시도 = ~200건/월 → 무료 범위 내 +### 12.2 AI 토큰 사용량 연동 (2026-03-23~) + +HWR API 호출 시 **AI 토큰 사용량** 페이지(`/system/ai-token-usage`)에 자동 기록된다. + +| 항목 | 값 | +|------|-----| +| **기록 테이블** | `ai_token_usages` | +| **모델명** | `google-vision` / `naver-clova` / `tesseract` | +| **메뉴명** | `전자서명 고도화` | +| **토큰 단위** | 1건 = 1 token (API 호출 건수 기반) | +| **비용 계산** | Google Vision: $0.0015/건 (≈ 2.1원), Clova: $0.003/건, Tesseract: 무료 | +| **환율** | `ai_pricing_configs` 테이블의 `exchange_rate` 참조 | + +**구현 위치**: `HandwritingVerificationService::recordTokenUsage()` + +```php +// recognizeText() 성공 시 자동 호출 +AiTokenUsage::create([ + 'model' => 'google-vision', + 'menu_name' => '전자서명 고도화', + 'prompt_tokens' => 1, // 호출 1건 = 1 token + 'cost_usd' => 0.0015, // $1.50 / 1,000건 + 'cost_krw' => 2.10, // × 환율 +]); +``` + +> **참고**: 데모 테스트(`/esign-verification/demo`)에서의 호출도 동일하게 기록된다. 실제 전자계약 서명 플로우에서의 호출과 구분 없이 누계로 관리한다. + --- ## 13. 기존 v1과의 공존 전략