자동화가 실패한 자리에 사람을 넣는다 — 문서 워크플로에 비상구 4개를 달았다

왜 — 자동화가 90%만 맞으면, 나머지 10%가 시스템의 평판이 된다

사내에서 만드는 물류 운영 SaaS 얘기다. 선적 건마다 문서가 줄줄이 오간다. 도착통지(A/N)를 화주에게 보내고, 배송지시서(D/O)를 운송사에 보내고, 운송사가 인수증(POD)을 올리면 그걸 다시 화주에게 전달한다. 그 사이에 인보이스·패킹리스트 PDF가 메일로 굴러들어온다.

이걸 상당 부분 자동화해뒀다. 파일을 드롭하면 컨테이너번호를 읽어 해당 선적에 붙고, 버튼 하나로 PDF가 생성되고 메일이 나간다.

문제는 자동화가 틀렸을 때가 아니라 아무것도 안 했을 때 생긴다. 컨테이너번호를 못 읽으면 파일은 어디에도 붙지 않는다. 운송사가 포털 대신 개인 메일로 POD를 보내면 시스템엔 POD가 영영 없다. 이런 건 에러가 아니라 침묵이라 아무도 모른다. 그리고 며칠 뒤 담당자가 화면을 열면 회색으로 비활성화된 버튼이 “Forward after driver uploads POD”라고 말하고 있다. 담당자 메일함엔 POD가 있는데.

이번 작업은 기능 추가가 아니라 그 침묵과 막다른 골목을 메우는 일이었다. 네 군데를 고쳤다.

1. 조용한 실패를 표면화한다

인보이스·패킹리스트(CIPL) PDF를 드롭하면 백그라운드 잡이 컨테이너번호를 뽑아 선적에 붙인다. 매칭이 안 되면 종모양 알림 하나를 남기고 끝냈다. 그런데 그 알림은 새로고침 전엔 안 보인다. 드롭한 사람은 방금 화면에 있는데 아무 반응이 없으니 성공한 줄 안다.

두 경로로 바꿨다. 실시간 토스트(즉시)와 지속 알림(폴백).

def notify_unmatched(org, blob, reason)
  msg = "CIPL 미첨부 — #{reason} (#{blob.filename}). " \
        "해당 BL 등록 후 그 선적의 품목 탭에서 올려주세요."
  begin
    Turbo::StreamsChannel.broadcast_append_to(
      "shipments2:#{org.id}",
      target: "toast-container",
      partial: "shared/flash_toast",
      locals: { type: "alert", message: msg }
    )
  rescue StandardError => e
    Rails.logger.warn("[CiplMatchJob] toast 브로드캐스트 실패: #{e.class} #{e.message}")
  end
  Notification.broadcast_to_org(org, title: "CIPL 미첨부 — #{blob.filename}", body: msg, url: "/shipments2")
end

설계 판단 두 개가 들어 있다.

브로드캐스트 실패를 삼킨다. 알림 채널이 죽었다고 잡 전체가 실패하면 안 된다. 토스트는 편의고, 진짜 기록은 지속 알림 쪽이다. 그래서 rescue로 로그만 남기고 계속 간다.

메시지에 다음 행동을 넣는다. “실패했습니다”만 띄우면 담당자는 여전히 뭘 해야 할지 모른다. 붙일 BL이 없다는 게 원인이므로, BL 등록 후 어느 탭에서 직접 올리면 되는지까지 문장에 담았다. 원본 파일은 이미 오브젝트 스토리지에 올라가 있어서 유실은 없다 — 이 사실도 주석에 남겨뒀다. 나중에 이 코드를 보는 사람이 “실패하면 파일이 날아가나?”를 다시 확인하지 않도록.

2. 재발송(resend)과 재발행(regenerate)은 다른 동작이다

D/O를 이미 보낸 뒤 운송사가 “메일 못 받았다”고 하는 일이 잦다. 그런데 발송 완료 상태에선 Resend 버튼이 disabled에 title="Resend coming soon"이었다. 미뤄둔 이유가 있었다. D/O 발송 로직이 draft 상태 전용이라, 순진하게 재사용하면 D/O가 중복 생성되고 매직링크가 새로 발급되고 상태가 꼬인다.

그래서 재발송을 별도 액션으로 분리했다. 핵심은 “아무것도 새로 만들지 않는다”다.

# 기존 활성 매직링크 재사용(없을 때만 발급) — 새 링크 남발 방지.
link = do_.magic_links.where(link_type: "trucking_company").order(:created_at).last
link ||= do_.magic_links.create!(
  organization: do_.organization, link_type: "trucking_company", linkable: do_,
  recipient_name: do_.trucking_company&.name, recipient_email: to, expires_at: 90.days.from_now
)
link.update!(recipient_email: to) if link.recipient_email.to_s != to

DeliveryOrderMailer.dispatch(do_, link).deliver_later # 상태 전이 없음(재발송만)

매직링크를 재사용하는 건 편의 문제가 아니다. 운송사가 이미 첫 메일의 링크를 북마크했을 수 있고, 재발송할 때마다 새 링크를 뿌리면 어느 링크가 유효한지 아무도 모르게 된다. 외부로 나간 URL은 함부로 늘리지 않는다.

그리고 내용이 바뀌었을 땐? 재발송이 아니라 재발행이다. 픽업번호나 터미널이 바뀌면 Regenerate D/O로 PDF를 다시 만들고, 그 다음 재발송하면 메일러가 최신 문서를 자동으로 집는다. 이 구분을 코드 주석과 화면 문구 양쪽에 적었다. 담당자가 두 버튼 앞에서 헷갈리는 순간 설계가 실패한 거라서.

테스트로 못 박은 것도 이 지점이다.

assert_no_difference [ "DeliveryOrder.count", "MagicLink.count" ] do
  # ... resend 요청 ...
end
assert_equal "dispatched", do_.reload.status, "재발송은 상태를 바꾸지 않음"
assert_equal "[email protected]", link.reload.recipient_email, "기존 매직링크 재사용(수신자만 갱신)"

3. 화면에만 쓴 값은 저장한 값이 아니다

Regenerate를 눌렀더니 폼이 텅 비어 있었다. 운송사명과 배송지를 처음 발행 때 분명히 입력했는데.

원인은 단순했다. D/O 생성 시 firms_code와 픽업 터미널만 컨테이너에 저장하고, delivery_location과 trucker는 PDF 렌더링에만 넘기고 버렸다. 폼 기본값도 nil로 하드코딩돼 있었다.

cont.update(firms_code: dopts[:firms_code].presence || cont.firms_code,
            pickup_location_name: dopts[:pickup_location].presence || cont.pickup_location_name,
            delivery_location_name: dopts[:delivery_location].presence || cont.delivery_location_name,
            trucking_company_name: dopts[:trucker].presence || cont.trucking_company_name)

한 줄짜리 수정이지만 교훈은 한 줄이 아니다. 문서를 생성하는 액션은 문서만 만드는 게 아니라 상태를 남겨야 한다. 안 그러면 “다시 하기”가 “처음부터 하기”가 된다. 사용자 눈에 재발행은 한 번의 클릭이지만, 값을 안 남기면 열 번의 타이핑이다.

당시 필드 일부는 데이터소스가 확정 전이라 일부러 저장을 미룬 상태였는데, 그 유예가 그대로 굳어 있었다. 이런 건 “나중에”라고 주석 달아두면 반드시 잊는다.

4. 죽은 회색 버튼은 기능이 아니라 막다른 골목이다

POD 행의 Forward 버튼은 POD가 없으면 회색 비활성이었다. 문구는 “운송사가 올린 뒤 전달 가능”. 논리적으로는 맞다. 문제는 운송사가 포털을 안 쓰고 메일로 보내는 경우가 실제로 있다는 것. 그럼 담당자는 손에 POD를 들고 영원히 회색 버튼을 보게 된다.

비활성 버튼을 지우고, 항상 눌리는 업로드 진입점을 그 자리에 놨다.

def upload_pod
  authorize @shipment, :update?
  file = params[:file]
  ok = file && (UPLOAD_PDF.include?(file.content_type) ||
                file.original_filename.to_s.match?(/\.(pdf|png|jpe?g)\z/i))
  unless ok
    flash.now[:alert] = file ? "POD는 PDF 또는 이미지(png/jpg)만 가능합니다." : "POD 파일을 선택하세요."
    load_modal
    return render_modal_with_rows
  end
  blob = ActiveStorage::Blob.create_and_upload!(io: file.to_io, filename: file.original_filename,
                                                content_type: file.content_type)
  doc = Document.attach_original!(@shipment, blob, category: "pod")
  flash.now[doc ? :notice : :alert] = doc ? "POD 업로드됨 — 이제 고객에게 Forward 가능." : "이미 업로드된 파일(중복)."
  load_modal
  render_modal_with_rows
end

새로 만든 건 컨트롤러 액션과 라우트뿐이다. 첨부는 기존 Document.attach_original!을 그대로 썼는데, 이 메서드가 blob checksum으로 중복을 걸러준다. 같은 POD를 두 번 올려도 문서가 두 개 생기지 않고, 화면엔 “이미 업로드된 파일(중복)”이 뜬다.

허용 타입은 application/pdf, image/png, image/jpeg 화이트리스트에 확장자 검사를 더했다. content-type만 믿으면 브라우저·클라이언트가 보내주는 값에 의존하게 되고, 확장자만 믿으면 이름만 바꾼 파일이 들어온다. 둘 다 통과해야 받는다. POD는 사진이나 스캔본이라 파싱은 아예 하지 않는다 — 붙이는 것까지가 이 액션의 일이다.

배운 것

네 건을 다 하고 나서 공통점이 보였다. 전부 “자동 경로가 실패했을 때 사람이 이어받을 수 있는가” 하나였다.

  • 실패는 반드시 동기적으로 표면화한다. 비동기 알림만으론 그 순간의 사용자에게 닿지 않는다.
  • 실패 메시지엔 원인이 아니라 다음 행동을 쓴다. “매칭 실패”가 아니라 “어디서 직접 올려라”.
  • 재시도는 멱등이어야 한다. 상태를 바꾸지 않고, 새 리소스를 만들지 않는다. 특히 외부로 나간 링크는.
  • 비활성 버튼은 최후의 수단이다. 눌러도 아무것도 안 되는 버튼을 놓느니, 항상 실행 가능한 대안을 놓는다.

마지막 하나는 UI 취향 문제로 보이지만 아니다. 비활성 버튼은 “이 시스템으로는 이 일을 끝낼 수 없다”는 선언이고, 그 순간 담당자는 시스템을 떠나 메일과 엑셀로 돌아간다. 한 번 떠나면 그 다음 건도 떠난다.

각 경로마다 테스트를 붙였다. 컨트롤러 5개(재발송 2, 재발행 prefill 1, POD 업로드 2)와 잡 1개. 특히 “안 만들어야 한다”는 성질은 테스트가 아니면 지킬 수 없다. assert_no_difference는 이런 데 쓰라고 있는 물건이다.

한계·다음 계획

  • 수동 업로드는 여전히 사람이 화면에 들어와야 한다. 근본 해결은 메일 인제스천이다. 전용 수신 주소로 온 메일에서 첨부를 뜯어 자동 등록하는 설계를 문서로만 잡아둔 상태고, 아직 구현 전이다.
  • POD 업로드에 파싱이 없다. 어느 컨테이너 건인지 담당자가 모달을 열어 지정하는 방식이라, 여러 건을 한 번에 처리할 수 없다.
  • CIPL 미매칭 알림은 아직 재시도 큐가 아니다. 나중에 BL이 등록되면 그때 자동으로 붙는 게 맞는데, 지금은 알림만 남고 사람이 다시 올려야 한다. 미매칭 blob을 보관함에 넣어두고 BL 생성 시 재매칭을 거는 쪽으로 가야 한다.
  • 재발송 이력이 얇다. 발송 이벤트는 기록하지만 “몇 번째 재발송인지”를 화면에서 보여주지 않는다. 운송사와 분쟁이 생기면 필요한 정보다.

FAQ

Q. 재발송을 기존 발송 액션에 파라미터로 붙이면 안 되나?
가능하지만 권하지 않는다. 발송은 상태 전이(draft → dispatched)를 동반하고 재발송은 상태를 유지한다. 한 액션에 두 성질을 넣으면 조건문이 상태머신을 대신하게 되고, 나중에 상태가 하나 늘 때마다 그 조건문을 다시 읽어야 한다. 라우트와 액션을 나누면 테스트도 “상태가 안 바뀐다”를 직접 단언할 수 있다.

Q. 매직링크를 재발송마다 새로 발급하면 더 안전하지 않나?
보안만 보면 그렇다. 다만 수신자가 외부(운송사)고 링크가 메일에 남는 상황에선, 링크가 늘수록 “어느 게 유효한가”를 아무도 모르게 된다. 그래서 링크는 하나로 유지하고 만료(90일)로 통제하는 쪽을 택했다. 수신자가 바뀌면 링크를 새로 만드는 게 아니라 기존 링크의 수신자 정보를 갱신한다. 유출 우려가 커지는 도메인이라면 반대로 가는 게 맞다 — 트레이드오프지 정답이 아니다.

Q. 백그라운드 잡의 실패를 실시간으로 알리는 다른 방법은?
Turbo Streams 브로드캐스트 말고도 폴링이나 잡 상태 테이블 + 배지 방식이 있다. 다만 어떤 방식을 쓰든 원칙은 같다. 알림 전송 실패가 잡 실패로 번지면 안 된다. 브로드캐스트를 rescue로 감싸고, 지속되는 기록(알림 레코드·로그)을 별도로 남긴다. 실시간은 있으면 좋은 것이고, 없어도 사실이 남아야 한다.

Q. 업로드 파일 검증을 content-type과 확장자 둘 다 보는 게 과한가?
과하지 않다. content-type은 클라이언트가 주는 값이라 위조가 쉽고, 확장자는 이름만 바꾸면 그만이다. 둘을 함께 보면 실수로 잘못 올린 파일은 대부분 걸러진다. 다만 이건 방어의 1차선일 뿐이라, 임의 파일이 외부에서 들어오는 경로라면 매직바이트 검사나 별도 스토리지 격리까지 봐야 한다.

Leave a Comment