feat:E-Sign 전자계약 서명 솔루션 백엔드 구현

- 마이그레이션 4개 (esign_contracts, esign_signers, esign_sign_fields, esign_audit_logs)
- 모델 4개 (EsignContract, EsignSigner, EsignSignField, EsignAuditLog)
- 서비스 4개 (EsignContractService, EsignSignService, EsignPdfService, EsignAuditService)
- 컨트롤러 2개 (EsignContractController, EsignSignController)
- FormRequest 4개 (ContractStore, FieldConfigure, SignSubmit, SignReject)
- Mail 1개 (EsignRequestMail + 이메일 템플릿)
- API 라우트 (인증 계약 관리 + 토큰 기반 서명 프로세스)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

app/Http/Controllers/Api/V1/ESign/EsignContractController.php

@@ -0,0 +1,116 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\ESign;
+
+use App\Helpers\ApiResponse;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\ESign\ContractStoreRequest;
+use App\Http\Requests\ESign\FieldConfigureRequest;
+use App\Services\ESign\EsignContractService;
+use App\Services\ESign\EsignPdfService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Storage;
+
+class EsignContractController extends Controller
+{
+    public function __construct(
+        private EsignContractService $service,
+        private EsignPdfService $pdfService,
+    ) {}
+
+    public function index(Request $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->list($request->all());
+        }, __('message.fetched'));
+    }
+
+    public function show(int $id): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->show($id);
+        }, __('message.fetched'));
+    }
+
+    public function store(ContractStoreRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->create($request->validated() + ['file' => $request->file('file')]);
+        }, __('message.created'));
+    }
+
+    public function cancel(int $id): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->cancel($id);
+        }, __('message.esign.cancelled'));
+    }
+
+    public function configureFields(int $id, FieldConfigureRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id, $request) {
+            return $this->service->configureFields($id, $request->validated()['fields']);
+        }, __('message.esign.fields_configured'));
+    }
+
+    public function send(int $id): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->send($id);
+        }, __('message.esign.sent'));
+    }
+
+    public function remind(int $id): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->remind($id);
+        }, __('message.esign.reminded'));
+    }
+
+    public function stats(): JsonResponse
+    {
+        return ApiResponse::handle(function () {
+            return $this->service->stats();
+        }, __('message.fetched'));
+    }
+
+    public function download(int $id): \Symfony\Component\HttpFoundation\StreamedResponse|JsonResponse
+    {
+        try {
+            $contract = $this->service->show($id);
+            $filePath = $contract->signed_file_path ?? $contract->original_file_path;
+
+            if (! $filePath || ! Storage::disk('local')->exists($filePath)) {
+                return ApiResponse::error(__('error.esign.file_not_found'), 404);
+            }
+
+            $fileName = $contract->original_file_name ?? 'contract.pdf';
+
+            return Storage::disk('local')->download($filePath, $fileName);
+        } catch (\Throwable $e) {
+            return ApiResponse::error($e->getMessage(), 500);
+        }
+    }
+
+    public function verify(int $id): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id) {
+            $contract = $this->service->show($id);
+
+            if (! $contract->original_file_path || ! $contract->original_file_hash) {
+                return ['verified' => false, 'message' => '파일 정보가 없습니다.'];
+            }
+
+            $isValid = $this->pdfService->verifyIntegrity(
+                $contract->original_file_path,
+                $contract->original_file_hash
+            );
+
+            return [
+                'verified' => $isValid,
+                'original_hash' => $contract->original_file_hash,
+            ];
+        }, __('message.esign.verified'));
+    }
+}

app/Http/Controllers/Api/V1/ESign/EsignSignController.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\ESign;
+
+use App\Helpers\ApiResponse;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\ESign\SignRejectRequest;
+use App\Http\Requests\ESign\SignSubmitRequest;
+use App\Services\ESign\EsignSignService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Storage;
+
+class EsignSignController extends Controller
+{
+    public function __construct(
+        private EsignSignService $service,
+    ) {}
+
+    public function getContract(string $token): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($token) {
+            return $this->service->getByToken($token);
+        }, __('message.fetched'));
+    }
+
+    public function sendOtp(string $token): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($token) {
+            return $this->service->sendOtp($token);
+        }, __('message.esign.otp_sent'));
+    }
+
+    public function verifyOtp(string $token, Request $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($token, $request) {
+            $request->validate(['otp_code' => 'required|string|size:6']);
+
+            return $this->service->verifyOtp($token, $request->input('otp_code'));
+        }, __('message.esign.otp_verified'));
+    }
+
+    public function getDocument(string $token): \Symfony\Component\HttpFoundation\StreamedResponse|JsonResponse
+    {
+        try {
+            $data = $this->service->getByToken($token);
+            $contract = $data['contract'];
+            $filePath = $contract->original_file_path;
+
+            if (! $filePath || ! Storage::disk('local')->exists($filePath)) {
+                return ApiResponse::error(__('error.esign.file_not_found'), 404);
+            }
+
+            return Storage::disk('local')->response($filePath, null, [
+                'Content-Type' => 'application/pdf',
+            ]);
+        } catch (\Throwable $e) {
+            return ApiResponse::error($e->getMessage(), $e->getCode() ?: 500);
+        }
+    }
+
+    public function submit(string $token, SignSubmitRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($token, $request) {
+            return $this->service->submitSignature($token, $request->validated());
+        }, __('message.esign.signed'));
+    }
+
+    public function reject(string $token, SignRejectRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($token, $request) {
+            return $this->service->reject($token, $request->validated()['reason']);
+        }, __('message.esign.rejected'));
+    }
+}

app/Http/Requests/ESign/ContractStoreRequest.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Http\Requests\ESign;
+
+use App\Models\ESign\EsignContract;
+use Illuminate\Foundation\Http\FormRequest;
+
+class ContractStoreRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'title' => 'required|string|max:200',
+            'description' => 'nullable|string|max:2000',
+            'sign_order_type' => 'nullable|string|in:' . implode(',', EsignContract::SIGN_ORDERS),
+            'file' => 'required|file|mimes:pdf|max:20480',
+            'expires_at' => 'nullable|date|after:now',
+            'creator_name' => 'required|string|max:100',
+            'creator_email' => 'required|email|max:255',
+            'creator_phone' => 'nullable|string|max:20',
+            'counterpart_name' => 'required|string|max:100',
+            'counterpart_email' => 'required|email|max:255',
+            'counterpart_phone' => 'nullable|string|max:20',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'title.required' => __('validation.required', ['attribute' => '계약 제목']),
+            'file.required' => __('validation.required', ['attribute' => 'PDF 파일']),
+            'file.mimes' => __('validation.mimes', ['attribute' => '파일', 'values' => 'PDF']),
+            'file.max' => __('validation.max.file', ['attribute' => '파일', 'max' => '20MB']),
+            'creator_name.required' => __('validation.required', ['attribute' => '작성자 이름']),
+            'creator_email.required' => __('validation.required', ['attribute' => '작성자 이메일']),
+            'counterpart_name.required' => __('validation.required', ['attribute' => '상대방 이름']),
+            'counterpart_email.required' => __('validation.required', ['attribute' => '상대방 이메일']),
+        ];
+    }
+}

app/Http/Requests/ESign/FieldConfigureRequest.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Http\Requests\ESign;
+
+use App\Models\ESign\EsignSignField;
+use Illuminate\Foundation\Http\FormRequest;
+
+class FieldConfigureRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'fields' => 'required|array|min:1',
+            'fields.*.signer_id' => 'required|integer|exists:esign_signers,id',
+            'fields.*.page_number' => 'required|integer|min:1',
+            'fields.*.position_x' => 'required|numeric|min:0|max:100',
+            'fields.*.position_y' => 'required|numeric|min:0|max:100',
+            'fields.*.width' => 'required|numeric|min:1|max:100',
+            'fields.*.height' => 'required|numeric|min:1|max:100',
+            'fields.*.field_type' => 'nullable|string|in:' . implode(',', EsignSignField::FIELD_TYPES),
+            'fields.*.field_label' => 'nullable|string|max:100',
+            'fields.*.is_required' => 'nullable|boolean',
+            'fields.*.sort_order' => 'nullable|integer|min:0',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'fields.required' => __('validation.required', ['attribute' => '서명 필드']),
+            'fields.min' => '최소 1개 이상의 서명 필드가 필요합니다.',
+        ];
+    }
+}

app/Http/Requests/ESign/SignRejectRequest.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Http\Requests\ESign;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class SignRejectRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'reason' => 'required|string|max:1000',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'reason.required' => __('validation.required', ['attribute' => '거절 사유']),
+        ];
+    }
+}

app/Http/Requests/ESign/SignSubmitRequest.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Http\Requests\ESign;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class SignSubmitRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'signature_image' => 'required|string',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'signature_image.required' => __('validation.required', ['attribute' => '서명 이미지']),
+        ];
+    }
+}