sam-docs/dev/dev_plans/esign-alimtalk-integration.md

전자계약(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() 수정

현재 (이메일만):

Mail::to($signer->email)->send(new EsignRequestMail($contract, $signer));

변경 후 (발송 방식 분기):

// 요청에서 발송 방식 수신
$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 알림톡 발송 메서드 추가

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 알림톡 메시지 템플릿

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	계획서 초안 작성