Story: Gmail API 이메일 파싱

메타

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

---

사용자 스토리

As a 시스템,
I want Gmail에서 수신된 이메일을 자동으로 파싱하여 인증번호를 추출하고 싶다,
So that 이메일 인증도 자동화할 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: Gmail API 연동

항목	내용
Given	Gmail API OAuth2 설정이 완료되었을 때
When	서버가 시작되면
Then	Gmail API에 연결되어 이메일을 조회할 수 있다

AC-02: 이메일 폴링

항목	내용
Given	API 연결된 상태에서
When	EMAIL_WAITING 상태인 세션이 있을 때
Then	10초마다 새 이메일을 확인한다

AC-03: 인증번호 추출

항목	내용
Given	새 이메일이 수신되었을 때
When	제목 또는 본문에서 인증번호를 파싱하면
Then	6자리 숫자 인증번호를 추출한다

AC-04: 세션 연동

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

---

태스크 분해

Task 1: Gmail API 설정 AC-01

• [ ] 1.1: Google Cloud Console 프로젝트 설정
• [ ] 1.2: Gmail API 활성화
• [ ] 1.3: OAuth2 자격 증명 생성
• [ ] 1.4: Refresh Token 저장 (환경변수)

Task 2: 이메일 폴링 AC-02

• [ ] 2.1: Gmail API 클라이언트 구현
• [ ] 2.2: 10초 간격 스케줄러
• [ ] 2.3: 최근 5분 내 미처리 메일 필터

Task 3: 인증번호 파싱 AC-03

• [ ] 3.1: 이메일 본문 추출 (HTML → Text)
• [ ] 3.2: 정규식 패턴 매칭
  • /인증번호[^0-9]*(\d{6})/
  • /verification code[:\s]*(\d{6})/i
• [ ] 3.3: 파싱 실패 시 로깅

Task 4: 세션 연동 AC-04

• [ ] 4.1: EMAIL_WAITING 세션 조회
• [ ] 4.2: emailCode 저장 + 상태 변경
• [ ] 4.3: WebSocket 이벤트 발송

---

Gmail API 설정 가이드

1. Google Cloud Console

1. https://console.cloud.google.com 접속
2. 새 프로젝트 생성 또는 기존 프로젝트 선택
3. Gmail API 활성화

2. OAuth2 자격 증명

1. API 및 서비스 > 자격 증명
2. OAuth 2.0 클라이언트 ID 생성
3. 리다이렉트 URI 설정
4. Client ID, Client Secret 저장

3. Refresh Token 발급

// OAuth 동의 후 Refresh Token 저장
const token = await oauth2Client.getToken(code);
// token.refresh_token 저장

---

Dev Notes

이메일 패턴 예시

제목: [쿠팡] 이메일 인증번호 안내
본문: 인증번호 [123456]을 입력해주세요.

폴링 vs Push

방식	장점	단점
폴링 (선택)	구현 간단	지연 최대 10초
Push (Pub/Sub)	즉시 수신	설정 복잡

→ 10초 지연 허용 가능하므로 폴링 선택

의존성

• E-05-S-04: 세션 상태 머신
• E-05-S-05: WebSocket

---

생성일: 2026-01-20