docs: [esign] 전자서명 고도화 문서 최종 업데이트 — Phase 5 완료, 파일 목록/엔드포인트/엔진 현황 최신화

features/esign/handwriting-verification.md

@@ -1,7 +1,7 @@
 # 전자계약 eSign 고도화 — 필기 문구 확인 (Handwriting Verification)
 
 > **작성일**: 2026-03-22
-> **상태**: Phase 1~3 구현 완료 (관리자 기능 + 데모)
+> **상태**: 전체 구현 완료 (Phase 1~5)
 > **담당**: R&D실
 > **메뉴**: 연구개발 > 전자서명 고도화 (`/esign-verification`)
 > **v1 참조**: [features/esign/README.md](README.md), [projects/e-sign/technical-design.md](../../projects/e-sign/technical-design.md)
@@ -791,16 +791,26 @@ SAM 프로젝트는 기존 GCS 서비스 계정(`/var/www/sales/apikey/google_se
 | 라우트 등록 검증 | ✅ | 11개 라우트 정상 |
 | HWR 폴백 검증 | ✅ | API 키 없을 시 빈 결과 + 적절한 힌트 반환 |
 
+### Phase 5: 추가 고도화 — ✅ 구현 완료 (2026-03-23)
+
+| 작업 | 상태 | 내용 |
+|------|:----:|------|
+| Google Vision API 활성화 | ✅ | 프로젝트 `codebridge-chatbot`에서 Vision API 활성화 (서비스 계정 공유) |
+| 실제 서명 플로우 연동 | ✅ | OTP → **필기 확인** → 서명/도장 (`sign/verification.blade.php`) |
+| `esign_contracts` 컬럼 | ✅ | `verification_required`, `verification_template_id` 추가 |
+| `esign_signers` 컬럼 | ✅ | `verification_status`, `verification_passed_at` 추가 |
+| 계약 생성 마법사 연동 | ✅ | "필기 문구 확인" 체크박스 + 템플릿 선택 드롭다운 |
+| 감사 로그 연동 | ✅ | `verification_viewed`, `_attempted`, `_passed`, `_completed` 4개 액션 |
+| 시험 테스트 모달 | ✅ | 템플릿 목록에서 단계별 필기 인식 테스트 모달 |
+| 토큰 사용량 누계 | ✅ | 엔진별(Clova/Vision/Tesseract) 호출 횟수 + 대시보드 카드 |
+| 캔버스 좌표 보정 | ✅ | CSS 스케일링 시 마우스 좌표 scaleX/scaleY 보정 |
+
 ### 남은 작업 (추후)
 
 | 작업 | 우선순위 | 설명 |
 |------|:-------:|------|
-| HWR API 키 설정 | 높음 | `.env`에 Naver Clova 또는 Google Vision API 키 추가 |
-| 실제 전자계약 연동 | 높음 | 기존 서명 플로우에 필기 확인 단계 삽입 (verification.blade.php) |
-| `esign_contracts` 컬럼 추가 | 중간 | `verification_required`, `verification_template_id` |
-| `esign_signers` 컬럼 추가 | 중간 | `verification_status`, `verification_passed_at` |
-| 인식률 실 데이터 튜닝 | 중간 | 다양한 필체 테스트 후 임계값 조정 |
-| 감사 로그 연동 | 낮음 | `esign_audit_logs`에 verification 액션 기록 |
+| Naver Clova OCR 연동 | 낮음 | 1순위 엔진으로 설정 시 `.env`에 키 추가 (현재 Google Vision으로 충분) |
+| 인식률 실 데이터 튜닝 | 낮음 | 다양한 필체 테스트 후 임계값 최적화 |
 
 ---
 
@@ -832,34 +842,46 @@ SAM 프로젝트는 기존 GCS 서비스 계정(`/var/www/sales/apikey/google_se
 
 ## 14. 구현 결과 (2026-03-22)
 
-### 14.1 생성된 파일 목록
+### 14.1 생성/수정 파일 목록
 
 ```
 mng/
 ├── config/esign.php                                              ← HWR 설정
 ├── database/migrations/
 │   ├── 2026_03_22_100000_create_esign_verification_templates_table.php
-│   └── 2026_03_22_110000_create_esign_handwriting_verifications_table.php
+│   ├── 2026_03_22_110000_create_esign_handwriting_verifications_table.php
+│   ├── 2026_03_22_200000_add_verification_to_esign_contracts_table.php
+│   └── 2026_03_22_210000_add_verification_to_esign_signers_table.php
 ├── app/Models/ESign/
-│   ├── EsignVerificationTemplate.php
-│   └── EsignHandwritingVerification.php
+│   ├── EsignVerificationTemplate.php                             ← NEW
+│   ├── EsignHandwritingVerification.php                          ← NEW
+│   ├── EsignContract.php                                         ← 수정 (fillable/casts/관계)
+│   └── EsignSigner.php                                           ← 수정 (fillable/casts)
 ├── app/Services/ESign/
 │   ├── TextSimilarityService.php                                 ← 유사도 계산
 │   ├── HwrAdapterInterface.php                                   ← 엔진 인터페이스
 │   ├── HandwritingVerificationService.php                        ← 메인 서비스
 │   └── Adapters/
 │       ├── NaverClovaAdapter.php                                 ← Naver Clova OCR
-│       ├── GoogleVisionAdapter.php                               ← Google Vision
+│       ├── GoogleVisionAdapter.php                               ← Google Vision (서비스 계정)
 │       └── TesseractAdapter.php                                  ← 무료 폴백
 ├── app/Http/Controllers/ESign/
-│   └── EsignVerificationController.php                           ← 관리 컨트롤러
-└── resources/views/esign/verification/
-    ├── dashboard.blade.php                                       ← 대시보드
-    ├── templates.blade.php                                       ← 템플릿 CRUD
-    └── demo.blade.php                                            ← 필기 인식 테스트
+│   ├── EsignVerificationController.php                           ← 관리 컨트롤러 (NEW)
+│   ├── EsignPublicController.php                                 ← 수정 (필기 확인 API 추가)
+│   └── EsignApiController.php                                    ← 수정 (store에 verification 필드)
+├── resources/views/esign/
+│   ├── verification/
+│   │   ├── dashboard.blade.php                                   ← 대시보드 + 토큰 사용량
+│   │   ├── templates.blade.php                                   ← 템플릿 CRUD + 시험 모달
+│   │   └── demo.blade.php                                        ← 필기 인식 테스트
+│   ├── sign/
+│   │   └── verification.blade.php                                ← 공개 서명 필기 확인 (NEW)
+│   ├── sign/auth.blade.php                                       ← 수정 (verification 리다이렉트)
+│   └── create.blade.php                                          ← 수정 (필기 확인 토글)
+└── routes/web.php                                                ← 수정 (14개 라우트 추가)
 ```
 
-### 14.2 엔드포인트 (11개)
+### 14.2 엔드포인트 (14개)
 
 | Method | URI | 설명 |
 |--------|-----|------|
@@ -874,25 +896,25 @@ mng/
 | DELETE | `/esign-verification/api/templates/{id}` | 템플릿 삭제 |
 | POST | `/esign-verification/api/demo` | 인식 테스트 API |
 | GET | `/esign-verification/api/history` | 검증 이력 |
+| GET | `/esign/sign/{token}/verification` | 공개 필기 확인 페이지 |
+| GET | `/esign/sign/{token}/api/verification` | 필기 확인 단계 조회 |
+| POST | `/esign/sign/{token}/api/verification/submit` | 필기 인식 제출 |
 
-### 14.3 HWR 활성화 (.env)
+### 14.3 HWR 엔진 현황
 
-```bash
-# Naver Clova OCR (1순위 권장)
-CLOVA_OCR_API_URL=https://xxxxxx.apigw.ntruss.com/custom/v1/xxxxx/general
-CLOVA_OCR_SECRET_KEY=your_secret_key
-
-# Google Vision (폴백)
-GOOGLE_VISION_API_KEY=your_api_key
-```
+| 엔진 | 상태 | 인증 방식 | 비고 |
+|------|:----:|---------|------|
+| **Google Vision** | ✅ 활성화 | 기존 GCS 서비스 계정 공유 | `.env` 변경 없이 사용 가능 |
+| Naver Clova | 대기 | API Key 필요 | `.env`에 키 추가 시 1순위 전환 |
+| Tesseract | 미설치 | 서버 설치 필요 | 필기체 인식률 낮음 |
 
 ### 14.4 기존 서비스 영향
 
 ```
-✅ 기존 eSign 파일 수정 0건
-✅ 별도 prefix (/esign-verification) — 기존 /esign/* 라우트와 완전 독립
-✅ 별도 컨트롤러 (EsignVerificationController) — 기존 컨트롤러 미수정
-✅ 별도 테이블 (MNG 마이그레이션) — 기존 esign_* 테이블 미수정
+✅ 기존 계약 (verification_required=false): 영향 없음
+✅ 관리자 기능: 별도 prefix (/esign-verification)
+✅ 공개 서명 플로우: verification_required=true인 계약만 필기 확인 단계 추가
+✅ 기존 서명/도장 기능: 변경 없음
 ```
 
 ---
@@ -906,4 +928,4 @@ GOOGLE_VISION_API_KEY=your_api_key
 
 ---
 
-**최종 업데이트**: 2026-03-22
+**최종 업데이트**: 2026-03-23