Story: SMS Webhook 수신 API

메타

항목	값
Story ID	E-05-S-02
Epic	E-05 연동 자동화
상태	ready-for-dev
우선순위	P0
규모	S
담당 개발자	하록 (BE)

---

사용자 스토리

As a 시스템,
I want SmsForwarder에서 전송한 SMS Webhook을 수신하고 인증번호를 추출하고 싶다,
So that Lock 보유 중인 셀러에게 인증번호를 전달할 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: Webhook 수신

항목	내용
Given	SmsForwarder가 SMS를 수신했을 때
When	Webhook이 서버로 전송되면
Then	서버가 정상적으로 수신하고 200 응답을 반환한다

AC-02: 인증번호 추출

항목	내용
Given	SMS 내용이 수신되었을 때
When	인증번호 패턴을 파싱하면
Then	6자리 숫자 인증번호를 추출한다

패턴 예시:
"[쿠팡] 인증번호 [123456]을 입력해주세요." → 123456
"인증번호: 654321" → 654321

AC-03: Lock 보유 세션에 전달

항목	내용
Given	인증번호가 추출되었을 때
When	Lock 보유 중인 세션이 있으면
Then	해당 세션에 인증번호를 저장하고 WebSocket으로 전달한다

AC-04: Lock 없을 때 처리

항목	내용
Given	인증번호가 추출되었을 때
When	Lock 보유 중인 세션이 없으면
Then	로그만 기록하고 무시한다

---

태스크 분해

Task 1: Webhook 엔드포인트 AC-01

• [ ] 1.1: POST /webhook/sms-forward 엔드포인트 생성
• [ ] 1.2: Request body 파싱 (from, content, timestamp)
• [ ] 1.3: 인증 토큰 검증 (선택적)

Task 2: 인증번호 파싱 AC-02

• [ ] 2.1: 정규식 패턴 정의
  • /인증번호[^0-9]*(\d{6})/
  • /\[(\d{6})\]/
  • /인증코드[:\s]*(\d{6})/
• [ ] 2.2: 다중 패턴 매칭 로직

Task 3: 세션 연동 AC-03, AC-04

• [ ] 3.1: 현재 LOCKED 상태 세션 조회
• [ ] 3.2: 세션에 sms_code 저장
• [ ] 3.3: 세션 상태 LOCKED → SMS_RECEIVED 변경
• [ ] 3.4: WebSocket 이벤트 발송 (E-05-S-05 연동)

---

API 스펙

POST /webhook/sms-forward

Request:

{
  "from": "15771234",
  "content": "[쿠팡] 인증번호 [123456]을 입력해주세요.",
  "timestamp": "2026-01-20T10:01:30Z"
}

Response (성공):

{
  "status": "success",
  "session_id": "uuid",
  "code_extracted": true
}

Response (Lock 없음):

{
  "status": "ignored",
  "reason": "no_active_lock"
}

---

Dev Notes

보안 고려사항

• Webhook URL은 외부 노출 최소화
• 선택적: API Key 또는 IP 화이트리스트

의존성

• E-05-S-01: Exclusive Lock (세션 조회용)
• E-05-S-05: WebSocket (코드 전달용)

---

생성일: 2026-01-20