# 전자서명 (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 (필수) |

---

## 5. 근로계약서 사원 연동

### 사원불러오기 API

근로계약서 작성 시 사원 정보를 검색하여 계약 변수를 자동 채운다.

| HTTP | URI | 설명 |
|------|-----|------|
| GET | `/esign/contracts/search-employees?q=검색어` | 사원 검색 (MNG 내부 API) |

**반환 데이터:**

| 필드 | 설명 | 매핑 대상 |
|------|------|----------|
| `name` | 사원명 | 근로자 이름/성명 |
| `phone`, `email` | 연락처 | 서명자 정보 자동 채움 |
| `department`, `position` | 부서/직위 | 부서, 직책 필드 |
| `address` | 주소 | 직원 주소 |
| `hire_date` | 입사일 | 근로계약 시작일 |
| `birth_year/month/day` | 생년월일 (주민번호 파싱) | 출생 년/월/일 |
| `annual_salary` | 최신 연봉 | 연봉 금액, 월급 자동 계산 |
| `salary_effective_date` | 연봉 적용일 | 연봉계약 시작/종료일 기준 |

### 최신 연봉 탐색 로직 (2026-03-11)

연봉 이력이 많을 때 최신 연봉을 정확히 반환하기 위한 fallback 로직:

1. `salary_info.annual_salary` 확인 (현재 연봉)
2. null이면 `salary_info.history`에서 `effective_date` 기준 최신 이력 탐색
3. `salary_effective_date`도 함께 반환

### 계약 기간 자동 계산

| 계약 유형 | 시작일 기준 | 종료일 |
|----------|-----------|--------|
| 연봉계약 | `salary_effective_date` (최신 연봉 적용일) | 시작일 + 1년 |
| 근로계약 | `hire_date` (입사일) | 입사일 + 1년 |
| 일반 계약 | 연봉 적용일 우선, 없으면 입사일 | 시작일 + 1년 |

> 매년 연봉을 갱신하면 연봉계약 기간이 자동으로 최신 적용일 기준으로 계산된다.

### 관련 파일

| 파일 | 역할 |
|------|------|
| `mng/app/Http/Controllers/ESign/EsignApiController.php` | `searchEmployees()` — 사원 검색 + 최신 연봉 반환 |
| `mng/resources/views/esign/create.blade.php` | `handleEmployeeSelect()` — 변수 자동 매핑 |
| `mng/app/Models/HR/Employee.php` | `getSalaryInfo()` — 연봉 데이터 조회 |

---

## 관련 문서

- [DB 스키마 — 문서/전자서명](../../system/database/documents.md)
- [Employee API 규칙 — 연봉 정보](../../rules/employee-api.md#연봉-정보-관리-mng-내부-api)
- Swagger: `/api-docs` → ESign 섹션

---

**최종 업데이트**: 2026-03-11