docs: [esign] 전자서명 고도화 기획서 — 구현 완료 상태 업데이트 (Phase 1~3, 파일 목록, 엔드포인트, 남은 작업)

2026-03-22 22:38:17 +09:00
parent 1bcae79b12
commit a5542a762a
1 changed files with 109 additions and 30 deletions
--- 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)