[Reliability] REVIEW_REQUIRED 수동 재처리 API와 감사로그 구현

[hywznn]

한 줄 목표

자동 재시도를 멈춘 REVIEW_REQUIRED Outbox 이벤트를 운영자가 DB를 직접 수정하지 않고, 권한·사유·버전 검증과 감사로그를 거쳐 안전하게 다시 처리합니다.

쉽게 설명하면

현재는 반복 실패한 이벤트를 서버가 안전을 위해 멈춥니다. 이후 재처리 기능이 없으므로 DB 값을 사람이 직접 바꾸면 누가 왜 다시 실행했는지 남지 않고 중복 실행 위험이 생깁니다. 이 이슈는 승인된 운영 절차를 API로 만드는 후속 작업입니다.

시작 전 결정

• 재처리 허용 역할을 확정합니다. 기본안은 ADMIN만 허용입니다.
• 운영 API 경로와 OpenAPI 노출 범위를 확정합니다.
• 재처리 사유의 필수 길이와 보존기간을 확정합니다.

구현 범위

• REVIEW_REQUIRED 상태의 이벤트만 재처리할 수 있습니다.
• 요청에 expected_version과 재처리 사유를 필수로 받습니다.
• 현재 상태·버전·lease 보유 여부를 transaction 안에서 다시 검증합니다.
• 상태를 재처리 가능 상태로 바꾸고 다음 실행시각·오류 정보를 일관되게 갱신합니다.
• 누가, 언제, 어떤 이벤트를, 어떤 사유로 재처리했는지 AuditLog에 남깁니다.
• payload·개인정보·token·예외 원문은 응답과 감사로그에 남기지 않습니다.
• 같은 요청의 중복 제출과 동시 재처리를 방지합니다.
• 성공·권한 없음·상태 충돌·버전 충돌·중복 요청 통합 테스트를 작성합니다.
• 운영 runbook과 OpenAPI를 갱신합니다.

하지 않는 것

• 일반 사용자의 이벤트 조회 화면
• DB에서 상태를 직접 PENDING으로 변경하는 절차
• 실패 payload나 개인정보 원문 노출
• heartbeat 또는 장시간 handler lease 연장 구현

완료 조건

• 승인된 운영자만 사유와 함께 재처리할 수 있습니다.
• 잘못된 상태·오래된 version·동시 요청은 안전하게 거부됩니다.
• 재처리 전후 상태와 actor·requestId가 감사로그로 추적됩니다.
• DB 직접 수정 없이 장애 복구 절차를 수행할 수 있습니다.

관계

• 선행: [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25 Transactional Outbox, [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11 Approval·Audit
• RLS 연동: [Security] PostgreSQL RLS 기반 사업장 2차 격리 안전 도입 #34 tenant-safe Outbox 접근
• 관련 리뷰: feat: 이벤트 유실 방지와 재처리 Outbox 기반 구현 #50
• 후속 운영 고도화이며 feat: 이벤트 유실 방지와 재처리 Outbox 기반 구현 #50 병합을 막지는 않습니다.