물류 시스템이 선사 데이터를 자동으로 가져온다면 확인할 것이 하나 있다. 못 알아본 정보를 어디에 남기는가다. 우리 시스템은 선사 사이트에 빈컨 반납 완료로 뜬 컨테이너 3대의 반납일을 비워 두고 있었다. 오류도 경보도 없었고, 사람이 선사 사이트와 손으로 비교하다가 발견했다. 이 선사의 선적에서 1년 가까이 그 상태였다.
여기부터는 원인과 코드 이야기다. 시스템을 고르거나 운영하는 입장이라면 업체에 이것만 물어보면 된다. “선사가 보낸 문구를 못 알아보면 어디에 기록되나요?”
왜 — 반납된 컨테이너 3대가 우리 화면엔 없었다
사내에서 만드는 물류 운영 SaaS 얘기다. 선적 건마다 선사 트래킹을 주기적으로 긁어 와 컨테이너별 날짜(양하·반출·철도·빈컨 반납)를 채운다. 이 날짜들이 틀리면 체화료(demurrage) 알림이 틀리고, 그건 바로 돈이다.
어느 날 선사 사이트를 직접 열어 보다가, 컨테이너 3대가 빈컨 반납 완료로 떠 있는데 우리 화면은 비어 있는 걸 발견했다. 사람이 손으로 비교해서 찾았다는 게 제일 불편한 부분이었다.
로그를 뒤졌다. 스윕 잡은 정상, HTTP 200, 컨테이너 파싱 성공. 실패한 게 하나도 없었다. 받아온 걸 우리가 못 꽂은 것이다.
원인 — 벤더 어휘를 우리 어휘로 짐작했다
반납 판별 정규식은 이랬다.
EMPTY_RETURN_RE = /empty.*return|returned.*empty/i
그런데 그 선사가 주는 문구는 이거였다.
Gate in of Empty Equipment by Truck at Ramp
return이 없다. DCSA(해운 데이터 표준) 문구 체계는 <동작> of <Laden|Empty> Equipment <전치사> <장소> 꼴이라, “반납”을 Gate in + Empty의 조합으로 표현한다. 우리는 “반납이면 return이라고 쓰겠지”라고 가정한 채 1년 가까이 돌렸다. 그 선사를 쓰는 선적에서만, 그 한 필드만 조용히 비어 있었다.
패턴에 표준 문구를 추가했다.
EMPTY_RETURN_RE = /empty.*return|returned.*empty|gate\s*-?\s*in\s+of\s+empty/i
EMPTY_PICKUP_RE = /empty.*(released?|pick.?up)|gate\s*-?\s*out\s+of\s+empty/i
더 나쁜 건 옆에 있었다 — 순서가 곧 우선순위
반납 패턴을 고치면서 짝인 빈컨 수령(Gate out of Empty Equipment)을 같이 봤는데, 이쪽은 비어 있는 게 아니라 틀린 값이 들어가고 있었다.
문구 → 컬럼 매핑 테이블의 아래쪽에 일반 패턴이 있다.
[ /pick.?up\s+by\s+|gate\s*out|out.?gate/i, :outgated_at ]
Gate out of Empty Equipment는 이 패턴에 걸린다. 그래서 빈 컨테이너를 받으러 간 기록이 적컨 반출(픽업)로 기록되고 있었다. 비어 있는 필드는 언젠가 눈에 띄지만, 그럴듯한 값이 들어간 필드는 안 띈다.
고친 방법은 단순하다. 좁은 패턴을 넓은 패턴 위로 올리고, 그 순서가 의미를 갖는다는 걸 코드에 적어 뒀다.
# ★ 순서가 곧 우선순위다. 빈/적 구분이 일반 gate in/out 패턴보다 먼저 와야 한다 —
# 표준 문구가 "Gate in of Empty Equipment" 라, 아래 일반 gate 패턴이 먼저 걸리면
# 빈컨 반납이 단순 게이트인으로 뭉개진다.
MILESTONE_FIELDS = [
[ EMPTY_RETURN_RE, :empty_return_date ],
[ EMPTY_PICKUP_RE, :empty_pickup_date ],
[ /depart\w*\s+by\s+rail|rail\s+depart\w*/i, :rail_atd ],
[ /arriv\w*\s+by\s+rail|rail\s+arriv\w*/i, :rail_ata ],
[ /discharge\w*\b.*\b(vessel|pod)\b/i, :discharge_date ],
[ /load\w*\b.*\bvessel\b/i, :loading_date ],
[ /pick.?up\s+by\s+|gate\s*out|out.?gate/i, :outgated_at ]
].freeze
철도 패턴이 선박 패턴 위에 있는 것도 같은 이유다. 순서 의존 테이블은 원래 냄새나는 설계지만, 자유 텍스트 분류에서는 어차피 우선순위를 어딘가에 적어야 한다. 그러면 테이블 순서 하나로 몰아넣고 “순서가 계약”이라고 못 박는 쪽이 조건문에 흩뿌리는 것보다 낫다고 판단했다.
규칙 사본을 없앴다
같은 정규식 사본을 선사 어댑터 한 곳이 따로 들고 있었다. 반납 패턴을 공용 매퍼에서 고쳐도 그 어댑터는 옛날 규칙으로 돌았을 것이다. 사본을 지우고 모든 어댑터가 EventMapper 한 곳만 보도록 바꿨다. 어댑터는 문구 판정을 직접 하지 않는다가 지금의 규칙이다.
진짜 교훈 — 조용한 실패를 시끄럽게
원칙 자체는 틀리지 않았다. “못 알아보는 문구는 추측해서 채우지 않고 비워 둔다”는 맞는 설계다. 틀린 건 “못 했다”를 아무 데도 남기지 않은 것이다. 선사가 문구를 바꾼 날 데이터는 소리 없이 사라지고, 발견자는 시스템이 아니라 사람이 된다.
그래서 매칭 실패에 경로를 하나 냈다.
def self.milestone_dates(text, timestamp, source: nil)
field = milestone_field(text)
unmapped!(text, source) if field.nil?
return {} if field.nil? || timestamp.nil?
...
end
def self.unmapped!(text, source = nil)
return if text.to_s.strip.empty?
Rails.logger.warn("[EventMapper] unmapped event#{source ? " (#{source})" : ''}: #{text.inspect}")
end
열 줄도 안 되는 코드다. 이게 있었으면 이번 건은 사람이 선사 사이트를 열어 보기 전에 로그에서 잡혔다.
확인은 실응답으로 — 점검 태스크
픽스처 테스트는 이번 버그를 못 잡는다. 픽스처는 우리가 안다고 믿는 문구로 만들어졌기 때문이다. 그래서 실제 선사 응답을 받아 raw 문구와 들어간 컬럼을 나란히 찍는 rake 태스크를 만들었다.
# bin/rails carriers:check # 활성 선적으로 전 선사
# bin/rails carriers:check[SCAC,BL] # 특정 건 하나만
puts " - #{c.container_no} status=#{c.status.inspect}"
puts " raw : #{raw.inspect}"
puts " map : #{set.presence&.join(' ') || '(없음)'}"
판정 기준은 한 줄로 끝난다. raw에 문구가 있는데 map이 (없음)이면 그게 미매핑이다. 12개 날짜 필드를 이걸로 전 선사 한 바퀴 돌렸고, 반납 13건·4건이 들어오는 걸 눈으로 확인했다.
돌리면서 알게 된 더 유용한 사실은, 선사가 두 부류로 갈린다는 것이다.
| 부류 | 주는 방식 | 위험도 |
|---|---|---|
| 구조화 필드형 | 전용 필드나 이벤트 코드로 준다 | 낮다. 깨지면 전부 안 들어와 금방 눈에 띈다 |
| 문구 추측형 | 사람이 읽는 자유 문장을 준다 | 높다. 표현만 바꿔도 그 한 필드만 조용히 사라진다 |
이번에 터진 건 전부 문구 추측형이었다. 이 구분을 선사별 매핑 문서에 적고, 각 선사 옆에 “언제 실응답으로 검증했는지”를 함께 기록했다. 코드가 아니라 문서가 정본인 영역이다.
한계 · 다음 계획
- 검증 못 한 선사가 남아 있다. 한 곳은 픽스처로 쓰던 B/L이 선사 사이트에서 만료돼 실응답을 못 받았다. 문서에 ✅ 대신 🟡 “검증 불가”로 적어 뒀다. 모르는 걸 안다고 적는 것보다 낫다.
- B/L은 만료된다. 라이브 검증은 몇 주 지나면 그 번호가 선사 쪽에서 사라져 재현이 안 된다. 점검할 때 raw 응답을 떠서 고정 픽스처로 쌓아 두는 쪽으로 갈 생각이다.
- 미매칭 로그는 아직 로그일 뿐이다. 주기적으로 모아 보는 장치가 없다. 주간으로 집계해 “새로 등장한 미매칭 문구”만 뽑는 게 다음 작업이다.
- 애그리게이터를 거치는 선사가 늘고 있어서, 문구 추측형 비중 자체는 줄어드는 방향이다.
FAQ
Q. 자유 텍스트 매칭을 아예 LLM에 맡기면 되지 않나?
이벤트 문구는 종류가 수십 개로 한정돼 있고 하루에 수천 번 돈다. 비용·지연·비결정성을 감수할 이유가 없다. 다만 미매칭 문구를 모아 새 규칙을 제안하는 쪽이라면 쓸 만하다. 판정은 코드, 규칙 발굴은 사람(또는 AI)이 맞다고 본다.
Q. 왜 테스트로 못 잡았나?
픽스처가 우리 가정으로 만들어졌기 때문이다. empty returned라고 적은 픽스처는 empty.*return 패턴을 영원히 통과시킨다. 외부 연동에서 픽스처 테스트는 회귀 방지용이지 가정 검증용이 아니다. 가정은 실응답으로만 깨진다.
Q. 순서 의존 정규식 테이블이 위험하지 않나?
위험하다. 그래서 두 가지를 같이 뒀다. 순서가 계약이라는 주석과, 우선순위가 뒤집히면 깨지는 테스트(빈컨 문구가 일반 gate 컬럼으로 가지 않는지). 테이블 대신 조건문으로 흩어 놓으면 우선순위가 보이지 않는 곳으로 숨는다.
Q. 비슷한 유실을 빨리 찾아내려면 뭘 먼저 보나?
“성공했는데 아무것도 안 쓴” 경우를 찾는다. 외부 연동에서 200 OK + 파싱 성공 + 쓰기 0건은 정상이 아니라 미매핑 신호다. 매칭 실패 지점마다 로그 한 줄을 남기고, 그 로그가 0인지 아닌지 주기적으로 보는 것만으로 대부분 잡힌다.