From 8772d0af3a4fe4230e553cc04c77053f9f247d27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Mon, 23 Mar 2026 08:24:34 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[esign]=20=EC=A0=84=EC=9E=90=EC=84=9C?= =?UTF-8?q?=EB=AA=85=20=EA=B3=A0=EB=8F=84=ED=99=94=20=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EC=B5=9C=EC=A2=85=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8=20?= =?UTF-8?q?=E2=80=94=20Phase=205=20=EC=99=84=EB=A3=8C,=20=ED=8C=8C?= =?UTF-8?q?=EC=9D=BC=20=EB=AA=A9=EB=A1=9D/=EC=97=94=EB=93=9C=ED=8F=AC?= =?UTF-8?q?=EC=9D=B8=ED=8A=B8/=EC=97=94=EC=A7=84=20=ED=98=84=ED=99=A9=20?= =?UTF-8?q?=EC=B5=9C=EC=8B=A0=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- features/esign/handwriting-verification.md | 86 ++++++++++++++-------- 1 file changed, 54 insertions(+), 32 deletions(-) diff --git a/features/esign/handwriting-verification.md b/features/esign/handwriting-verification.md index da62aa5..a510d2c 100644 --- a/features/esign/handwriting-verification.md +++ b/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