diff --git a/features/esign/handwriting-verification.md b/features/esign/handwriting-verification.md index be67cea..da62aa5 100644 --- a/features/esign/handwriting-verification.md +++ b/features/esign/handwriting-verification.md @@ -667,13 +667,13 @@ verification_completed — 모든 단계 통과 ## 10. 설정 (config) ```php -// config/esign.php (추가) +// config/esign.php 'handwriting_verification' => [ - 'enabled' => env('ESIGN_HWR_ENABLED', false), + 'enabled' => env('ESIGN_HWR_ENABLED', true), - // HWR 엔진 우선순위 - 'engine' => env('ESIGN_HWR_ENGINE', 'clova'), // clova, google, tesseract - 'fallback_engine' => env('ESIGN_HWR_FALLBACK', 'google'), + // HWR 엔진 우선순위: clova, google_vision, tesseract + 'engine' => env('ESIGN_HWR_ENGINE', 'clova'), + 'fallback_engine' => env('ESIGN_HWR_FALLBACK', 'google_vision'), // Naver Clova OCR 'clova' => [ @@ -681,16 +681,17 @@ verification_completed — 모든 단계 통과 'secret_key' => env('CLOVA_OCR_SECRET_KEY'), ], - // Google Cloud Vision - 'google' => [ - 'credentials_path' => env('GOOGLE_VISION_CREDENTIALS'), + // Google Cloud Vision (서비스 계정 우선, API Key 폴백) + 'google_vision' => [ + 'credentials_path' => env('GOOGLE_VISION_CREDENTIALS', env('GOOGLE_APPLICATION_CREDENTIALS')), + 'api_key' => env('GOOGLE_VISION_API_KEY'), ], // 검증 설정 - 'default_threshold' => 80.0, // 기본 통과 임계값 (%) - 'max_attempts' => 5, // 최대 시도 횟수 - 'min_strokes' => 5, // 최소 스트로크 수 - 'recognition_timeout' => 5, // 인식 타임아웃 (초) + 'default_threshold' => 80.0, + 'max_attempts' => 5, + 'min_strokes' => 5, + 'recognition_timeout' => 5, // 이미지 전처리 'image_max_width' => 1200, @@ -698,6 +699,56 @@ verification_completed — 모든 단계 통과 ], ``` +### 10.1 Google Cloud Vision API 활성화 절차 (필수) + +> **핵심**: Google Cloud 서비스 계정(API Key)이 있더라도, 개별 API는 프로젝트 수준에서 **별도로 활성화**해야 한다. API Key/서비스 계정은 **인증 수단**이고, API 활성화는 **서비스 사용 권한**이다 — 별개의 개념이다. + +``` +❌ 서비스 계정만 있으면 모든 Google API를 바로 사용 가능 (틀림) +✅ 서비스 계정 + 해당 API 활성화 = 두 가지 모두 필요 +``` + +**활성화 방법**: + +1. Google Cloud Console 접속 +2. 프로젝트 선택: `codebridge-chatbot` (ID: 814841800268) +3. [API 및 서비스] → [라이브러리] → "Cloud Vision API" 검색 +4. **"사용(Enable)" 버튼** 클릭 +5. 활성화 후 수 분 내 적용 + +**직접 링크**: +``` +https://console.developers.google.com/apis/api/vision.googleapis.com/overview?project=codebridge-chatbot +``` + +**CLI 방법** (gcloud 설치 시): +```bash +gcloud services enable vision.googleapis.com --project=codebridge-chatbot +``` + +**현재 SAM 프로젝트에서 활성화된 Google API 목록**: + +| API | 용도 | 상태 | +|-----|------|:----:| +| Vertex AI | AI 기능 (Gemini) | ✅ 기존 | +| Cloud Storage | 파일 저장 (GCS) | ✅ 기존 | +| FCM | 푸시 알림 | ✅ 기존 | +| **Cloud Vision** | **필기 인식 (HWR)** | ✅ 2026-03-23 활성화 | + +### 10.2 인증 우선순위 (GoogleVisionAdapter) + +``` +1순위: 서비스 계정 JSON → OAuth2 Bearer Token + ├─ config('esign.handwriting_verification.google_vision.credentials_path') + ├─ env('GOOGLE_APPLICATION_CREDENTIALS') + └─ config('gcs.service_account_path') ← 기존 GCS 서비스 계정 공유 + +2순위: API Key (폴백) + └─ config('esign.handwriting_verification.google_vision.api_key') +``` + +SAM 프로젝트는 기존 GCS 서비스 계정(`/var/www/sales/apikey/google_service_account.json`)을 공유하므로 **`.env` 변경 없이** Vision API를 사용한다. + --- ## 11. 개발 로드맵