고객 데이터 일괄 업로드의 중복 반영을 막는 설계

고객이 같은 엑셀 파일을 두 번 올리거나 업로드 중 연결이 끊겨 다시 시도하는 일은 흔합니다. 일괄 업로드는 중복 요청을 정상적인 상황으로 보고 설계해야 합니다.

파일과 행의 중복을 구분한다

파일 단위 요청 ID와 행 단위 업무 키를 분리합니다. 같은 파일을 다시 올렸을 때 전체를 건너뛸지, 수정된 행만 반영할지 정책이 달라집니다. 고객에게는 업로드 미리보기와 예상 생성·수정 건수를 보여줍니다.

재시도에 같은 결과를 돌려준다

서버는 요청 ID를 저장하고 동일 요청의 재시도에는 같은 결과를 돌려줍니다. 그러나 같은 데이터가 다른 파일 이름으로 들어오면 행 단위 고유 키 검사가 필요합니다. 키가 없는 데이터라면 중복 판단 기준을 고객과 먼저 합의해야 합니다.

부분 실패 규칙을 정한다

검증 단계에서 형식 오류, 존재하지 않는 참조 값, 고객 권한 밖의 데이터를 분리합니다. 1만 행 중 1행 오류일 때 전체 실패인지 부분 성공인지도 미리 정합니다. 부분 성공은 재시도 시 어느 행이 이미 반영됐는지 알려줘야 합니다.

반영 단계를 나눈다

반영은 가능한 한 트랜잭션 경계를 명확히 둡니다. 외부 시스템까지 쓰는 경우 단일 DB 트랜잭션만으로는 끝나지 않아 재시도 안전한 단계 설계가 필요합니다. 진행 상태를 단순 ‘완료’ 대신 검증·반영·후처리로 나눕니다.

재시도 품질을 측정한다

운영에서는 중복 차단 건수, 부분 실패 건수, 재시도 후 결과 일치율을 봅니다. 장애 때 관리자가 수동으로 같은 파일을 다시 넣어도 이력이 연결되어야 합니다. 고객 데이터가 두 배로 늘어난 뒤 되돌리는 것보다 예방이 훨씬 쉽습니다.

현장에 적용할 때의 순서

1. 파일 요청 ID와 행 키 정의
2. 검증·반영 단계별 결과 저장
3. 끊김·재시도·부분 실패 시험

주의할 실패: 같은 행이 파일명만 달라 두 번 생성됨

관찰할 지표: 중복 차단 건수와 재시도 결과 일치율

적용 전 체크리스트

• 파일 요청 ID와 행 업무 키 분리
• 부분 성공·전체 실패 정책 명시
• 동일 파일 재시도 결과 일치 테스트

참고 자료

Stripe API — Idempotent Requests. 요청을 안전하게 재시도하는 멱등성 개념은 Stripe 공식 문서를 참고했습니다. 파일·행 단위 구분은 업로드 업무에 맞춘 설계 제안입니다.

이미지와 도식은 이해를 돕기 위한 개념 시각화입니다. 특정 고객의 실제 설비·데이터·화면을 재현한 것이 아닙니다.

#일괄업로드 #멱등성 #데이터중복 #SaaS운영 #엑셀업로드 #네이처프랙탈 #트랜잭션 #API설계 #데이터품질 #고객데이터