왜 — 운영의 절반이 시스템 밖에 있었다
사내에서 만드는 물류 운영 SaaS 얘기다. 선적 건 하나가 굴러가는 동안 도착통지(A/N), 선사 알림, 운송사 청구서가 계속 메일로 들어온다. 문제는 그 메일이 담당자 받은편지함에만 있다는 것이었다. 시스템은 사람이 화면에 다시 옮겨 적어줄 때까지 아무것도 모른다.
그래서 인바운드 메일 웹훅을 붙였다. 다만 처음부터 자동 반영은 하지 않기로 했다. 1단계(P1)는 수신·라우팅·분류·진단까지만이고, 첨부에서 값을 뽑아 필드에 쓰는 건 다음 단계다. 자동화를 열어도 되는지는 열어보기 전에는 모르고, 잘못 쓴 날짜 하나가 곧바로 데머리지 비용이 되는 도메인이라 순서를 이렇게 잡았다.
P1을 올리고 실제 메일을 흘려보내자, 예상했던 “분류 정확도” 문제보다 훨씬 재미없고 훨씬 치명적인 것들이 먼저 나왔다. 네 가지 다 로그에는 정상으로 남는 실패였다.
1. 멱등 장치가 한 번도 동작한 적이 없었다
웹훅 중복 수신을 막는 WebhookEvent.record!는 “이미 처리한 이벤트면 nil을 준다”는 계약으로 쓰고 있었다. 호출부는 nil을 받으면 “중복이니 그냥 200″으로 끝낸다.
def self.record!(provider:, event_type:, external_id:, payload: nil)
create!(provider:, event_type:, external_id:, payload:)
rescue ActiveRecord::RecordNotUnique
nil
end
RecordNotUnique만 잡고 있는 게 함정이다. 모델에 external_id uniqueness 검증이 걸려 있으면 검증이 INSERT보다 먼저 터진다. 실제로 나는 예외는 RecordInvalid고, 그건 그대로 새어나가 응답이 422가 된다. 웹훅 발신 측은 4xx 중에서도 422를 “일시 실패”로 보고 계속 재시도한다. 즉 중복을 막으려고 넣은 장치가, 중복이 올 때마다 발신 측 재시도를 유발하고 있었다.
고친 건 세 줄이다. 중복 사유일 때만 삼키고 나머지 검증 실패는 그대로 올린다.
rescue ActiveRecord::RecordInvalid => e
raise unless e.record.errors.of_kind?(:external_id, :taken)
nil
rescue ActiveRecord::RecordNotUnique
nil # 동시 요청 경합 — 검증을 함께 통과하고 DB 유니크 인덱스가 잡은 경우
end
두 rescue 다 필요하다. 앞은 순차 중복, 뒤는 동시 요청 경합이다. 배운 것은 따로 있다. “멱등하게 만들어 뒀다”는 문장은 중복 요청을 실제로 두 번 쏴 보기 전까지는 가설이다. 이 코드는 배포된 채로 한 번도 제 일을 한 적이 없었고, 아무 알림도 울리지 않았다.
2. 첨부의 3분의 2가 조용히 버려지고 있었다
수신한 메일의 첨부를 내려받아 보관하는데, 허용 타입 화이트리스트를 발신 측이 선언한 Content-Type으로 걸고 있었다.
실제 선사 메일 14건(선사 8곳)을 표본으로 떠서 헤더를 열어봤더니, 첨부 6개 중 4개가 .PDF인데 application/octet-stream으로 선언돼 있었다. 큰 글로벌 선사 넷이 그랬다. A/N 알맹이는 그 PDF 안에만 있는데, 우리는 전부 스킵하고 attachments_count: 0으로 “정상 처리” 마크를 찍고 있었다.
먼저 내려받은 뒤 실제 타입을 판정하도록 순서를 바꿨다. 판정은 ActiveStorage가 이미 쓰는 Marcel에 맡긴다.
# 선언타입 → 파일명 확장자 → 매직바이트 순으로 해소
def effective_content_type(bytes, filename, declared)
Marcel::MimeType.for(StringIO.new(bytes), name: filename, declared_type: declared).to_s
rescue StandardError
declared.to_s
end
확장자를 무조건 믿는 게 아니라 매직바이트까지 종합하므로, .pdf로 위장한 실행파일은 여전히 걸린다(테스트로 고정했다).
여기서 하나 더 배웠다. 버린 첨부도 흔적을 남겨야 한다. 표본 중 한 건은 컨테이너 번호가 본문에도, 다른 첨부에도 없고 오직 CUSTOMS MANIFEST - XXXU 987xxxx.msg라는 첨부 파일명에만 있었다. 조용히 버리면 그 메일은 영영 선적 건에 못 붙는다. 그래서 skipped_attachments(파일명·선언타입·사유)를 남기고, 분류기 프롬프트에도 버린 첨부 이름을 함께 넣는다.
# 분류기·화면에 보여줄 첨부 이름 전체(보관된 것 + 버린 것)
def all_attachment_names
stored = files.attached? ? files.map { |f| f.filename.to_s } : []
stored + skipped_attachment_list.map { |a| a["filename"].to_s }.compact_blank
end
3. To:는 끝까지 우리 주소가 아니었다
컨트롤러는 웹훅 페이로드의 to / received_for / cc로 어느 조직(테넌트)의 메일인지 정한다. 그런데 실제 유입 경로는 이랬다. 선사 통지가 고객사의 공용 그룹 주소로 먼저 가고, 거기서 우리 주소로 포워딩된다. 그러면 To:는 끝까지 그룹 주소다.
To: [email protected] ← 끝까지 안 바뀐다
Delivered-To: [email protected] ← 진짜 수신 주소는 여기에만
X-Original-Sender: [email protected] ← 진짜 발신 선사
문제는 웹훅 페이로드에는 헤더가 없다는 것이다. 메타데이터만 온다. 본문·헤더는 잡에서 따로 당겨온다. 그래서 라우팅을 두 번 시도하게 했다 — 컨트롤러에서 한 번, 헤더를 받아온 직후 한 번.
ENVELOPE_HEADERS = %w[delivered-to x-forwarded-to x-original-to envelope-to x-delivered-to].freeze
def reroute_from_headers!(mail)
return if mail.organization_id.present? # 이미 붙었으면 건드리지 않는다
lookup = mail.headers.transform_keys { |k| k.to_s.downcase }
candidates = ENVELOPE_HEADERS.flat_map { |h| lookup[h].to_s.split(/[,;]/) }.map(&:strip).compact_blank
return if candidates.empty?
org, matched = InboundMail.route(candidates)
mail.update!(organization: org, routed_via: matched) if org
rescue StandardError => e
# 구제 실패해도 본문·분류는 계속 — 미라우팅으로 남고 Admin 화면에서 보인다
Rails.logger.warn("[reroute] mail=#{mail.id}: #{e.class} #{e.message}")
end
같은 표본에서 나온 사실 하나 더. 그룹 릴레이를 거치면 From도 그룹 주소라 의미가 없다. 실발신자는 X-Original-Sender에 있다. 중계를 한 번이라도 거치는 메일은, 봉투(envelope)와 헤더가 서로 다른 이야기를 한다고 보는 게 맞다.
4. 한국어 PDF가 전부 “스캔본”으로 오판됐다
파이프라인 밖이지만 같은 성격이라 같이 적는다. 고객사가 올린 HBL 두 건이 “스캔 BL(텍스트 레이어 없음) — 수동 입력 필요”로 실패했는데, 스캔본이 아니었다. 같은 파일에 같은 명령을 두 환경에서 돌려봤다.
| 환경 | poppler-data | pdftotext 추출 |
판정 |
|---|---|---|---|
| 운영 컨테이너 | 없음 | 0자 | TEXT_MIN=300 미달 → Unparseable |
| 로컬 | 있음 | 753자 (shipper·consignee·HBL 번호 전부) | 정상 |
운영 쪽 stderr에 답이 있었다.
Syntax Error: Missing language pack for 'Adobe-Korea1' mapping
Syntax Error: Unknown font tag 'CJK1'
이미지에 poppler-utils만 있고 CJK CMap을 담은 poppler-data가 빠져 있었다. 국내 기업용 리포팅 툴로 출력한 PDF가 전부 이 인코딩이라, 결과적으로 한국어 인코딩 PDF는 하나도 파싱되지 않으면서 사용자에게는 “스캔본이니 손으로 넣으라”고 안내하고 있었다. 일본어·중국어 PDF도 같이 걸린다.
- ... poppler-utils && \
+ ... poppler-utils poppler-data && \
수정은 한 단어인데, 진짜 고칠 것은 따로 있었다. 에러 메시지가 오진을 유도하고 있었다. “스캔 BL”이라고 단정한 문구 때문에 아무도 인코딩을 의심하지 않았다.
# 0자는 스캔본이라는 뜻이 아니다 — 인코딩 미지원으로도 0자가 나온다
raise Unparseable, "텍스트 추출 실패(스캔본이거나 인코딩 미지원) — 자동 파싱 불가, 수동 입력 필요"
관통하는 것 — 주석과 로그는 증거가 아니다
같은 날 하나 더 걸렸다. 어떤 잡의 주석에 “일시 오류(timeout, 502)만 retry”라고 적혀 있었는데 둘 다 거짓이었다. ActiveJob은 나중에 등록된 rescue 핸들러부터 매칭하므로 뒤에 선언된 discard_on StandardError가 retry_on을 통째로 가로챈다(재시도 큐 진입 0건). 순서를 고쳐도 타임아웃은 안 걸린다 — SDK 예외를 우리 래퍼가 감싸지 않기 때문이다. 무해한 죽은 코드라 동작은 두고 주석만 사실로 맞췄다. 진짜 위험은 순서 버그가 아니라 있지도 않은 안전망을 믿게 만든 주석이었다.
다섯 건의 형태가 같다. 예외도 안 나고, 알림도 안 울리고, 로그에는 “처리 완료”로 남는다. 찾은 방법도 하나뿐이었다 — 실제 데이터를 표본으로 떠서 한 건씩 손으로 읽는 것. 실메일 44건(선사 11곳)을 읽고서야 설계 문서의 필드 매핑표가 추측이었다는 것도 드러났다. 선사 봇 메일은 33%뿐이고 절반이 사람 메일이라, 도메인으로 잘랐으면 운송사 청구서를 같이 버렸을 것이다.
한계 · 다음 계획
- P1은 아직 아무것도 자동으로 고치지 않는다. 분류 라벨과 진단만 남기고 필드 반영은 사람이 한다.
- 분류 정확도만 재서는 부족하다. 위험한 건 분류가 아니라 추출이다. 그래서 다음을
P2a-shadow(파서는 돌리되 적용 차단) →P2a-live(사람이 버튼으로 적용) →P3(고신뢰 건만 자동)으로 쪼갰다. 섀도우 구간의 실측치가 “자동화를 열어도 되는가”의 유일한 근거다. - A/N PDF 4장을 직접 해부한 결과 LFD와 pickup 번호는 A/N으로 못 얻는다. 컬럼이 비었거나 “포털을 보라”고 적혀 있고, 외부 트래킹 어댑터 8종도 이 값을 주지 않는다. 파싱한 LFD조차 터미널·계약 free time에 따라 달라지는 참고값이라 사람 입력을 덮지 않는다.
- 파싱 함정은 정규식으로 안 풀린다(컨테이너 번호 안 공백, 2단 조판 좌우 교차, 3줄로 쪼개진 표 헤더, 날짜 4형식…).
pdftotext -layout텍스트를 통째로 LLM에 넘기는 쪽으로 간다. vision은 필요 없다 — 4장 전부 텍스트 레이어가 살아 있었다. - 백로그: 같은 의미의 날짜 컬럼이 두 군데라 화면마다 다른 값을 본다.
FAQ
Q. 웹훅 중복 요청에 4xx를 주면 안 되나요?
중복은 실패가 아니라 “이미 처리함”이므로 200이 맞다. 발신 측은 2xx가 아니면 재시도 정책을 태우고, 특히 408·409·422·429·5xx는 일시 실패로 보고 백오프 재시도하는 경우가 많다. 4xx는 서명 검증 실패나 스키마 위반처럼 재시도해도 절대 성공할 수 없는 경우에만 쓴다.
Q. Content-Type을 못 믿으면 확장자로 판정하면 되지 않나요?
확장자만 믿으면 .pdf로 위장한 파일을 통과시키고, 매직바이트만 보면 텍스트 계열 구분이 흔들린다. Rails라면 ActiveStorage가 이미 의존하는 Marcel이 선언타입 → 파일명 → 매직바이트를 종합해 주므로 새 gem이 필요 없다. 단, 판정하려면 바이트가 있어야 하니 “다운로드 후 필터링”으로 순서를 바꿔야 한다.
Q. 첨부를 버릴 때 로그만 남기면 충분하지 않나요?
아니다. 로그는 검색되지 않고 화면에도 안 뜬다. 파일명 자체가 유일한 식별 정보인 건이 실제로 있었다. 버린 것도 레코드로 남기고 화면에 보여야 사람이 구제할 수 있다. 규모가 작다면 JSON 컬럼 하나로 충분하다.
Q. 도커 이미지에서 이런 누락을 미리 잡을 방법은?
운영과 같은 이미지로 대표 입력 파일을 한 번 돌려보는 스모크 테스트가 가장 싸다. 우리는 CJK 데이터가 이미 깔린 개발자 머신에서만 검증해서 놓쳤다. --no-install-recommends를 쓰면 데이터 패키지가 조용히 빠지므로, 언어·인코딩 의존이 있는 도구는 데이터 패키지를 명시적으로 함께 적는다.