왜 — “화주별로 뽑아주세요”가 안 되는 이유
사내에서 만드는 물류 운영 SaaS에 화주(cargo owner)별 리포트 그리드를 붙이는 작업이었다. 컨테이너 단위로 스프레드시트처럼 보여주고, 화주 드롭다운으로 거르고, CSV로 내보내는 화면. 백엔드 쿼리는 이미 있었으니 하루면 끝날 줄 알았다.
막힌 건 쿼리가 아니라 “화주”라는 값이 시스템에 없다는 것이었다.
우리가 가진 건 B/L에서 파싱된 consignee_name 자유 텍스트다. 실제 데이터는 이렇게 들어온다.
ACME IMPORTS INC.
Acme Imports, Inc
acme imports inc
Acme Imports Co., Ltd.
사람 눈엔 전부 같은 회사인데 문자열로는 넷 다 다르다. 이 상태로 GROUP BY consignee_name을 하면 한 회사가 네 줄로 쪼개진 리포트가 나온다. 그래서 리포트보다 먼저 엔티티 해석(entity resolution)을 만들어야 했다.
AI에 맡길까도 생각했지만 접었다. 상호명 표기 흔들림은 대부분 대소문자·구두점·법인격 접미어라서 규칙으로 90%가 잡히고, 나머지 10%는 AI를 붙여도 사람이 확인해야 한다. 그럴 거면 규칙 + 사람 교정을 기억하는 구조가 더 싸고 예측 가능하다.
무엇을 — 정규화 키 + 학습형 별칭
구조는 두 조각이다.
1) 정규화 키. 원문을 대문자로 올리고, 구두점을 공백으로 바꾸고, 후행 법인격 접미어를 떼고, 공백을 정리한다.
SUFFIXES = %w[
INC INCORPORATED CORP CORPORATION CO COMPANY
LLC LLP LP LTD LIMITED
].freeze
def normalize(name)
tokens = name.to_s.upcase.gsub(/[^[[:alnum:]]& ]/, " ").split
tokens.pop while tokens.any? && SUFFIXES.include?(tokens.last)
tokens.join(" ")
end
접미어를 while로 떼는 이유는 Acme Imports Co., Ltd.처럼 두 개가 겹쳐 붙는 표기가 흔해서다. 한 번만 떼면 ACME IMPORTS CO가 남는다. 위 네 줄은 전부 ACME IMPORTS로 수렴한다.
2) 별칭 테이블. 정규화 키 → 화주 매핑을 조직 단위로 저장한다.
add_index :cargo_owner_aliases, [ :organization_id, :normalized_name ],
unique: true, name: "index_cargo_owner_aliases_on_org_and_name"
해석기는 별칭을 먼저 보고, 없으면 접미어 뗀 이름으로 화주를 찾거나 만든다. 그리고 사람이 화면에서 화주를 고쳐주면 그 교정 결과가 별칭으로 남는다. 다음부터 같은 원문이 오면 자동으로 맞는 화주에 붙는다. 학습이라고 부르긴 했지만 모델이 아니라 그냥 테이블 한 줄이다.
읽기(해석)와 쓰기(학습)는 담당을 나눴다. 해석기는 조회와 화주 생성만 하고, 별칭 기록은 HouseBill 모델이 단독으로 한다.
before_save :auto_assign_cargo_owner
after_commit :learn_cargo_owner_alias, on: [ :create, :update ]
시행착오
1. 부차 작업이 코어 저장을 롤백시키고 있었다
처음엔 학습을 after_save에 걸었다. 배포 전 코드리뷰에서 HIGH로 잡혔다.
after_save는 저장 트랜잭션 안이다. 두 요청이 같은 이름의 B/L을 동시에 저장하면 별칭 unique 인덱스에서 RecordNotUnique가 터지고, 그 예외가 트랜잭션을 되감아 B/L 저장 자체가 실패한다. 사용자 입장에선 화면에서 저장 버튼을 눌렀는데 이유 없이 실패하는 것이다. 원인은 자기가 알 바 아닌 별칭 bookkeeping인데.
after_commit으로 옮겼다.
def learn_cargo_owner_alias
return unless saved_change_to_consignee_name? || saved_change_to_cargo_owner_id?
return if cargo_owner_id.blank? || consignee_name.blank?
key = CargoOwnerResolver.normalize(consignee_name)
return if key.blank?
aliaz = CargoOwnerAlias.find_or_initialize_by(normalized_name: key)
aliaz.update!(cargo_owner_id: cargo_owner_id) if aliaz.cargo_owner_id != cargo_owner_id
rescue ActiveRecord::RecordNotUnique
retry # 다른 요청이 방금 같은 별칭을 만듦 → 재조회 후 UPDATE 경로
end
이제 별칭이 실패해도 B/L은 이미 커밋돼 있다. retry는 무한루프처럼 보이지만 아니다 — 재시도 시점엔 상대가 만든 행이 이미 있으므로 find_or_initialize_by가 그걸 집어 INSERT가 아닌 UPDATE로 가고, 같은 충돌이 다시 나지 않는다.
앞의 saved_change_to_* 가드도 같이 넣었다. 이게 없으면 B/L의 아무 필드나 저장할 때마다 별칭 조회·쓰기가 돌아 쓸데없는 쿼리가 붙는다.
일반화하면 이렇다. 부차 bookkeeping은 코어 저장과 같은 트랜잭션에 두지 않는다. 실패해도 코어가 살아야 하는 작업이면 커밋 밖으로 뺀다.
2. 정규식 하나가 비ASCII 화주를 통째로 날렸다
처음 정규화는 이랬다.
name.to_s.upcase.gsub(/[^A-Z0-9& ]/, " ") # ← 틀림
대한물산 같은 상호가 들어오면 전부 공백으로 치환돼 키가 빈 문자열이 된다. 그러면 resolve가 nil을 반환하고, 화주는 조용히 미배정으로 남는다. 예외도 로그도 없다. 리포트에서 그 화물이 그냥 안 보일 뿐이다.
[[:alnum:]]으로 바꿔서 유니코드 문자·숫자를 살렸다. 테스트도 같이 박았다.
test "normalize keeps non-ASCII (CJK) consignee" do
assert_equal "대한물산", CargoOwnerResolver.normalize("대한물산")
refute_nil CargoOwnerResolver.resolve("대한물산", organization: @org)
end
문자 클래스를 ASCII로 좁게 잡는 습관은 국내 데이터가 섞이는 순간 에러 대신 침묵으로 나타난다. 이런 종류는 테스트로 못 박아두지 않으면 리팩터링 때 또 좁아진다.
3. 삭제한 화주가 별칭을 타고 되살아났다
화주를 soft-delete 해도 별칭은 남아 있다. 그 별칭이 가리키는 화주를 그대로 반환하면, 삭제한 화주가 다음 B/L에서 부활한다. .kept와 discarded_at 체크를 넣어 폐기된 화주는 건너뛰고 새로 만들게 했다.
aliaz = CargoOwnerAlias.find_by(normalized_name: key)
owner = aliaz&.cargo_owner
next owner if owner && owner.discarded_at.nil? # discarded 화주는 되살리지 않음
soft-delete를 쓰는 프로젝트에서 캐시·매핑 테이블이 폐기 플래그를 안 보는 것은 반복되는 함정이다.
4. 안 하기로 한 것 — 지역 브랜드 자동 병합
ACME CANADA와 ACME는 같은 회사일까? 대개는 그렇지만, 아닐 때가 있다. 별도 법인이라 청구·정산이 갈리면 자동 병합은 회계를 오염시킨다. 문자열만 보고는 구분이 안 된다.
그래서 접두어가 같다는 이유로 묶는 규칙은 넣지 않았다. 대신 사람이 한 번 교정하면 그게 별칭으로 남아 다음부터 자동이 된다.
test "resolve honors an existing alias (learned mapping wins)" do
acme = CargoOwner.create!(name: "Acme")
CargoOwnerAlias.create!(normalized_name: "ACME CANADA", cargo_owner: acme)
owner = CargoOwnerResolver.resolve("ACME CANADA INC.", organization: @org)
assert_equal acme.id, owner.id
end
이게 이 설계의 핵심 트레이드오프다. 자동화의 경계를 “되돌리기 쉬운 것”에 맞춘다. 오분리(한 회사가 둘로 보임)는 사람이 한 번 고치면 끝이고, 오병합(다른 회사가 하나로 합쳐짐)은 어디서부터 잘못됐는지 찾기가 어렵다. 비용이 비대칭이면 싼 쪽 실수를 택한다.
곁들여 넣은 무결성 방어
리뷰에서 같이 지적된 것들을 DB·모델 양쪽에 깔았다.
# 활성 화주 기준 org내 이름 유일 — 동시 생성 경쟁 방어
add_index :cargo_owners, [ :organization_id, :name ], unique: true,
where: "discarded_at IS NULL", name: "index_cargo_owners_on_org_and_name_active"
# dangling 참조 차단
add_foreign_key :house_bills, :cargo_owners, on_delete: :nullify
모델 쪽엔 다른 조직 id나 없는 id가 들어오면 거부하는 검증을 얹었다. 멀티테넌트에서 cargo_owner_id는 폼으로 오는 값이라 컨트롤러만 믿을 수 없다.
def cargo_owner_within_tenant
errors.add(:cargo_owner_id, "가 유효하지 않습니다") if cargo_owner_id.present? && cargo_owner.nil?
end
테넌트 스코프가 걸린 연관은 타 조직 id를 읽으면 nil이 된다는 성질을 그대로 검증에 쓴 것이다. 별도 조회 없이 크로스테넌트 참조가 걸린다. 이 커밋 시점 전체 스위트는 931건 통과였다.
한계 · 다음 계획
- 접미어 목록이 영미권 위주다.
GMBH,S.A.,PTE,주식회사같은 표기는 아직 안 뗀다. 실데이터에서 미스가 보이면 목록을 늘리는 식으로 대응할 생각이다. - 오타는 못 잡는다.
ACME와ACEM은 다른 키다. 편집거리 기반 후보 제시는 검토만 하고 넣지 않았다 — 자동 병합을 안 하기로 한 이상, 후보를 띄우려면 UI가 먼저 필요하다. - 별칭 관리 화면이 없다. 잘못 학습된 별칭을 지우려면 지금은 콘솔이다. 사람 교정이 곧 학습인 구조에서 잘못된 학습을 되돌릴 창구가 없는 건 갭이 맞다. 다음 순번.
- 정규화 규칙을 바꾸면 기존 별칭 키와 어긋난다. 접미어를 추가하는 순간 과거 키는 새 규칙으로 다시 만들어지지 않는다. 규칙 버전과 재계산 태스크가 필요한데 아직 없다.
정리
- 자유 텍스트를 엔티티로 묶는 일은 AI보다 정규화 키 + 사람 교정 학습이 먼저다. 싸고, 결과가 설명 가능하고, 틀렸을 때 되돌리기 쉽다.
- 부차 bookkeeping은
after_commit으로. 트랜잭션 안에 두면 그 실패가 코어 저장을 죽인다. - 문자열 처리에서 ASCII 문자 클래스는 에러가 아니라 침묵으로 실패한다.
- 자동화 범위는 정확도가 아니라 실수의 되돌리기 비용으로 정한다. 오분리는 싸고 오병합은 비싸다.