Repository navigation
[FEAT] 메일 발송 내구성 및 재시도 처리 #670
Description
📃 요약
메일 발송 요청과 외부 SES 호출 사이의 장애 구간을 보완합니다. 서버 재기동·프로세스 장애·일시적 SES 오류가 발생해도 작업 결과를 잃거나 중복 발송하지 않도록 영속적인 실행 경계를 마련합니다.
#629는 요청 시점의 즉시 발송과 기본 결과 저장까지만 담당합니다. 이 이슈에서 내구성 있는 비동기 실행과 재시도 정책을 별도로 설계·구현합니다.
구현 범위
- DB 저장과 외부 메일 호출 사이의 dual-write 문제를 해결하는 Outbox 또는 동등한 영속 큐 구조
- 발송 작업과 수신자 대상의 재기동 복구·claim·lease·중복 실행 방지
- SES 오류를 재시도 가능 오류와 영구 실패로 분류
- 최대 재시도 횟수, backoff, 대상별 최종 실패 상태와 실패 사유 저장
- 같은
requestedByAdminId와Idempotency-Key로 다른 요청 본문을 보낸 경우 기존 결과를 재사용하지 않고 충돌로 거부- 비교 대상:
scenarioId,recruitId,applyIds, 제목 덮어쓰기, 입력 변수
- 비교 대상:
- 재시도와 복구 결과를 관찰할 수 있는 로그·메트릭·알림 기준
완료 조건
- 작업 저장 직후 프로세스가 중단되어도 재기동 후 미처리 대상을 복구한다.
- 동시 워커가 같은 대상을 중복 처리하지 않는다.
- 재시도 가능 오류만 정책에 따라 재시도하고 영구 실패는 즉시 종료한다.
- 최대 재시도 횟수와 다음 시각을 저장·검증할 수 있다.
- 같은 idempotency key의 요청 본문이 다르면 명확한 충돌 오류를 반환한다.
- 외부 호출 성공 후 DB 기록 실패, DB 기록 후 프로세스 중단 등 장애 시나리오를 테스트한다.
- 운영자가 작업 상태와 재시도·복구 결과를 추적할 수 있다.
이번 이슈에서 하지 않는 것
- 메일 템플릿 CRUD 또는 대상자 조회
- 발송 이력 조회 API 자체의 화면·검색 기능
- 예약 시각 기반 스케줄러 정책
- SES 외 공급자 추가
📎 참고 자료 (선택)
- [FEAT] 단체 메일 발송 및 발송 이력 기록 #629
- AWS Transactional Outbox: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html
- AWS asynchronous processing: https://docs.aws.amazon.com/prescriptive-guidance/latest/modernization-integrating-microservices/asynchronous.html
- Stripe idempotent requests: https://docs.stripe.com/api/idempotent_requests
Activity
023-dev commentedon Sep 9, 2026
후속 구현 설계 기준
#670 구현 전 다음 경계를 기준으로 확정합니다.
PENDING → PROCESSING → SENT/FAILED로 관리하고,attempt_count,next_attempt_at,lease_until, 마지막 안전 오류 코드를 저장합니다. lease가 만료된PROCESSING은 재기동 시 회수합니다.FAILED로 종료합니다.requestedByAdminId + Idempotency-Key를 unique로 유지하고, canonical JSON fingerprint가 다르면 충돌 오류를 반환합니다. 비교 대상은scenarioId,recruitId,applyIds, 제목 덮어쓰기, 입력 변수입니다.별도 결정 필요
외부 SES 성공 직후 DB 기록 전에 프로세스가 중단되면, SES 자체 멱등성 키가 없어 외부 발송의 정확히 한 번 처리를 보장할 수 없습니다. 따라서 구현 PR 시작 전
at-least-once + 중복 완화를 허용할지, SES 호출 경계에 별도 중복 방지 수단을 둘지 결정해야 합니다.이번 단계에서는 설계 기준만 정리하고 Outbox·워커·재시도 코드는 별도 PR로 구현합니다.
feat/#670 Idempotency-Key 요청 본문 검증 (#682)
feat/#670 발송 Outbox 저장 (#683)
feat/#670 Outbox claim과 lease 복구 (#684)
test: #670 V45·V46 Flyway 마이그레이션 검증 추가
test: #670 Outbox migration 제약 검증 추가
test: #670 V45 이전 fingerprint 누락 요청 충돌 검증 추가
fix: #670 fingerprint 없는 작업 요청 충돌 처리 수정
test: #670 Outbox 통합 테스트 기반 클래스 상속 추가
test: #670 통합 테스트 기반 클래스 상속 추가
test: #670 MySQL 동시 키 충돌 검증 추가
test: #670 MySQL 통합 테스트 dialect 설정 수정
17 remaining items
test: #670 메일 결과 조회 중복 검증 통합
test: #670 메일 migration 테스트 실행 환경 정리
test: #670 메일 요청 fingerprint 필드별 변경 검증 추가
Merge pull request #696 from JECT-Study/feat/670-mail-ses-outcome-cla…
Merge pull request #693 from JECT-Study/feat/670-mail-dispatch-claim-…
Merge pull request #688 from JECT-Study/feat/670-mail-dispatch-outbox…
feat: #670 메일 발송 worker 및 미처리 대상 자동 복구 구현 (#698)
chore: #670 dev 대상 메일 CI 실행
feat: #670 메일 worker·복구 및 안전한 재시도 dev 통합 (#700)
chore: #670 dev 병합 후 장애 복구 PR 기준 정리
feat: #670 메일 발송 장애 복구 검증 및 운영 관측 보강 (#702)
chore: #670 dev 병합 후 조회 검증 PR 기준 정리
test: #670 메일 조회 검증 통합 및 요청 식별 테스트 보강 (#706)
feat: #502 메일 예약 생성·조회 및 취소 기반 구현 (#707)