sam-docs/features/esign

전자서명 (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 스키마 — 문서/전자서명
• Employee API 규칙 — 연봉 정보
• Swagger: /api-docs → ESign 섹션

---

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