102 lines
3.4 KiB
Markdown
102 lines
3.4 KiB
Markdown
|
# 전자서명 (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
|