테마
Epic Spec: E-05 연동 자동화 (SMS 포워딩 기반)
⚠️ 스펙아웃: 2026-01-23 Sprint 52에서 제외. Sprint 53 이후 재검토 예정.
메타
| 항목 | 값 |
|---|---|
| Epic ID | E-05 |
| Sprint | |
| 상태 | spec-out |
| PO 승인일 | 2026-01-20 |
| 스펙아웃일 | 2026-01-23 |
| 담당 | 하록 (BE) |
| 스펙아웃 사유 | Sprint 52 리소스 집중을 위해 우선순위 조정. 온보딩 팝업(E-11)으로 연동율 개선 우선 시도. |
1. WHY: 왜 이 기능이 필요한가?
문제 정의
현재 쿠팡 연동 시 유선 통화로 인증번호를 전달하는 방식이 심각한 문제를 야기하고 있다.
[실제 발생한 문제]
• 담당자가 셀러에게 전화 → 스팸으로 오해받아 차단당함
• "인증번호 불러달라"는 요청 = 전형적인 보이스피싱 패턴
• 셀러 입장에서 장사왕을 신뢰하기 어려운 구조
[현재 문제]
1. 유선 통화 = 스팸/보이스피싱으로 오해 → 고객 신뢰 훼손
2. 영업시간 외 연동 불가 → 셀러 이탈
3. 담당자 리소스 소모 → 운영 비효율
4. 연동 경험 자체가 서비스 품질을 저해⚠️ 핵심 제약: 100% 정확한 매칭 필수
[법적 리스크]
A 셀러의 연동에 B 셀러의 데이터가 연결되면:
• 타인의 매출/마진 정보 노출
• 개인정보보호법 위반
• 법적 책임 + 사업 신뢰 붕괴
→ 0.01%의 오매칭도 허용 불가
→ "추측" 기반 매칭 금지
→ 100% 확실한 세션 식별 필수현재 연동 프로세스 (As-Is)
┌─────────────────────────────────────────────────────────────────────────┐
│ 현재 수동 연동 프로세스 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ [셀러] [담당자] [시스템] │
│ │
│ 1. 연동 신청 ──────────────────────────────────────→ 연동신청 접수 │
│ │
│ 2. ←────────────────── 유선 통화 시작 ←──────────── 알림 │
│ │
│ 3. 쿠팡 관리자 접속 │
│ └─ 추가계정 생성 시작 │
│ │
│ 4. 장사왕 정보 입력 │
│ └─ 휴대전화: 장사왕 업무폰 │
│ └─ 이메일: sellerking@moonklabs.com │
│ │
│ 5. 📱 SMS 인증 요청 ─────→ 업무폰 SMS 확인 │
│ ←───── "인증번호 000000" 전달 │
│ │
│ 6. 📧 이메일 인증 요청 ──→ 이메일 확인 │
│ ←───── "인증번호 000000" 전달 │
│ │
│ 7. 추가계정 생성 완료 │
│ (판매자 본인인증 포함) │
│ │
│ 8. ─────────────────────────────────────────────→ 상태 변경 │
│ (계정생성완료) │
│ │
│ 9. ←────────────────── 유선 통화 종료 │
│ │
│ 10. ────────────────────────────────────────────→ AI Agent 연동 시작 │
│ (로그인 + 데이터) │
│ │
└─────────────────────────────────────────────────────────────────────────┘
[병목]
• 5~6단계: 담당자가 직접 인증번호 확인 → 전달 (평균 1~2분 × 2회)
• 2~9단계: 유선 통화 유지 필요 (평균 10~15분)근거 데이터
| 지표 | 수치 | 출처 | 비고 |
|---|---|---|---|
| 연동 1건당 평균 소요 시간 | 10~15분 | 운영팀 | 유선 통화 포함 |
| 스팸 차단 발생 | 1건 | 2026-01-20 | PO 직접 경험 |
| 월 연동 신청 건수 | TBD | 어드민 | 측정 필요 |
| 담당자 연동 업무 비중 | 높음 | 운영팀 | 이삭 선임 출산휴가로 PO 임시 담당 |
기대 효과
- 스팸 오해 제거: 유선 통화 0건 → 신뢰 확보
- 24시간 무인 연동: 영업시간 외에도 연동 가능
- 연동 시간 단축: 15분 → 5분 이내
- 담당자 리소스 해방: 연동 업무 완전 자동화
- 100% 안전한 매칭: 법적 리스크 제로
2. WHAT: 솔루션 개요
핵심 아이디어
[기존] 유선 통화로 인증번호 전달
→ 스팸 오해, 신뢰 붕괴
[변경] SMS 자동 포워딩 + 셀러 화면에 실시간 표시
→ 전화 없음, 셀러가 직접 입력핵심 기능
| # | 기능 | 설명 | 필수 여부 |
|---|---|---|---|
| 1 | Android SMS 자동 수신 | SmsForwarder 앱으로 SMS → Webhook | 필수 |
| 2 | Exclusive Lock | SMS 인증 단계 한 번에 한 명만 진행 | 필수 |
| 3 | 실시간 인증번호 표시 | WebSocket으로 셀러 화면에 즉시 표시 | 필수 |
| 4 | 이메일 인증번호 자동 추출 | Gmail API로 이메일 파싱 | 필수 |
| 5 | 셀러 셀프 연동 UI | 단계별 가이드 + 실시간 상태 | 필수 |
기술 스택
[SMS 자동화]
• Android 업무폰 (기존 번호 유지 또는 신규)
• SmsForwarder 앱 (오픈소스)
- GitHub: https://github.com/pppscn/SmsForwarder
- 라이선스: BSD-2-Clause
- 기능: SMS 수신 → Webhook 전송, 규칙 기반 필터링
[이메일 자동화]
• Gmail API 폴링 (10초 간격)
• 대상: sellerking@moonklabs.com
[실시간 통신]
• WebSocket (셀러 브라우저 ↔ 서버)3. Exclusive Lock 메커니즘
왜 Exclusive Lock인가
[문제]
SMS에는 "이건 A 셀러 것"이라는 식별 정보가 없음
동시에 여러 셀러가 대기 중이면 매칭 불가능
[검토한 대안들]
• 시간 기반 매칭 → 동시 요청 시 오매칭 위험 ❌
• 확인 요청 → 둘 다 "네" 클릭하면? 여전히 위험 ❌
• 가상번호 풀 → 한국 SMS 수신 서비스 제한적 ❌
[결론]
SMS 인증 단계는 한 번에 한 명만 진행
= Exclusive Lock
= 100% 정확한 매칭 보장Lock 플로우
[Exclusive Lock 상태 머신]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┌─────────────────┐
│ LOCK_FREE │ ← 아무도 인증 중 아님
└────────┬────────┘
│
셀러 A "준비 완료" 클릭
│
▼
┌─────────────────┐
│ LOCKED (A) │ ← A가 Lock 획득
│ 2분 타이머 │
└────────┬────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
SMS 수신 성공 2분 타임아웃 A가 완료
│ │ │
▼ ▼ ▼
A에게 코드 전달 Lock 해제 + 재시도 Lock 해제
│ 안내
▼
┌─────────────────┐
│ LOCK_FREE │
└─────────────────┘
[Lock 규칙]
• Lock 최대 유지 시간: 2분
• Lock 보유자만 SMS 수신 가능
• 타임아웃 시 자동 해제
• 완료/실패 시 즉시 해제동시 요청 처리
[시나리오: A가 Lock 중일 때 B가 요청]
셀러 A: Lock 보유 중 (남은 시간 1:30)
셀러 B: "준비 완료" 클릭 시도
B 화면:
┌─────────────────────────────────────────────────────┐
│ ⏳ 잠시만 기다려주세요 │
│ │
│ 다른 셀러님의 인증이 진행 중이에요. │
│ 곧 순서가 돌아옵니다. │
│ │
│ 예상 대기 시간: 약 1분 30초 │
│ │
│ ████████████░░░░░░░░ 진행 중... │
│ │
│ 💡 창을 닫지 마세요. 자동으로 진행됩니다. │
└─────────────────────────────────────────────────────┘
A 완료 또는 타임아웃 시 → B 자동 진행세션 상태 정의
[연동 세션 상태 머신]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
REQUESTED → 셀러가 연동 신청
↓
INFO_ENTERING → 쿠팡에서 정보 입력 중
↓
WAITING_FOR_LOCK → Lock 대기 중 (다른 셀러 진행 중)
↓
LOCKED → Lock 획득, SMS 대기 중
↓
SMS_RECEIVED → SMS 인증번호 수신 완료
↓
EMAIL_WAITING → 이메일 인증 대기 중
↓
EMAIL_RECEIVED → 이메일 인증번호 수신 완료
↓
VERIFYING → 셀러가 쿠팡에서 인증 진행 중
↓
COMPLETED → 연동 완료
[예외 상태]
LOCK_TIMEOUT → Lock 시간 초과 (2분)
FAILED → 연동 실패
CANCELLED → 셀러가 취소
[세션 데이터]
{
"session_id": "uuid",
"seller_id": "seller_123",
"seller_phone": "010-1234-5678",
"status": "LOCKED",
"locked_at": "2026-01-20T10:00:00Z",
"lock_expires_at": "2026-01-20T10:02:00Z",
"sms_code": null,
"email_code": null,
"created_at": "2026-01-20T09:55:00Z",
"completed_at": null
}4. SMS 자동화 (SmsForwarder)
SmsForwarder 설정
[앱 설치]
• Android 폰에 SmsForwarder 설치
• GitHub Releases에서 APK 다운로드
• https://github.com/pppscn/SmsForwarder/releases
[전달 채널 설정]
• 유형: Webhook
• URL: https://api.sellerking.io/webhook/sms-forward
• Method: POST
• Content-Type: application/json
• Body Template:
{
"from": "{{발신번호}}",
"content": "{{문자내용}}",
"timestamp": "{{수신시간}}"
}
[전달 규칙 설정]
• 조건: 문자 내용에 "인증번호" 또는 "인증코드" 포함
• 또는: 발신자에 "coupang" 포함
• 액션: Webhook으로 전달Webhook 수신 API
POST /webhook/sms-forward
Request Body:
{
"from": "15771234",
"content": "[쿠팡] 인증번호 [123456]을 입력해주세요.",
"timestamp": "2026-01-20T10:01:30Z"
}
Server Logic:
1. 인증번호 추출
regex: /인증번호[^0-9]*(\d{6})/
또는: /\[(\d{6})\]/
2. 현재 LOCKED 상태인 세션 조회
• 없으면 → 무시 (예상 외 SMS)
• 있으면 → 해당 세션에 코드 저장
3. WebSocket으로 셀러에게 즉시 전송
{
"type": "SMS_CODE_RECEIVED",
"code": "123456"
}
4. 세션 상태 업데이트: LOCKED → SMS_RECEIVED
Response:
{ "status": "success", "session_id": "uuid" }5. 이메일 자동화
Gmail API 폴링
[설정]
• 대상: sellerking@moonklabs.com
• 폴링 주기: 10초
• 필터: 최근 5분 내 수신 + 미처리 메일
[파싱 로직]
1. 제목 또는 본문에서 인증번호 검색
- /인증번호[^0-9]*(\d{6})/
- /verification code[:\s]*(\d{6})/i
2. 현재 EMAIL_WAITING 상태인 세션에 매칭
(SMS와 달리 이메일은 SMS 이후 단계이므로
이미 특정 세션이 식별된 상태)
3. WebSocket으로 셀러에게 전송이메일도 Lock 필요한가?
[분석]
• SMS 단계에서 이미 세션이 특정됨
• 이메일 인증은 SMS 인증 통과 후 진행
• 따라서 이메일 도착 시 어느 세션인지 명확
[결론]
이메일은 별도 Lock 불필요
SMS 단계의 Lock이 전체 인증 과정을 보호6. 사용자 시나리오
정상 플로우 (99%)
1. 셀러가 장사왕에서 "연동 시작" 클릭
2. 연동 가이드 페이지로 이동 (WebSocket 연결)
3. 가이드 따라 쿠팡 관리자에서 추가계정 생성 시작
4. 장사왕 정보(아이디, 전화번호, 이메일) 입력
5. 셀러가 장사왕 페이지에서 [인증번호 받을 준비 완료] 클릭
→ Lock 획득 (또는 대기)
6. 셀러가 쿠팡에서 "SMS 인증번호 발송" 클릭
7. (자동) 업무폰 SMS 수신 → SmsForwarder → 서버 → WebSocket
8. 셀러 화면에 인증번호 표시:
┌─────────────────────────────────────────────────────┐
│ ✅ SMS 인증번호 수신 완료! │
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ 1 2 3 4 5 6 [복사] │ │
│ └─────────────────────────────────────────┘ │
│ │
│ 위 인증번호를 쿠팡 화면에 입력해주세요 │
└─────────────────────────────────────────────────────┘
9. 셀러가 쿠팡에 인증번호 입력
10. 이메일 인증도 동일하게 진행
11. 추가계정 생성 완료
12. 장사왕에서 "연동 완료!" 표시
전화 없음 ✅
대기 없음 ✅ (Lock 경쟁 없으면)
소요 시간: 5분 이내Lock 대기 플로우 (1%)
1~4. 동일
5. 셀러 B가 [인증번호 받을 준비 완료] 클릭
→ 다른 셀러(A)가 Lock 보유 중
→ "잠시만 기다려주세요. 예상 대기: 1분 30초"
6. A 완료 또는 타임아웃 → B 자동으로 Lock 획득
7. B 화면: "이제 진행할 수 있어요!"
8. 이후 정상 플로우와 동일7. HOW: 시스템 아키텍처
전체 아키텍처
┌─────────────────────────────────────────────────────────────────────────┐
│ SMS 포워딩 기반 연동 자동화 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 셀러 브라우저 │ │
│ │ • 연동 가이드 페이지 │ │
│ │ • WebSocket 연결 (실시간 상태) │ │
│ │ • [인증번호 받을 준비 완료] 버튼 │ │
│ │ • 인증번호 실시간 표시 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ ↕ WebSocket │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 장사왕 서버 │ │
│ │ │ │
│ │ [Exclusive Lock 관리] [Webhook 수신] │ │
│ │ • Lock 획득/해제 • POST /webhook/sms-forward │ │
│ │ • 대기열 관리 • POST /webhook/email-forward │ │
│ │ • 타임아웃 처리 • 인증번호 파싱 │ │
│ │ │ │
│ │ [세션 관리] [WebSocket 서버] │ │
│ │ • 상태 머신 • 실시간 코드 전송 │ │
│ │ • 세션 데이터 • 상태 업데이트 푸시 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ ↑ ↑ │
│ HTTP Webhook HTTP Webhook │
│ │ │ │
│ ┌────────────────┴───────┐ ┌──────────────┴──────────────────┐ │
│ │ Android 업무폰 │ │ Gmail API │ │
│ │ + SmsForwarder │ │ (10초 폴링) │ │
│ │ │ │ │ │
│ │ • SMS 수신 감지 │ │ • 새 메일 확인 │ │
│ │ • 규칙 기반 필터 │ │ • 인증번호 추출 │ │
│ │ • Webhook 전송 │ │ • Webhook 전송 │ │
│ └─────────────────────────┘ └─────────────────────────────────┘ │
│ ↑ │
│ SMS 수신 │
│ │ │
│ ┌────────────────┴────────────────────────────────────────────────┐ │
│ │ 쿠팡 │ │
│ │ • 추가계정 생성 시 SMS/이메일 인증 발송 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘셀러 화면 (연동 가이드)
[STEP 1: 정보 입력 단계]
┌───────────────────────────────────────────────────────────────┐
│ 🔗 쿠팡 연동하기 │
├───────────────────────────────────────────────────────────────┤
│ │
│ ✅ 1. 연동 신청 완료 │
│ │
│ 🔄 2. 쿠팡에서 추가계정 생성 │
│ 아래 정보를 쿠팡 관리자에 입력해주세요 │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 아이디: sellerking_a1b2c3 [복사] │ │
│ │ 담당자명: 장사왕 [복사] │ │
│ │ 휴대전화: 010-1234-5678 [복사] │ │
│ │ 이메일: sellerking@moonklabs.com [복사] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ⬜ 3. SMS 인증 │
│ ⬜ 4. 이메일 인증 │
│ ⬜ 5. 연동 완료 │
│ │
│ ───────────────────────────────────────────────────────── │
│ 📌 쿠팡에 정보 입력을 완료했다면 다음 단계로 진행하세요 │
│ │
│ [다음: SMS 인증 준비하기 →] │
│ │
└───────────────────────────────────────────────────────────────┘
[STEP 2: SMS 인증 준비]
┌───────────────────────────────────────────────────────────────┐
│ 🔗 쿠팡 연동하기 │
├───────────────────────────────────────────────────────────────┤
│ │
│ ✅ 1. 연동 신청 완료 │
│ ✅ 2. 쿠팡에서 추가계정 생성 │
│ │
│ 🔄 3. SMS 인증 │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 쿠팡에서 "인증번호 발송" 버튼을 누르기 전에 │ │
│ │ 아래 버튼을 먼저 눌러주세요. │ │
│ │ │ │
│ │ [🔔 인증번호 받을 준비 완료] │ │
│ │ │ │
│ │ 버튼 클릭 후 2분 안에 쿠팡에서 인증을 요청하세요 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ⬜ 4. 이메일 인증 │
│ ⬜ 5. 연동 완료 │
│ │
└───────────────────────────────────────────────────────────────┘
[STEP 2-1: Lock 대기 중 (드문 케이스)]
┌───────────────────────────────────────────────────────────────┐
│ 🔄 3. SMS 인증 │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ ⏳ 잠시만 기다려주세요 │ │
│ │ │ │
│ │ 다른 셀러님의 인증이 진행 중이에요. │ │
│ │ 곧 순서가 돌아옵니다. │ │
│ │ │ │
│ │ 예상 대기 시간: 약 1분 30초 │ │
│ │ │ │
│ │ ████████████░░░░░░░░ │ │
│ │ │ │
│ │ 💡 창을 닫지 마세요. 자동으로 진행됩니다. │ │
│ └─────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────┘
[STEP 2-2: Lock 획득, SMS 대기 중]
┌───────────────────────────────────────────────────────────────┐
│ 🔄 3. SMS 인증 │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ ✅ 준비 완료! │ │
│ │ │ │
│ │ 지금 쿠팡에서 "인증번호 발송"을 눌러주세요. │ │
│ │ 인증번호가 도착하면 여기에 자동으로 표시됩니다. │ │
│ │ │ │
│ │ ⏱️ 남은 시간: 1:45 │ │
│ │ │ │
│ │ 🔄 인증번호 대기 중... │ │
│ └─────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────┘
[STEP 2-3: SMS 인증번호 수신 완료]
┌───────────────────────────────────────────────────────────────┐
│ ✅ 3. SMS 인증 │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ ✅ 인증번호 수신 완료! │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────┐ │ │
│ │ │ 1 2 3 4 5 6 [복사] │ │ │
│ │ └─────────────────────────────────────────┘ │ │
│ │ │ │
│ │ 위 인증번호를 쿠팡 화면에 입력해주세요 │ │
│ │ │ │
│ │ 입력을 완료했다면: │ │
│ │ [다음: 이메일 인증 →] │ │
│ └─────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────┘
[STEP 5: 연동 완료]
┌───────────────────────────────────────────────────────────────┐
│ 🔗 쿠팡 연동하기 │
├───────────────────────────────────────────────────────────────┤
│ │
│ ✅ 1. 연동 신청 완료 │
│ ✅ 2. 쿠팡에서 추가계정 생성 │
│ ✅ 3. SMS 인증 │
│ ✅ 4. 이메일 인증 │
│ ✅ 5. 연동 완료 │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 🎉 연동이 완료되었어요! │ │
│ │ │ │
│ │ 이제 쿠팡 데이터를 분석할 수 있어요. │ │
│ │ 데이터 수집에 최대 24시간이 소요될 수 있습니다. │ │
│ │ │ │
│ │ [대시보드로 이동 →] │ │
│ │ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────┘어드민 화면 (연동 모니터링)
[어드민 - 연동 현황]
┌───────────────────────────────────────────────────────────────┐
│ 📊 연동 현황 [새로고침] │
├───────────────────────────────────────────────────────────────┤
│ │
│ 🔒 현재 Lock: 김셀러 (shop_123) - 남은 시간 1:23 │
│ │
│ [전체] [진행중] [대기중] [완료] [실패] │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 🔵 김셀러 (shop_123) LOCKED │ │
│ │ 10:30 시작 │ Lock 보유 중 │ SMS 대기 │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ 🟡 박셀러 (shop_456) WAITING_FOR_LOCK │ │
│ │ 10:31 시작 │ 대기 중 (예상: 1분 23초) │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ 🟢 이셀러 (shop_789) COMPLETED │ │
│ │ 10:15 시작 │ 10:22 완료 │ 소요 7분 │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ 🔴 최셀러 (shop_012) LOCK_TIMEOUT │ │
│ │ 10:00 시작 │ Lock 타임아웃 (2분 초과) │ │
│ │ [🔄 재시도 안내 발송] [📞 수동 연결] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 📈 오늘 통계: 완료 12건 / 진행 2건 / 실패 1건 │
│ │
└───────────────────────────────────────────────────────────────┘디자인 요청사항
| 항목 | 내용 |
|---|---|
| 톤앤매너 | 진행 상황이 명확히 보이는 스텝 UI |
| 컬러 | 완료=초록, 진행중=파랑, 대기=노랑, 실패=빨강 |
| 애니메이션 | Lock 대기 시 프로그레스 바, SMS 대기 시 스피너 |
| 인증번호 | 큰 폰트, 자간 넓게, 복사 버튼 강조 |
| 참고 | 카카오뱅크 계좌 개설 플로우, 토스 인증 플로우 |
8. EDGE: 예외 & 엣지 케이스
Lock 관련 예외
| 상황 | 처리 방법 |
|---|---|
| Lock 보유 중 SMS 미수신 (2분 초과) | Lock 자동 해제 + "시간 초과. 다시 시도해주세요" 안내 |
| Lock 대기 중 셀러 이탈 | 대기열에서 제거 (WebSocket 연결 끊김 감지) |
| Lock 보유자가 새로고침 | WebSocket 재연결 시 세션 유지 (session_id 기반) |
| 동시에 Lock 요청 | 서버 측 atomic 연산으로 1명만 획득, 나머지 대기 |
SMS 관련 예외
| 상황 | 처리 방법 |
|---|---|
| SMS 미수신 (2분 타임아웃) | Lock 해제 + 재시도 안내 |
| 인증번호 형식 오류 | 6자리 숫자 아니면 무시, 로그 기록 |
| Lock 없을 때 SMS 도착 | 무시 (예상 외 SMS, 로그만 기록) |
| SmsForwarder 앱 중지 | 어드민 알림 + 수동 모드 전환 |
이메일 관련 예외
| 상황 | 처리 방법 |
|---|---|
| 이메일 미수신 (3분 초과) | 스팸함 확인 안내 + 재요청 버튼 |
| 이메일 파싱 실패 | 로그 기록 + 어드민 알림 |
| Gmail API 장애 | 어드민에서 수동 입력 UI 제공 |
시스템 예외
| 상황 | 처리 방법 |
|---|---|
| 웹훅 서버 장애 | Fallback: 어드민에서 수동 코드 입력 |
| WebSocket 연결 끊김 | 자동 재연결 (3회 시도), 실패 시 폴링 모드 |
| Android 폰 장애 | 알림 + 수동 모드 전환 |
사용자 예외
| 상황 | 처리 방법 |
|---|---|
| 셀러가 중간에 이탈 | Lock 보유 시 타임아웃 후 해제, 세션 30분 유지 |
| 셀러가 잘못된 정보 입력 | 쿠팡에서 오류 → 처음부터 재시도 안내 |
| 이미 연동된 계정 | 중복 연동 감지 → 기존 연동 정보 안내 |
| 브라우저 뒤로가기 | 현재 단계로 리다이렉트 |
9. 성공 지표
이 에픽의 성공 기준
| 지표 | Before | Target | 측정 방법 |
|---|---|---|---|
| 유선 통화 | 100% | 0% | 연동 시 전화 건수 |
| 스팸 차단 | 발생 | 0건 | CS 접수 건수 |
| 연동 소요 시간 | 15분 | 5분 이내 | 세션 시작~완료 시간 |
| 자동 연동 성공률 | - | 90%+ | 자동 완료 / 전체 시도 |
| 영업시간 외 연동 | 0% | 측정 시작 | 18시 이후 완료 건 |
모니터링 지표
| 지표 | 설명 | 알림 기준 |
|---|---|---|
| SMS 웹훅 수신율 | Lock 상태에서 SMS 도착률 | < 90% 시 알림 |
| Lock 타임아웃 비율 | 2분 초과 건 | > 20% 시 알림 |
| Lock 대기 발생률 | 대기 발생 건수 | 모니터링 (참고용) |
| 평균 Lock 대기 시간 | 대기 시작~획득 시간 | > 1분 시 알림 |
| 이메일 파싱 성공률 | 이메일 수신 대비 파싱 성공 | < 95% 시 알림 |
| WebSocket 연결 안정성 | 연결 끊김 비율 | > 5% 시 알림 |
GA4 이벤트
| 이벤트명 | 트리거 | 파라미터 |
|---|---|---|
integration_started | 연동 시작 | seller_id, platform |
integration_lock_acquired | Lock 획득 | seller_id, wait_time |
integration_lock_waited | Lock 대기 발생 | seller_id, queue_position |
integration_sms_received | SMS 수신 | seller_id, duration |
integration_completed | 연동 완료 | seller_id, total_duration |
integration_failed | 연동 실패 | seller_id, reason, step |
10. 의존성 & 제약
기술 의존성
| 의존 항목 | 상태 | 비고 |
|---|---|---|
| Android 업무폰 | ✅ 확보 필요 | 기존 번호 이관 또는 신규 번호 |
| SmsForwarder 앱 | ✅ 오픈소스 | BSD-2-Clause, 무료 |
| Gmail API | ⏳ 설정 필요 | OAuth2 + API 키 발급 |
| WebSocket 서버 | ⏳ 개발 필요 | 실시간 통신용 |
| Webhook 수신 API | ⏳ 개발 필요 | /webhook/sms-forward |
인프라 요구사항
| 항목 | 사양 | 비고 |
|---|---|---|
| Android 폰 | 7.0 이상 | SmsForwarder 요구사항 |
| 네트워크 | Wi-Fi 상시 연결 | 업무폰 WebHook 전송용 |
| 충전 | 상시 충전 | 24시간 운영 |
| Gmail 계정 | sellerking@moonklabs.com | 기존 계정 사용 |
제약 조건
- Exclusive Lock: SMS 인증 단계는 한 번에 한 명만 가능 → 동시 다수 연동 불가
- Lock 시간 제한: 2분 내 SMS 수신 필요 → 타임아웃 시 재시도
- Android 폰 의존: 폰 장애 시 자동 연동 중단 → Fallback: 수동 모드
- 인증번호 유효시간: 보통 3~5분 → Lock 내 빠른 처리 필요
확인 필요 사항
| 항목 | 담당 | 상태 |
|---|---|---|
| SmsForwarder 설치 및 웹훅 테스트 | 하록 | ⏳ PoC 필요 |
| Gmail API OAuth2 설정 | 하록 | ⏳ 설정 필요 |
| Android 업무폰 확보 | 운영팀 | ⏳ 구매/기존폰 활용 검토 |
| WebSocket 인프라 선정 | 하록 | ⏳ Socket.io vs 자체 구현 |
11. 스토리 목록 (예정)
Epic Spec 승인 후 분해
| Story ID | 제목 | 규모 | 의존성 | 상태 |
|---|---|---|---|---|
| E-05-S-01 | Exclusive Lock 시스템 구현 | M | - | draft |
| E-05-S-02 | SMS Webhook 수신 API | S | - | draft |
| E-05-S-03 | SmsForwarder 설정 + PoC | S | Android 폰 | draft |
| E-05-S-04 | 연동 세션 상태 머신 | M | S-01 | draft |
| E-05-S-05 | WebSocket 실시간 통신 | M | S-04 | draft |
| E-05-S-06 | Gmail API 이메일 파싱 | M | - | draft |
| E-05-S-07 | 셀러 연동 가이드 UI | L | S-04, S-05 | draft |
| E-05-S-08 | 어드민 연동 모니터링 UI | M | S-04 | draft |
| E-05-S-09 | Lock 타임아웃 & 알림 처리 | S | S-01, S-05 | draft |
| E-05-S-10 | E2E 테스트 + 운영 가이드 | M | 전체 | draft |
구현 순서 제안
Phase 1: 기반 (1주)
├─ S-01: Exclusive Lock 시스템
├─ S-02: SMS Webhook API
└─ S-03: SmsForwarder PoC
Phase 2: 핵심 (1주)
├─ S-04: 세션 상태 머신
├─ S-05: WebSocket
└─ S-06: Gmail API
Phase 3: UI (1주)
├─ S-07: 셀러 연동 UI
├─ S-08: 어드민 모니터링
└─ S-09: 타임아웃 처리
Phase 4: 마무리 (0.5주)
└─ S-10: E2E 테스트 + 가이드12. 체크리스트
PO 승인 전 체크
- [x] 문제 정의가 명확한가? (스팸 차단, 신뢰 훼손, 법적 리스크)
- [x] 비즈니스 로직이 구체적인가? (Exclusive Lock, 상태 머신)
- [x] 와이어프레임/플로우가 있는가? (7개 화면 상태)
- [x] 엣지 케이스가 정의되었는가? (Lock/SMS/Email/시스템/사용자)
- [x] 성공 지표가 측정 가능한가? (유선통화 0%, 스팸 0건)
- [ ] 기술 의존성이 확인되었는가? (SmsForwarder PoC 필요)
미결 사항 (승인 전 완료 불필요, 개발 단계에서 진행)
| 항목 | 상태 | 담당 | 비고 |
|---|---|---|---|
| SmsForwarder PoC | ⏳ 테스트 필요 | 하록 | S-03에서 진행 |
| Android 업무폰 확보 | ⏳ 검토 필요 | 운영팀 | 기존폰/신규폰 |
| Gmail API 설정 | ⏳ 설정 필요 | 하록 | S-06에서 진행 |
핵심 결정 사항 (확정)
| 항목 | 결정 | 근거 |
|---|---|---|
| 세션 매칭 방식 | Exclusive Lock | 100% 정확도 필수 (법적 리스크) |
| SMS 자동화 | SmsForwarder (Android) | 오픈소스, 무료, Webhook 지원 |
| Lock 타임아웃 | 2분 | 인증번호 유효시간 고려 |
| 유선 통화 | 완전 제거 | 스팸 오해 근절 |
승인
| 항목 | 확인 |
|---|---|
| PO 승인 | ☑️ |
| 승인일 | 2026-01-20 |
| 비고 | Exclusive Lock 기반 설계로 100% 정확 매칭 보장 |
작성일: 2026-01-20최종 수정: 2026-01-20주요 변경: AI Agent 방식 → SmsForwarder + Exclusive Lock 방식으로 전환