엑셀 업로드가 끝났는데, 발주요청은 왜 아직 처리 중일까?
직매입 발주요청 화면에서는 여러 상품의 발주 수량과 입고 정보를 엑셀로 한꺼번에 제출할 수 있다. 화면에서는 파일 하나를 올리는 일처럼 보이지만, 서버가 해야 할 일은 파일 저장으로 끝나지 않는다. 엑셀의 각 행은 SKU 입력이고, 한 번의 업로드 안에서 같은 파트너의 SKU들을 묶어 발주요청으로 처리해야 한다. 그 과정에서 입력 형식과 업무 규칙을 검증하고 결과를 사용자에게 돌려줘야 한다.
업로드 처리기 본체는 동료가 구현했다. 나는 이 프로젝트에서 발주요청 엑셀 다운로드와 일괄확정 실패 리포트, 날짜·서식, 입력 검증을 개선했다. 그 작업을 하며 업로드부터 결과 확인까지의 전체 흐름을 분석했고, 이 글에서는 팀이 사용한 구조와 내가 맡은 부분을 함께 정리한다.
이 흐름에서 가장 중요한 구분은 “파일 업로드가 완료됐다”와 “발주요청 처리가 완료됐다”는 서로 다른 사건이라는 점이었다. Presigned URL과 비동기 일괄 작업이 어떻게 연결되는지, 그리고 실패한 행을 사용자가 어떻게 수정해 다시 제출할 수 있는지 살펴보자.
파일을 API 서버로 바로 보내면 생기는 문제
일반적인 업로드 API라면 브라우저가 파일을 multipart/form-data로 서버에 보내고, 서버가 그 요청 안에서 파일을 읽어 처리할 수 있다. 행이 적고 처리 시간이 짧다면 충분히 단순한 방법이다.
하지만 발주요청 엑셀은 여러 행에 대해 형식 검증뿐 아니라 상품, 수량, 입고예정일 같은 업무 검증까지 필요하다. 이 작업을 HTTP 요청 하나에 묶으면 처리 시간이 길어질수록 게이트웨이 타임아웃에 걸리기 쉽다. 파일을 받는 API 서버가 파일 전달과 처리까지 모두 담당하면 요청이 몰릴 때 서버 메모리와 처리 자원도 함께 압박받는다.
이 프로젝트에서는 파일 전달과 발주요청 처리를 서로 다른 단계로 나눴다.
Presigned URL로 파일만 먼저 올린다
Presigned URL은 제한된 시간 동안 특정 객체 저장소 작업을 할 수 있도록 서명된 주소다. 이 흐름에서는 브라우저가 업로드용 URL을 발급받고, 파일을 S3에 직접 전송한다. API 서버는 파일 전체를 중간에서 받아 전달하지 않는다.
브라우저 ── 업로드 주소 요청 ──▶ API
브라우저 ◀─ Presigned URL + 파일 키 ── API
브라우저 ── 엑셀 파일 전송 ──▶ S3
브라우저 ── 파일 키로 작업 등록 ──▶ API여기서 파일 키는 업로드된 객체를 가리키는 식별자다. URL은 파일을 올릴 권한, 파일 키는 이후 어떤 파일을 처리할지 지정하는 값으로 역할이 다르다. 브라우저가 S3로부터 업로드 성공 응답을 받았더라도, 그것은 파일 저장 단계의 성공일 뿐이다. 엑셀의 내용이 유효하다는 의미는 아니다.
Presigned URL을 사용한다고 해서 파일을 신뢰해도 되는 것은 아니다. 작업 등록 시 허용된 파일 키인지 확인하고, 처리 전에 실제 객체가 있는지와 크기가 허용 범위인지 검사해야 한다. 파일 확장자나 이름 검사는 출발점이고, 엑셀 파싱과 업무 검증은 별도로 수행한다.
업로드 뒤에는 비동기 작업으로 처리한다
파일이 S3에 올라가면 브라우저는 파일 키와 작업 종류를 API에 보내 일괄 작업을 등록한다. API는 작업 기록을 PENDING으로 남기고 작업 ID를 반환한다. 실제 처리는 이 HTTP 요청 안에서 하지 않는다. 서버가 Temporal Workflow를 시작하면 백그라운드 워커가 작업을 이어받는다.
브라우저: 파일 키로 작업 등록
↓
API: 작업 기록 PENDING 저장 → Temporal Workflow 시작
↓
Workflow: PROCESSING 상태 전환
↓
Activity: S3 파일 확인·다운로드 → 엑셀 처리기에 위임
↓
Workflow: 결과 파일과 건수를 기록 → COMPLETED 또는 FAILED이렇게 하면 사용자는 긴 HTTP 요청이 끝나기를 기다리는 대신 작업 상태를 조회할 수 있다. 서버도 업로드 요청이 열려 있는 동안 전체 엑셀을 처리할 필요가 없다.
Temporal이 맡는 일과 업로드 처리기가 맡는 일
여기서 Workflow는 작업의 순서를 관리한다. 처리 중으로 상태를 바꾸고, 파일 처리 결과를 받아 완료 또는 실패 상태를 기록하는 흐름을 연결한다. 반면 S3에서 파일을 읽거나 데이터베이스에 쓰는 작업처럼 외부 세계에 영향을 주는 일은 Activity에서 실행한다.
Activity는 내려받은 파일을 발주요청 엑셀 처리기(Processor) 에 전달한다. 처리기는 엑셀을 파싱해 SKU 행을 파트너 ID별로 묶고, 각 SKU를 검증·처리한 뒤 성공·실패 건수와 결과 파일 정보를 돌려준다. 즉, Temporal이 엑셀 내용을 직접 해석하는 것은 아니다. Temporal은 오래 걸리는 작업의 실행 흐름을 관리하고, 처리기는 발주요청 도메인의 규칙을 담당한다.
이 구분 덕분에 다른 종류의 엑셀 일괄 작업에도 작업 접수·상태·결과 조회라는 공통 흐름을 재사용하고, 각 업무의 파싱과 검증은 해당 처리기에서 다룰 수 있다.
SKU 행을 파트너별 발주요청으로 묶는다
엑셀의 한 행을 발주요청 한 건으로 보면 이 업로드의 업무 단위가 잘못된다. 한 파트너에게 여러 SKU를 발주할 수 있으므로, 같은 업로드에서 같은 파트너에게 보내는 정상 SKU들은 하나의 발주요청으로 묶어 파트너가 확정할 수 있게 한다.
엑셀 입력
파트너 A · SKU 1 (정상)
파트너 A · SKU 2 (검증 실패)
파트너 B · SKU 3 (정상)
처리 결과
파트너 A의 발주요청 1건 ─ SKU 1
파트너 B의 발주요청 1건 ─ SKU 3
실패 리포트 ─ 파트너 A의 SKU 2와 실패 사유따라서 한 번의 엑셀 일괄 등록 안에서는 SKU 행의 파트너 ID를 기준으로 묶고, 각 묶음을 발주요청의 헤더와 그에 속한 SKU 항목들로 다룬다. SKU별 부분 성공을 허용했기 때문에 같은 파트너 그룹에 잘못된 행이 있어도 정상 SKU는 처리하고, 실패한 SKU는 사유와 함께 리포트에 남긴다. 파트너가 확정할 요청은 파트너 단위이고, 검증 결과는 SKU 단위다. 엑셀의 행 수와 생성될 발주요청 건수는 같지 않다.
이 규칙은 파트너마다 발주요청을 평생 한 건만 만들 수 있다는 뜻이 아니다. 일반 발주요청에서도 같은 파트너에게 여러 요청을 만들 수 있고, 같은 SKU를 서로 다른 발주요청에 다시 포함하는 것도 허용했다. 여기서 파트너 ID로 묶는 범위는 해당 엑셀 업로드 안이다.
당시 동작을 개념적으로 풀면, 각 파트너 묶음 안에서 SKU 입력의 성공·실패를 갈라 정상 항목은 요청에 반영하고 실패 항목은 별도 목록에 사유와 함께 모으는 흐름이다. 아래는 실제 구현 코드가 아닌 처리 결과를 설명하기 위한 의사코드다.
파트너별로 묶인 SKU 행을 순회한다
입력이 유효하면 → 해당 파트너의 발주요청 항목으로 처리한다
입력이 유효하지 않으면 → 실패 목록에 원본 행과 사유를 담는다
작업이 끝나면 → 실패 목록으로 수정용 리포트를 만든다여기서 SKU별 부분 성공은 사용자에게 보이는 처리 결과의 단위를 말한다. 이 사실만으로 데이터베이스 트랜잭션이 SKU마다 하나씩 열렸다고 단정할 수는 없다.
이 구조에서 놓치기 쉬운 구간은 작업 기록을 저장한 직후, 비동기 실행을 시작하기 전이다. 실행 시작이 실패했는데 작업 기록만 남으면 화면에는 끝없이 대기 중인 작업처럼 보일 수 있다. 프로젝트에서는 작업 기록을 먼저 남기고 실행을 시작하되, 실행 실패 시 그 기록을 실패 상태로 전환해 추적할 수 있도록 했다. 실패 상태 기록까지 실패하는 경우에는 대기 중인 작업을 별도로 탐지해야 한다.
작업 완료와 모든 행의 성공도 다르다
엑셀 파일 자체는 정상적으로 읽혔어도 일부 SKU 행의 입력이 검증에 걸릴 수 있다. 예를 들어 입고예정일이 허용되지 않는 날짜이거나, 상품 정보와 입력값이 맞지 않을 수 있다.
따라서 작업 상태의 COMPLETED는 처리 과정이 정상적으로 끝났다는 뜻이다. 파일 안의 모든 입력이 유효해 발주요청이 만들어졌다는 뜻은 아니다. 사용자가 실제 결과를 판단하려면 성공·실패 건수와 실패 사유를 함께 봐야 한다.
작업 상태: COMPLETED
입력: SKU 100행 / 성공: 97행 / 실패 리포트: 3행
→ 작업은 끝났지만, 리포트를 확인해 수정할 입력이 남아 있다.숫자만 보여주면 사용자는 어떤 행을 고쳐야 할지 알 수 없다. 그래서 실패한 행에 사유를 적은 엑셀 리포트를 제공했다. 업무 규칙이 다양하다 보니 “처리 실패” 같은 한 문장보다 날짜, 상품 속성, 상태 전이 등 무엇을 수정해야 하는지 알 수 있는 메시지가 중요했다.
실패 리포트는 기능의 마지막 장식이 아니었다. 실제 사용자는 리포트를 열어 값을 수정한 뒤 다시 업로드한다. 내가 맡았던 오류 수정과 날짜 표기, 셀 서식, 안내 행의 가독성 개선도 사용자가 실패 원인을 이해하고 재제출하는 과정에 직접 닿아 있었다.
이 경험에서 배운 점
Presigned URL은 파일이 API 서버를 거치지 않고 저장소로 가도록 해 준다. 하지만 대용량 엑셀 처리 문제 전체를 해결하는 것은 아니다. 업로드 뒤에 작업을 접수하고, 처리 상태를 추적하고, 업무 규칙을 검증하고, 실패한 행을 사용자에게 돌려주는 설계가 함께 있어야 한다.
이 프로젝트에서 기억에 남은 것은 “업로드 성공”이라는 말을 조심해서 쓰게 된 점이다. 파일이 저장됐는지, 작업이 시작됐는지, 처리가 끝났는지, SKU 입력을 파트너별 발주요청으로 처리할 수 있었는지를 나눠야 사용자도 시스템도 현재 상태를 정확히 알 수 있다.