부분 실패와 복구를 품질 게이트에 넣기

시드 210개 중 209개만 들어간 상태는 성공도 완전한 실패도 아닙니다. 중요한 것은 부분 실패를 숨기지 않고 안전하게 재시도할 수 있게 만드는 것입니다.

1. 실패를 단계로 나눈다

입력 파싱 → 트랜잭션/멱등 쓰기 → 공개 캐시 무효화 → health/readiness → 배포 smoke

각 단계는 자신의 실패를 기록하고 다음 단계가 실행되어도 되는지 결정합니다. 필수 콘텐츠 오류가 있으면 Admin은 409를 반환하고, 전체 초기화는 강좌 시드로 조용히 넘어가지 않습니다.

2. 재시도 가능한 데이터 변경

• 기존 행을 지우고 다시 넣지 말고 안정 키와 ON CONFLICT를 사용합니다.
• 컬럼 추가 → 양쪽 코드 배포 → 백필 → 제약 강화 순서로 expand/contract를 지킵니다.
• 게시일·사용자 수정 필드처럼 재시드 때 보존해야 하는 값은 upsert SET에서 제외합니다.
• 인덱스는 IF NOT EXISTS와 실제 조회 조건을 함께 사용하고, 운영 DB에는 Admin의 멱등 마이그레이션 경로로 적용합니다.

3. 복구를 사용자 경험으로 만든다

운영자는 “부분 성공”을 보고 어느 파일부터 다시 처리할지 알아야 합니다. 사용자는 빈 목록이나 오래된 캐시 대신 현재 상태와 재시도 가능 여부를 알아야 합니다. Admin의 실행 이력은 상태·처리 건수·오류 목록을 남기고, 버튼은 실행 중 중복 클릭을 막으며 키보드 포커스를 유지해야 합니다.

4. 검증 기준

• 같은 시드를 두 번 실행해도 중복 행과 게시일 drift가 없다.
• 한 파일을 의도적으로 실패시키면 API 상태가 409이고 실패 파일이 응답·이력에 남는다.
• 마이그레이션 실패 시 트랜잭션이 rollback되고 다음 재실행이 가능하다.
• 컨테이너는 프로세스 시작이 아니라 dependency health 이후에 기동하며 /health/ready 또는 서비스 healthcheck로 확인한다.
• 배포 smoke가 실패하면 직전 이미지 태그로 복원할 수 있다.

이 기준을 통과한 뒤에만 “완료”라고 보고합니다.

Next

• /notes/data/16-idempotent-migration-recovery