# 전자서명 (E-Sign)

> **상태**: API 완전 구현
> **최종 갱신**: 2026-02-27

---

## 1. 개요

PDF 문서에 대한 전자서명 계약 관리 시스템. 계약 생성 → 서명 필드 설정 → 발송 → OTP 인증 → 서명 → 완료의 전체 라이프사이클을 관리한다.

**핵심 기능:**
- PDF 계약서 업로드 및 서명 필드 배치
- 서명 순서 관리 (작성자 우선 / 상대방 우선)
- OTP 기반 본인인증 후 서명
- 서명 완료 시 PDF 합성 + 감사 페이지 추가
- 토큰 기반 외부 서명자 접근 (비인증)

---

## 2. 모델

| 모델 | 테이블 | 설명 | Traits |
|------|--------|------|--------|
| `EsignContract` | `esign_contracts` | 계약서 (상태, 파일, 만료일) | BelongsToTenant, Auditable, SoftDeletes |
| `EsignSigner` | `esign_signers` | 서명자 (순서, OTP, 서명 이미지) | BelongsToTenant |
| `EsignSignField` | `esign_sign_fields` | 서명 필드 (위치, 유형, 페이지) | BelongsToTenant |
| `EsignAuditLog` | `esign_audit_logs` | 감사 로그 (IP, UA, 행위) | BelongsToTenant |

**계약 상태 흐름:**
```
draft → pending → partially_signed → completed
                                   → expired
                → cancelled
                → rejected
```

**서명 필드 유형:** signature, stamp, text, date, checkbox

---

## 3. 서비스

| 서비스 | 주요 메서드 |
|--------|-----------|
| `EsignContractService` | list, create, show, cancel, send, remind, configureFields, stats |
| `EsignSignService` | getByToken, sendOtp, verifyOtp, submitSignature, reject |
| `EsignAuditService` | log, logPublic, getContractLogs |
| `EsignPdfService` | generateHash, verifyIntegrity, composeSigned, addAuditPage |

---

## 4. API 엔드포인트

### 계약 관리 (인증 필요)

| HTTP | URI | 설명 |
|------|-----|------|
| GET | `/v1/esign/contracts` | 계약 목록 |
| POST | `/v1/esign/contracts` | 계약 생성 (PDF 업로드) |
| GET | `/v1/esign/contracts/stats` | 통계 |
| GET | `/v1/esign/contracts/{id}` | 계약 상세 |
| POST | `/v1/esign/contracts/{id}/cancel` | 계약 취소 |
| POST | `/v1/esign/contracts/{id}/fields` | 서명 필드 설정 |
| POST | `/v1/esign/contracts/{id}/send` | 계약 발송 |
| POST | `/v1/esign/contracts/{id}/remind` | 리마인드 |
| GET | `/v1/esign/contracts/{id}/download` | PDF 다운로드 |
| GET | `/v1/esign/contracts/{id}/verify` | 무결성 검증 |

### 서명 처리 (토큰 기반, 외부 접근)

| HTTP | URI | 설명 |
|------|-----|------|
| GET | `/v1/esign/sign/{token}` | 계약 정보 조회 |
| POST | `/v1/esign/sign/{token}/otp/send` | OTP 발송 |
| POST | `/v1/esign/sign/{token}/otp/verify` | OTP 검증 |
| GET | `/v1/esign/sign/{token}/document` | 문서 조회 |
| POST | `/v1/esign/sign/{token}/submit` | 서명 제출 |
| POST | `/v1/esign/sign/{token}/reject` | 서명 거절 |

---

## 5. FormRequest

| Request | 주요 검증 |
|---------|----------|
| `ContractStoreRequest` | title (필수, max:200), file (필수, pdf, max:20MB), sign_order_type, 서명자 정보 |
| `FieldConfigureRequest` | fields 배열 (page, position, size, type) |
| `SignSubmitRequest` | signature_image (파일), field_values (배열) |
| `SignRejectRequest` | reason (필수) |

---

## 관련 문서

- [DB 스키마 — 문서/전자서명](../../system/database/documents.md)
- Swagger: `/api-docs` → ESign 섹션

---

**최종 업데이트**: 2026-02-27