From a5542a762a1d4105e976cde4e8b00c0086d2a610 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Sun, 22 Mar 2026 22:38:17 +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=EA=B8=B0=ED=9A=8D?= =?UTF-8?q?=EC=84=9C=20=E2=80=94=20=EA=B5=AC=ED=98=84=20=EC=99=84=EB=A3=8C?= =?UTF-8?q?=20=EC=83=81=ED=83=9C=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8=20?= =?UTF-8?q?(Phase=201~3,=20=ED=8C=8C=EC=9D=BC=20=EB=AA=A9=EB=A1=9D,=20?= =?UTF-8?q?=EC=97=94=EB=93=9C=ED=8F=AC=EC=9D=B8=ED=8A=B8,=20=EB=82=A8?= =?UTF-8?q?=EC=9D=80=20=EC=9E=91=EC=97=85)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- features/esign/handwriting-verification.md | 139 ++++++++++++++++----- 1 file changed, 109 insertions(+), 30 deletions(-) diff --git a/features/esign/handwriting-verification.md b/features/esign/handwriting-verification.md index e30260a..be67cea 100644 --- a/features/esign/handwriting-verification.md +++ b/features/esign/handwriting-verification.md @@ -1,8 +1,9 @@ # 전자계약 eSign 고도화 — 필기 문구 확인 (Handwriting Verification) > **작성일**: 2026-03-22 -> **상태**: 기획 중 +> **상태**: Phase 1~3 구현 완료 (관리자 기능 + 데모) > **담당**: R&D실 +> **메뉴**: 연구개발 > 전자서명 고도화 (`/esign-verification`) > **v1 참조**: [features/esign/README.md](README.md), [projects/e-sign/technical-design.md](../../projects/e-sign/technical-design.md) --- @@ -701,43 +702,54 @@ verification_completed — 모든 단계 통과 ## 11. 개발 로드맵 -### Phase 1: 핵심 엔진 (2~3주) +### Phase 1: 핵심 엔진 — ✅ 구현 완료 (2026-03-22) -| 작업 | 담당 | 설명 | -|------|------|------| -| DB 마이그레이션 | MNG | 신규 2테이블 + 기존 2테이블 변경 | -| HWR 어댑터 구현 | MNG | Naver Clova + Google Vision 어댑터 | -| TextSimilarityService | MNG | Levenshtein + Jaro-Winkler 유사도 | -| HandwritingVerificationService | MNG | 메인 비즈니스 로직 | -| 이미지 전처리 | MNG | GD/Imagick 기반 전처리 파이프라인 | +| 작업 | 상태 | 파일 | +|------|:----:|------| +| DB 마이그레이션 | ✅ | `mng/database/migrations/2026_03_22_1*` (2개) | +| 모델 | ✅ | `EsignVerificationTemplate`, `EsignHandwritingVerification` | +| HWR 어댑터 | ✅ | `NaverClovaAdapter`, `GoogleVisionAdapter`, `TesseractAdapter` | +| TextSimilarityService | ✅ | Levenshtein + 글자유사도 (한글 mb_str_split 안전) | +| HandwritingVerificationService | ✅ | 메인 비즈니스 로직 (제출/검증/폴백/힌트) | +| config/esign.php | ✅ | HWR 엔진/임계값/시도횟수 설정 | -### Phase 2: 프론트엔드 (1~2주) +### Phase 2: 프론트엔드 — ✅ 구현 완료 (2026-03-22) -| 작업 | 담당 | 설명 | -|------|------|------| -| HandwritingCanvas 클래스 | MNG | 필기 전용 캔버스 (터치/마우스) | -| verification.blade.php | MNG | 필기 확인 페이지 UI | -| 디바이스 최적화 | MNG | 모바일/태블릿/웹 반응형 | -| 인식 결과 UI | MNG | 일치율 표시, 재시도 안내 | +| 작업 | 상태 | 파일 | +|------|:----:|------| +| HandwritingCanvas (React) | ✅ | Canvas API 직접 구현 (터치/마우스, 가이드 문구) | +| 인식 데모 페이지 | ✅ | `views/esign/verification/demo.blade.php` | +| 인식 결과 UI | ✅ | 일치율 프로그레스바, 힌트, 테스트 이력 테이블 | -### Phase 3: 관리자 기능 (1주) +### Phase 3: 관리자 기능 — ✅ 구현 완료 (2026-03-22) -| 작업 | 담당 | 설명 | -|------|------|------| -| 확인 템플릿 관리 UI | MNG | 문구 설정, 임계값 조정 | -| 계약 생성 마법사 연동 | MNG | 필기 확인 on/off 토글 | -| 감사 로그 연동 | MNG | 시도 이력 조회 | +| 작업 | 상태 | 파일 | +|------|:----:|------| +| 확인 템플릿 CRUD | ✅ | `views/esign/verification/templates.blade.php` (React) | +| 대시보드 | ✅ | `views/esign/verification/dashboard.blade.php` (통계/흐름도) | +| 컨트롤러 | ✅ | `EsignVerificationController` (11개 API) | +| 라우트 | ✅ | `/esign-verification/*` (11개 엔드포인트) | +| 메뉴 | ✅ | 연구개발 > 전자서명 고도화 (ID: 15621) | -### Phase 4: 검증 및 안정화 (1주) +### Phase 4: 검증 및 안정화 — ✅ 기본 검증 완료 (2026-03-22) -| 작업 | 담당 | 설명 | -|------|------|------| -| 인식률 테스트 | R&D | 다양한 필체로 인식률 검증 | -| 임계값 튜닝 | R&D | 실 데이터 기반 최적 임계값 | -| 폴백 시나리오 테스트 | MNG | API 장애, 타임아웃 처리 | -| 보안 테스트 | MNG | 이미지 조작, 재사용 방지 | +| 작업 | 상태 | 결과 | +|------|:----:|------| +| TextSimilarity 유사도 테스트 | ✅ | 완전일치 100%, 오타1개 92.9%, 오타2개 85.7%, 부분누락 64.3%, 완전다름 25% | +| 서비스 DI 검증 | ✅ | Laravel 컨테이너 자동 주입 정상 | +| 라우트 등록 검증 | ✅ | 11개 라우트 정상 | +| HWR 폴백 검증 | ✅ | API 키 없을 시 빈 결과 + 적절한 힌트 반환 | -### 총 예상 기간: 5~7주 +### 남은 작업 (추후) + +| 작업 | 우선순위 | 설명 | +|------|:-------:|------| +| 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 액션 기록 | --- @@ -767,6 +779,73 @@ verification_completed — 모든 단계 통과 --- +## 14. 구현 결과 (2026-03-22) + +### 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 +├── app/Models/ESign/ +│ ├── EsignVerificationTemplate.php +│ └── EsignHandwritingVerification.php +├── app/Services/ESign/ +│ ├── TextSimilarityService.php ← 유사도 계산 +│ ├── HwrAdapterInterface.php ← 엔진 인터페이스 +│ ├── HandwritingVerificationService.php ← 메인 서비스 +│ └── Adapters/ +│ ├── NaverClovaAdapter.php ← Naver Clova OCR +│ ├── 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 ← 필기 인식 테스트 +``` + +### 14.2 엔드포인트 (11개) + +| Method | URI | 설명 | +|--------|-----|------| +| GET | `/esign-verification` | 대시보드 | +| GET | `/esign-verification/templates` | 템플릿 관리 | +| GET | `/esign-verification/demo` | 인식 테스트 | +| GET | `/esign-verification/api/stats` | 통계 | +| GET | `/esign-verification/api/templates` | 템플릿 목록 | +| POST | `/esign-verification/api/templates` | 템플릿 생성 | +| GET | `/esign-verification/api/templates/{id}` | 템플릿 상세 | +| PUT | `/esign-verification/api/templates/{id}` | 템플릿 수정 | +| DELETE | `/esign-verification/api/templates/{id}` | 템플릿 삭제 | +| POST | `/esign-verification/api/demo` | 인식 테스트 API | +| GET | `/esign-verification/api/history` | 검증 이력 | + +### 14.3 HWR 활성화 (.env) + +```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 +``` + +### 14.4 기존 서비스 영향 + +``` +✅ 기존 eSign 파일 수정 0건 +✅ 별도 prefix (/esign-verification) — 기존 /esign/* 라우트와 완전 독립 +✅ 별도 컨트롤러 (EsignVerificationController) — 기존 컨트롤러 미수정 +✅ 별도 테이블 (MNG 마이그레이션) — 기존 esign_* 테이블 미수정 +``` + +--- + ## 관련 문서 - [전자서명 기능 개요](README.md)