docs: [esign] HWR API 비용 및 AI 토큰 사용량 연동 구조 문서화

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과의 공존 전략