5517b7f04d
- features/esign/README.md: 근로계약서 사원 연동 섹션 추가 - projects/e-sign/changelog.md: v1.1.1 변경 이력 추가 - rules/employee-api.md: 전자계약 연동 참조 추가 - dev/changes/20260311: esign 연봉정보 개선 내용 추가
154 lines
5.5 KiB
Markdown
154 lines
5.5 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 (필수) |
|
|
|
|
---
|
|
|
|
## 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
|