Repository navigation
Closed
Labels
Description
목적 (Why)
무엇을 추가/변경하나?
- 인증 이메일을 DB 기반 작업으로 저장하고 재시작·다중 서버 환경에서 복구한다.
왜 필요한가? (User value / Problem)
- 현재 AFTER_COMMIT 이벤트와 메모리 기반 @retryable은 프로세스 종료 시 미발송 작업과 재시도 횟수를 잃는다.
Out of scope / Non-goals
- SMTP exactly-once 보장, 자동 병합·운영 배포, 기존 FCM Outbox 변경.
비즈니스/기술적 배경
- 최초 시도 포함 최대 4회와 5→10→20초 지수 백오프를 유지한다. 사용자 요청의 3분 재전송 제한은 토큰 생성 시각을 기준으로 유지한다.
전체 설계 (How)
핵심 아이디어/접근법
- 인증 토큰과 email_jobs를 같은 트랜잭션에서 저장한다.
- PostgreSQL 행 잠금(SKIP LOCKED)으로 작업을 선점하고 시도 횟수·이력을 함께 커밋한다. SMTP 호출은 DB 트랜잭션 밖에서 수행한다.
- 현재 선점의 시도 번호로 완료 UPDATE를 제한해 오래된 워커의 상태 덮어쓰기를 막는다.
주요 컴포넌트/모듈
- 작업 저장소, 주기/시작 시 복구 워커, SMTP 오류 분류기, Flyway 마이그레이션.
데이터 흐름/상태 변화
- PENDING → SENDING → SUCCEEDED / RETRY_WAIT / FAILED. 만료된 SENDING은 횟수를 유지하며 복구한다.
PR 분할 전략 (리뷰어가 부담을 느끼질 않도록)
- 하나의 원자적인 기능 PR: 저장·선점·실행·기존 경로 교체·장애 검증이 함께 적용되어야 누락/이중 발송 경로를 피할 수 있다. 테스트 포함 300라인 초과 예상.
부분 머지 안전성
- 기능 전체를 함께 적용한다. 스키마 확장은 기존 버전과 호환되지만 구버전 메모리 작업은 복구할 수 없다.
전체 Acceptance Criteria (AC)
- AC1: 상태 5종, 시도 횟수, 마지막 시도/다음 재시도 시각을 DB에 저장한다.
- AC2: 시작 및 주기 실행에서 PENDING·기한 도래 RETRY_WAIT·오래된 SENDING을 복구한다.
- AC3: 다중 서버의 동일 작업 선점을 방지하고 오래된 선점자의 상태 변경을 차단한다.
- AC4: DB 기준 최대 4회/지수 백오프 및 SMTP 일시 오류와 영구 오류 분류를 적용한다.
- AC5: 작업 ID와 시도 이력을 남기고 SMTP 수락 후 DB 기록 전 장애의 중복 가능성을 문서화한다.
- AC6: 최종 실패를 보존하며 자동 재시도는 토큰 생성/3분 재전송 제한을 갱신하지 않는다.
- AC7: 재시작·동시 실행·SMTP 성공 후 DB 기록 실패·횟수 소진·트랜잭션 롤백을 검증한다.
영향 범위
- API 스펙 변경
- DB 스키마 변경: email_jobs 및 시도 이력 테이블 추가
- 설정/환경변수 변경: polling/lease, SMTP timeout
- 라이브러리 추가/업그레이드
- 외부 연동 영향: SMTP 재시도 분류 및 실행 시점
롤아웃/관측 (배포 전략)
- DB 작업 상태와 시도 이력, 비식별 로그/Trace로 관측한다. 실제 SMTP 운영 발송은 로컬 검증 범위에 포함하지 않는다.
리스크 & 롤백
리스크
- SMTP와 DB를 원자적으로 커밋할 수 없어 수락 후 장애 시 중복 발송 가능. exactly-once는 보장하지 않는다.
- 작업 payload에 인증 링크가 포함되므로 로그 노출 금지와 저장/보존 정책을 명시한다.
롤백 전략
- 워커를 중지하고 진행 중 SMTP 처리를 종료한 뒤 대기 작업을 확인한다. 이전 버전은 DB 작업을 처리하지 않으므로 단순 코드 롤백만으로 미완료 작업을 폐기하지 않는다.
의존성
- 선행 이슈/PR: 없음. 기존 FCM Outbox 선점 이슈 #262와는 별도 범위.
증빙/참고 자료
- 구현 PR에 실제 검증 명령·결과 및 장애 한계를 첨부한다.
구현·검증: PR #271에서 전체 338개 테스트와 빌드/정적 검사 통과를 확인했습니다. 사람 리뷰·병합·운영 배포는 별도이며 이슈는 열린 상태로 유지합니다.
최신 커밋 ef294334은 로컬 전체 검사 및 GitHub CI를 통과했습니다. 최초 CI의 기존 해변 스케줄러 Trace 테스트 1회 실패는 로컬 분리 실행과 동일 커밋 재실행에서 재현되지 않았으며, 원인 미확정 사항으로 PR에 기록했습니다.
리뷰 보완: 기존 메일 실행기에서 최대 3개 소비 작업 실행, 메일 비활성화 시 작업 생성·처리·키 검증 제외, 20건 배치 내 무효 후보 뒤 조회 지속, 복호화 실패의 암호문 보존. 새 의존성·추가 스키마 변경은 없습니다.
추가 정리: 주기 실행은 소비 작업 하나로 시작하고 실제 작업 발견 시에만 최대 3개까지 늘립니다. 미사용 Trace fixture/RetryConfig와 중복 설정 검증을 제거하고 기존 DB 보존 검증은 유지했습니다.
Activity
fix: 이메일 작업 실행 격리와 비활성화 호환성 보완
perf: 이메일 유휴 조회와 중복 테스트 정리