[Reliability] 이벤트 유실 방지·재처리 기반 구현 #25

한 줄 목표

DB 상태 변경 직후 Server가 종료되거나 handler가 실패해도 후속 작업을 잃지 않고, 중복 전달에도 업무 결과가 한 번만 만들어지도록 합니다.

초보자용 설명

Task 생성·취소와 “다음에 처리할 이벤트”를 따로 저장하면 중간 종료 때 하나만 남을 수 있습니다. 같은 transaction 안에 두 내용을 저장하고, 실패하거나 서버가 재시작되면 안전하게 이어서 처리합니다.

확정한 기술 선택

• DomainEventPublisher Port 뒤에 PostgreSQL Transactional Outbox adapter를 사용합니다.
• event_publication은 처리할 이벤트, event_consumption은 handler별 완료 기록입니다.
• Spring Boot 4.1에서 lease·실패 분류·backoff·handler별 멱등성을 명시적으로 통제합니다.
• MVP에서는 Kafka/RabbitMQ와 별도 Testcontainers 의존성을 추가하지 않습니다.
• 실제 PostgreSQL 검증은 저장소의 기존 GitHub Actions PostgreSQL 17 service를 사용합니다.

Event envelope

• eventId, eventType, payloadVersion
• aggregateType, aggregateId, companyId
• actorType, 안전한 actorId
• requestId, traceId, occurredAt
• 기능별 allow-list를 통과한 최소 payload

JWT, Link 원문 token, 여권·외국인등록·전화·계좌번호, 비밀번호, 전체 Prompt를 넣지 않습니다.

구현 범위

• DB 변경과 publication record를 한 transaction으로 저장
• 상태·시도 횟수·다음 시각·완료/안전한 오류 코드 저장
• restart 시 lease 만료 record 자동 회수
• handler별 완료 receipt, unique constraint, optimistic lock
• 지수 backoff와 최대 시도 후 REVIEW_REQUIRED 전환
• 원자성·재시작·중복 전달·영구 실패 통합 테스트
• PostgreSQL 17 migration·FK·CHECK·UNIQUE·index CI 테스트
• backlog·oldest delay·retry·review required metric
• Task 생성·취소 event를 실제 업무 transaction에 연결
• 초보자용 개발·운영·장애 복구 문서 작성

AI retry와 섞지 않기

• 이 이슈: Server 내부 event와 work item의 durable delivery
• [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24: AiRun business/manual retry와 attempt lifecycle
• [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8: Server → AI Runtime timeout/circuit/bulkhead, 투명 다중 retry 없음
• fowoco/ai: 한 Runtime attempt 내부 Provider retry

완료 조건

• DB 변경과 publication 사이 유실 구간이 없습니다.
• handler 실패와 Server restart 뒤 자동 복구됩니다.
• 같은 event를 두 번 받아도 완료된 handler 결과가 중복되지 않습니다.
• 영구 실패를 성공으로 위장하지 않고 requestId/traceId로 찾을 수 있습니다.
• 개인정보가 event/log/metric label에 없습니다.
• 전체 H2 테스트·실행 JAR 빌드·GitHub PostgreSQL CI가 통과합니다.

진행 상황

• 구현 PR: feat: 이벤트 유실 방지와 재처리 Outbox 기반 구현 #50
• 담당: @hywznn
• 리뷰 요청: @chaeliki
• 현재 단계: 승인·CI 통과, 병합 대기

관계

• 완료된 선행 작업: [Architecture] 저장소 경계·모듈·API·이벤트 계약 ADR 작성 #23, [Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6, [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11
• 후속 소비자: [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24, [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8, [Worker Link] 로그인 없는 근로자 보안 링크와 응답 구현 #7
• RLS 연동: #34에서 tenant-safe Outbox claim bootstrap 계약 확정 필요
• Parent: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2