364 lines
14 KiB
Markdown
364 lines
14 KiB
Markdown
# 전자계약(E-Sign) 알림톡 연동 계획서
|
|
|
|
> **문서 버전**: 1.0
|
|
> **작성일**: 2026-02-14
|
|
> **상태**: 계획 (카카오 채널 개설 후 착수)
|
|
> **전제 조건**: 바로빌 카카오톡 서비스 연동 완료
|
|
|
|
---
|
|
|
|
## 1. 현재 상태 (AS-IS)
|
|
|
|
### 1.1 발송 흐름
|
|
|
|
```
|
|
계약 생성 → 필드 설정 → [서명 요청 발송] → 이메일만 발송
|
|
│
|
|
└─ EsignApiController::send()
|
|
└─ Mail::to($signer->email)->send(new EsignRequestMail(...))
|
|
```
|
|
|
|
### 1.2 관련 파일
|
|
|
|
| 구분 | 파일 | 역할 |
|
|
|------|------|------|
|
|
| 발송 화면 | `views/esign/send.blade.php` (129줄) | React 기반 발송 확인 UI |
|
|
| 발송 로직 | `EsignApiController::send()` (686~728줄) | 이메일 발송 실행 |
|
|
| 리마인드 | `EsignApiController::remind()` (734줄~) | 미서명자 재발송 |
|
|
| Mail 클래스 | `Mail/EsignRequestMail.php` (47줄) | 이메일 템플릿 |
|
|
| 이메일 뷰 | `views/emails/esign/request.blade.php` (79줄) | 이메일 HTML |
|
|
| 완료 Mail | `Mail/EsignCompletedMail.php` (46줄) | 완료 알림 이메일 |
|
|
| OTP Mail | `Mail/EsignOtpMail.php` (37줄) | OTP 인증 이메일 |
|
|
| 모델 | `Models/ESign/EsignSigner.php` | `email`, `phone` 필드 보유 |
|
|
|
|
### 1.3 문제점
|
|
|
|
- 이메일 열람률 낮음 (20~30%), 스팸함 유입 가능
|
|
- 서명 요청 확인까지 수시간~1일 소요
|
|
- 모바일에서 이메일 확인 → 링크 클릭 동선이 불편
|
|
|
|
---
|
|
|
|
## 2. 목표 상태 (TO-BE)
|
|
|
|
### 2.1 발송 흐름
|
|
|
|
```
|
|
계약 생성 → 필드 설정 → [서명 요청 발송]
|
|
│
|
|
├─ 발송 방식 선택 (기본: 알림톡)
|
|
│ ├─ 알림톡 (기본값)
|
|
│ ├─ 이메일
|
|
│ └─ 알림톡 + 이메일 (동시)
|
|
│
|
|
└─ EsignApiController::send()
|
|
├─ [알림톡] BarobillService::sendATKakaotalkEx()
|
|
│ └─ SMS 대체발송 (카톡 미사용자)
|
|
└─ [이메일] Mail::to()->send(new EsignRequestMail())
|
|
```
|
|
|
|
### 2.2 핵심 변경 원칙
|
|
|
|
- **기본값은 알림톡** — 별도 선택 없이 발송하면 알림톡으로 전송
|
|
- **이메일도 유지** — 알림톡 불가 시(채널 미연동 등) 이메일 폴백
|
|
- **동시 발송 가능** — 중요 계약은 알림톡 + 이메일 동시 발송 옵션
|
|
- **기존 코드 최소 변경** — 발송 로직만 분기, 나머지 흐름 동일
|
|
|
|
---
|
|
|
|
## 3. UI/UX 변경
|
|
|
|
### 3.1 발송 화면 (`send.blade.php`) 변경
|
|
|
|
**현재**: 서명자 확인 → [서명 요청 발송] 버튼만 존재
|
|
|
|
**변경 후**:
|
|
|
|
```
|
|
┌──────────────────────────────────────────┐
|
|
│ 서명 요청 발송 │
|
|
├──────────────────────────────────────────┤
|
|
│ │
|
|
│ [발송 전 확인] │
|
|
│ ✓ 계약 제목: OO 공급계약서 │
|
|
│ ✓ PDF 파일: contract_2026.pdf │
|
|
│ ✓ 서명 필드: 4개 설정됨 │
|
|
│ │
|
|
│ [서명 순서] │
|
|
│ ① 홍길동 (작성자) - hong@company.com │
|
|
│ ② 김철수 (상대방) - kim@partner.com │
|
|
│ │
|
|
│ ┌─────────────────────────────────────┐ │
|
|
│ │ 발송 방식 │ │
|
|
│ │ │ │
|
|
│ │ ● 카카오톡 알림톡 (권장) │ │
|
|
│ │ 수신자 휴대폰으로 알림톡 발송 │ │
|
|
│ │ 카카오톡 미사용 시 SMS 자동 대체 │ │
|
|
│ │ │ │
|
|
│ │ ○ 이메일 │ │
|
|
│ │ 수신자 이메일로 발송 │ │
|
|
│ │ │ │
|
|
│ │ ○ 알림톡 + 이메일 (동시) │ │
|
|
│ │ 두 채널 모두 발송 │ │
|
|
│ │ │ │
|
|
│ │ ☐ SMS 대체발송 사용 │ │
|
|
│ │ (알림톡 선택 시 자동 체크) │ │
|
|
│ └─────────────────────────────────────┘ │
|
|
│ │
|
|
│ [서명자별 연락처 확인] │
|
|
│ ┌─────────────────────────────────────┐ │
|
|
│ │ ① 홍길동 │ │
|
|
│ │ 📱 010-1234-5678 ✓ │ │
|
|
│ │ ✉ hong@company.com ✓ │ │
|
|
│ │ │ │
|
|
│ │ ② 김철수 │ │
|
|
│ │ 📱 미입력 ⚠ (알림톡 발송 불가) │ │
|
|
│ │ ✉ kim@partner.com ✓ │ │
|
|
│ └─────────────────────────────────────┘ │
|
|
│ │
|
|
│ [돌아가기] [서명 요청 발송] │
|
|
└──────────────────────────────────────────┘
|
|
```
|
|
|
|
### 3.2 UI 동작 규칙
|
|
|
|
| 상황 | 기본 선택 | 동작 |
|
|
|------|----------|------|
|
|
| 모든 서명자에 휴대폰 번호 있음 | 알림톡 (기본) | 정상 발송 |
|
|
| 일부 서명자에 번호 없음 | 알림톡 선택 시 경고 표시 | "번호 미입력 서명자는 이메일로 발송됩니다" |
|
|
| 바로빌 카카오 미연동 | 이메일 (자동 전환) | 알림톡 옵션 비활성화 + 안내 문구 |
|
|
| 알림톡 + 이메일 선택 | 동시 발송 | 두 채널 모두 전송 |
|
|
|
|
### 3.3 서명자 연락처 유효성 표시
|
|
|
|
| 아이콘 | 의미 |
|
|
|--------|------|
|
|
| ✓ (녹색) | 해당 채널로 발송 가능 |
|
|
| ⚠ (주황) | 정보 누락 — 다른 채널로 대체 가능 |
|
|
| ✗ (빨강) | 발송 불가 — 정보 입력 필요 |
|
|
|
|
---
|
|
|
|
## 4. 백엔드 변경
|
|
|
|
### 4.1 EsignApiController::send() 수정
|
|
|
|
**현재** (이메일만):
|
|
```php
|
|
Mail::to($signer->email)->send(new EsignRequestMail($contract, $signer));
|
|
```
|
|
|
|
**변경 후** (발송 방식 분기):
|
|
```php
|
|
// 요청에서 발송 방식 수신
|
|
$sendMethod = $request->input('send_method', 'alimtalk'); // alimtalk | email | both
|
|
|
|
foreach ($targetSigners as $signer) {
|
|
$signer->update(['status' => 'notified']);
|
|
|
|
if (in_array($sendMethod, ['alimtalk', 'both']) && $signer->phone) {
|
|
// 알림톡 발송
|
|
$this->sendAlimtalk($contract, $signer, $request->boolean('sms_fallback', true));
|
|
}
|
|
|
|
if (in_array($sendMethod, ['email', 'both']) || !$signer->phone) {
|
|
// 이메일 발송 (또는 번호 없으면 이메일 폴백)
|
|
Mail::to($signer->email)->send(new EsignRequestMail($contract, $signer));
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.2 알림톡 발송 메서드 추가
|
|
|
|
```php
|
|
private function sendAlimtalk(EsignContract $contract, EsignSigner $signer, bool $smsFallback = true): void
|
|
{
|
|
$signUrl = config('app.url') . '/esign/sign/' . $signer->access_token;
|
|
|
|
$barobill = app(BarobillService::class);
|
|
$member = BarobillMember::where('tenant_id', $contract->tenant_id)->first();
|
|
|
|
if (!$member) return; // 바로빌 미연동 시 스킵
|
|
|
|
$barobill->setServerMode($member->is_test_mode ? 'test' : 'production');
|
|
|
|
$barobill->sendATKakaotalkEx(
|
|
corpNum: $member->corp_num,
|
|
certKey: $member->cert_key,
|
|
senderId: $member->kakaotalk_sender_id, // 발신 프로필 ID
|
|
templateName: '전자계약_서명요청', // 등록된 템플릿명
|
|
receiverName: $signer->name,
|
|
receiverNum: $signer->phone,
|
|
title: '전자계약 서명 요청',
|
|
message: $this->buildAlimtalkMessage($contract, $signer),
|
|
buttons: [
|
|
[
|
|
'Name' => '계약서 확인하기',
|
|
'ButtonType' => 'WL',
|
|
'Url1' => $signUrl, // 모바일
|
|
'Url2' => $signUrl, // PC
|
|
],
|
|
],
|
|
smsMessage: $smsFallback
|
|
? "[SAM] {$signer->name}님, 전자계약 서명 요청이 도착했습니다. {$signUrl}"
|
|
: '',
|
|
);
|
|
}
|
|
```
|
|
|
|
### 4.3 알림톡 메시지 템플릿
|
|
|
|
```php
|
|
private function buildAlimtalkMessage(EsignContract $contract, EsignSigner $signer): string
|
|
{
|
|
$expires = $contract->expires_at?->format('Y-m-d H:i') ?? '없음';
|
|
|
|
return "안녕하세요, {$signer->name}님.\n"
|
|
. "전자계약 서명 요청이 도착했습니다.\n\n"
|
|
. "■ 계약명: {$contract->title}\n"
|
|
. "■ 서명 기한: {$expires}\n\n"
|
|
. "아래 버튼을 눌러 계약서를 확인하고 서명해 주세요.";
|
|
}
|
|
```
|
|
|
|
### 4.4 리마인드 발송도 동일 적용
|
|
|
|
`EsignApiController::remind()` 에도 동일한 발송 방식 분기 적용.
|
|
|
|
### 4.5 계약 완료 알림도 알림톡 추가
|
|
|
|
`EsignPublicController::submitSignature()` → 모든 서명 완료 시 `EsignCompletedMail` 발송 부분에 알림톡 추가.
|
|
|
|
---
|
|
|
|
## 5. 알림톡 템플릿 (카카오 검수용)
|
|
|
|
카카오에 등록할 템플릿 3종:
|
|
|
|
### 5.1 서명 요청
|
|
|
|
```
|
|
템플릿명: 전자계약_서명요청
|
|
|
|
안녕하세요, #{수신자명}님.
|
|
전자계약 서명 요청이 도착했습니다.
|
|
|
|
■ 계약명: #{계약명}
|
|
■ 서명 기한: #{마감일}
|
|
|
|
아래 버튼을 눌러 계약서를 확인하고 서명해 주세요.
|
|
|
|
[계약서 확인하기] (웹링크 버튼)
|
|
```
|
|
|
|
### 5.2 리마인드
|
|
|
|
```
|
|
템플릿명: 전자계약_리마인드
|
|
|
|
안녕하세요, #{수신자명}님.
|
|
아직 서명이 완료되지 않은 전자계약이 있습니다.
|
|
|
|
■ 계약명: #{계약명}
|
|
■ 서명 기한: #{마감일}
|
|
|
|
기한 내에 서명을 완료해 주세요.
|
|
|
|
[서명하기] (웹링크 버튼)
|
|
```
|
|
|
|
### 5.3 계약 완료
|
|
|
|
```
|
|
템플릿명: 전자계약_완료
|
|
|
|
안녕하세요, #{수신자명}님.
|
|
전자계약이 모든 서명자의 서명 완료로 확정되었습니다.
|
|
|
|
■ 계약명: #{계약명}
|
|
■ 완료일: #{완료일}
|
|
|
|
아래 버튼에서 서명 완료된 계약서를 확인할 수 있습니다.
|
|
|
|
[계약서 확인하기] (웹링크 버튼)
|
|
```
|
|
|
|
---
|
|
|
|
## 6. DB 변경
|
|
|
|
### 6.1 esign_contracts 테이블 (컬럼 추가)
|
|
|
|
| 컬럼 | 타입 | 기본값 | 설명 |
|
|
|------|------|--------|------|
|
|
| `send_method` | `enum('alimtalk','email','both')` | `'alimtalk'` | 발송 방식 |
|
|
| `sms_fallback` | `boolean` | `true` | SMS 대체발송 사용 여부 |
|
|
|
|
> 마이그레이션은 API 프로젝트에서 생성
|
|
|
|
### 6.2 esign_signers 테이블 (기존 컬럼 활용)
|
|
|
|
- `phone` — 이미 존재. 알림톡 발송에 사용
|
|
- `email` — 이미 존재. 이메일 발송에 사용
|
|
|
|
> 추가 컬럼 불필요. `phone`이 nullable이므로, 없으면 이메일 폴백.
|
|
|
|
---
|
|
|
|
## 7. 구현 순서
|
|
|
|
| 단계 | 작업 | 파일 | 우선순위 |
|
|
|------|------|------|---------|
|
|
| **0** | **카카오 채널 개설 + 바로빌 연동 + 템플릿 검수** | (비개발) | 선행 필수 |
|
|
| 1 | API 마이그레이션 — `send_method`, `sms_fallback` 컬럼 추가 | `api/database/migrations/` | 높음 |
|
|
| 2 | `EsignApiController::send()` 발송 방식 분기 로직 | `EsignApiController.php` | 높음 |
|
|
| 3 | `sendAlimtalk()` 메서드 + 메시지 빌더 추가 | `EsignApiController.php` | 높음 |
|
|
| 4 | `send.blade.php` 발송 방식 선택 UI 추가 | `send.blade.php` | 높음 |
|
|
| 5 | 서명자 연락처 유효성 표시 UI | `send.blade.php` | 중간 |
|
|
| 6 | `remind()` 알림톡 분기 추가 | `EsignApiController.php` | 중간 |
|
|
| 7 | 계약 완료 알림톡 추가 | `EsignPublicController.php` | 중간 |
|
|
| 8 | 바로빌 카카오 미연동 시 알림톡 옵션 비활성화 처리 | `send.blade.php` + 컨트롤러 | 중간 |
|
|
| 9 | 테스트 발송 검증 | - | 높음 |
|
|
| 10 | 운영 전환 (`testws` → `ws`) | `config/services.php` | 최종 |
|
|
|
|
---
|
|
|
|
## 8. 영향 범위
|
|
|
|
### 8.1 변경 파일 (예상)
|
|
|
|
| 프로젝트 | 파일 | 변경 내용 |
|
|
|---------|------|----------|
|
|
| **API** | `database/migrations/xxx_add_send_method_to_esign_contracts.php` | 컬럼 추가 |
|
|
| **MNG** | `app/Http/Controllers/ESign/EsignApiController.php` | 발송 분기 로직 |
|
|
| **MNG** | `app/Http/Controllers/ESign/EsignPublicController.php` | 완료 알림톡 |
|
|
| **MNG** | `resources/views/esign/send.blade.php` | 발송 방식 선택 UI |
|
|
| **MNG** | `resources/views/esign/detail.blade.php` | 발송 방식 표시 (선택사항) |
|
|
|
|
### 8.2 변경하지 않는 파일
|
|
|
|
- `EsignController.php` — 페이지 라우팅만 담당, 변경 불필요
|
|
- `EsignRequestMail.php` — 이메일 발송은 그대로 유지
|
|
- `views/emails/esign/*` — 이메일 템플릿 유지
|
|
- `views/esign/sign/*` — 서명 화면은 발송 방식과 무관
|
|
- `Models/ESign/*` — `send_method` 컬럼만 fillable 추가
|
|
|
|
---
|
|
|
|
## 9. 리스크 및 대응
|
|
|
|
| 리스크 | 영향 | 대응 |
|
|
|--------|------|------|
|
|
| 카카오 템플릿 검수 반려 | 알림톡 발송 불가 | 템플릿 문구 수정 후 재신청 (반복 가능) |
|
|
| 서명자 휴대폰 번호 미입력 | 알림톡 발송 실패 | 이메일 자동 폴백 |
|
|
| 바로빌 API 장애 | 알림톡 발송 실패 | try-catch → 이메일 폴백 + 에러 로그 |
|
|
| SMS 대체발송 비용 | 예상 외 비용 발생 | SMS 대체발송 on/off 옵션 제공 |
|
|
|
|
---
|
|
|
|
## 변경 이력
|
|
|
|
| 날짜 | 버전 | 변경 내용 |
|
|
|------|------|----------|
|
|
| 2026-02-14 | 1.0 | 계획서 초안 작성 |
|