Story: WebSocket 실시간 통신

메타

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

---

사용자 스토리

As a 셀러,
I want 인증번호가 도착하면 화면에 즉시 표시되길 원한다,
So that 새로고침 없이 바로 확인할 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: WebSocket 연결

항목	내용
Given	셀러가 연동 페이지에 진입했을 때
When	페이지가 로드되면
Then	WebSocket 연결이 자동으로 수립된다

AC-02: 인증번호 실시간 표시

항목	내용
Given	WebSocket 연결된 상태에서
When	서버에서 SMS 인증번호를 수신하면
Then	셀러 화면에 즉시 인증번호가 표시된다

AC-03: 상태 변경 푸시

항목	내용
Given	WebSocket 연결된 상태에서
When	세션 상태가 변경되면
Then	클라이언트에 상태 변경이 즉시 푸시된다

AC-04: 재연결 처리

항목	내용
Given	WebSocket 연결이 끊어졌을 때
When	재연결을 시도하면
Then	자동으로 3회까지 재연결을 시도한다
And	실패 시 폴링 모드로 전환된다

---

태스크 분해

Task 1: BE - WebSocket 서버 AC-01, AC-03

• [ ] 1.1: WebSocket 서버 설정 (Socket.io 또는 ws)
• [ ] 1.2: 세션별 룸 관리 (session_id 기반)
• [ ] 1.3: 상태 변경 시 브로드캐스트

Task 2: BE - 이벤트 정의 AC-02, AC-03

• [ ] 2.1: SMS_CODE_RECEIVED 이벤트
• [ ] 2.2: STATUS_CHANGED 이벤트
• [ ] 2.3: LOCK_ACQUIRED 이벤트
• [ ] 2.4: LOCK_WAIT 이벤트

Task 3: FE - WebSocket 클라이언트 AC-01, AC-04

• [ ] 3.1: WebSocket 연결 훅 구현
• [ ] 3.2: 이벤트 핸들러 구현
• [ ] 3.3: 자동 재연결 로직 (3회)
• [ ] 3.4: 폴링 Fallback

---

WebSocket 이벤트

서버 → 클라이언트

이벤트	페이로드	설명
SMS_CODE_RECEIVED	{code: "123456"}	SMS 인증번호 수신
EMAIL_CODE_RECEIVED	{code: "654321"}	이메일 인증번호 수신
STATUS_CHANGED	{status: "LOCKED", ...}	세션 상태 변경
LOCK_ACQUIRED	{expires_in: 120}	Lock 획득
LOCK_WAIT	{position: 2, estimated: 90}	Lock 대기

클라이언트 → 서버

이벤트	페이로드	설명
JOIN_SESSION	{session_id: "xxx"}	세션 룸 참여
LEAVE_SESSION	{session_id: "xxx"}	세션 룸 퇴장

---

Dev Notes

기술 선택

옵션	장점	단점
Socket.io	자동 재연결, 폴백	라이브러리 의존
ws (native)	가벼움	직접 구현 필요

→ Socket.io 추천 (재연결, 브라우저 호환성)

의존성

• E-05-S-04: 세션 상태 머신 (상태 변경 트리거)
• E-05-S-02: SMS Webhook (코드 수신 트리거)

---

생성일: 2026-01-20