DEVELOPER HANDOFF · RECONSTRUCTED

물류비 개선 도구
기획서

분석 기준을 코드로 실험하고 웹 도구와 청구무게 보정으로 연결하는 기능 명세

2026-11-02 · 역사적 경험 기반 재구성 / 개발 제안 포함

서비스 정의·문서의 범위

관행으로 물류사를 고르던 판단을, 프로젝트의 운임·작업 조건·일정·품질을 비교하는 반복 가능한 도구로 바꾼다.

당시 경험을 바탕으로 재구성한 개발 전달용 예상 기획서다. 실제 개발팀 전달 이력으로 제시하지 않는다. 역사적 구현, 이번 문서의 개발 제안, 확인할 계약 조건을 구분한다.

구분	내용
역사적 구현	분석 프로젝트의 비교값을 코드로 실험한 후 Streamlit 계산·비교 기능에 반영. 실제 3PL 청구무게로 모델을 학습하고 결과를 수동 반영.
이 문서의 대상	입력·요금 검증, 박스/비용 비교, 업체 선택 이유, 예측값의 출처·검수, 결과 내보내기.
통합 서비스와 연결	C-3 주문서 자동화가 가공한 박스 구성과 C-4 업체·요금 기준을 활용하는 확장 설계.
실제 운영 성과	분석 연평균 실절감 3.5억 원 이상, 도구 연평균 실절감 1.5억 원 이상은 사용자 확인 별도 성과. 합산하거나 모델 단독 효과로 귀속하지 않는다.

문제정의·질문의 진화

단계	확인할 내용
눈앞의 관행	주로 A업체를 선택했다. 관행이 실제 조건에 맞는 비용·품질·일정 판단인지 확인할 필요가 있었다.
첫 질문	늘 쓰던 업체를 선택해도 프로젝트별 손해나 불필요한 비용이 없을까?
재검토	가장 저렴한 운임만 비교하면 충분한가? 포장·작업료·청구무게·일정·품질은 어떤 차이를 만드는가?
정보 수집	진행하던 분석 프로젝트에서 비교값을 얻고, 3PL 방문 인터뷰와 직접 포장에서 박스 공간·작업 조건의 아이디어를 보완.
문제 재정의	분석 기준을 건별 대응으로 소비하지 않고, 반복 적용할 수 있는 비용·운영 조건 비교 구조가 필요하다.

가설·제약·검증 방식

항목	명세
가설	분석에서 얻은 요금과 조건을 코드로 계산하고 실제 배송 조건과 비교하면, 감 대신 근거로 물류사와 방식을 선택할 수 있다.
제약	일정과 작업 품질 때문에 최저가 업체를 선택할 수 없는 경우가 있다. 국내/해외를 나누거나 프로젝트 전체를 한 업체에 맡길 수 있다.
작은 실행	일부 비교 계산부터 코드화 → 수작업/기존 분석값과 대조 → 계산 조건 수정 → Streamlit 기능화.
확인 항목	박스 수, 사용 운임 구간, 추가 작업료의 시작 수량, 누락 비용, 선택 가능한 일정과 업체.
검증 수준	당시 운영 비교와 확인에 기반한다. 통제 실험이나 검증된 모델 정확도를 주장하지 않는다.
현재 개발 목표	동일 입력과 동일 요금 버전에서 계산 재현, 근거가 보이는 비교, 미산정 항목의 명시, 사람이 선택 이유를 판단할 수 있는 결과.

사용자·역할·범위

사용자	행동	권한 제안
물류 담당자	프로젝트 구성 입력, 요금·예측값 확인, 업체 비교·선택, 결과 검수	계산·작업 중 값 수정·내보내기
물류 어드민	3PL·국가/무게 운임·작업료·포장 기준 관리	공통 기준 등록·수정, 적용일·근거 확인
관계 부서	선택 근거와 일정·비용 결과 확인	결과 공유본 조회. 민감한 원본 배송정보는 공유본에서 제외

계정·권한은 통합 C의 제안이다. 과거 로컬 Streamlit에 같은 계정 체계가 있었다고 서술하지 않는다.

화면 IA·메뉴

화면	목적	핵심 요소
S01 프로젝트 입력	구성과 배송 범위를 정함	프로젝트명, 국내/해외 범위, 국가, 상품/수량, 예정일
S02 포장·무게 확인	실제 청구에 쓰일 박스 정보를 확인	박스별 상품, 포장 한도, 청구무게, 수동/예측 출처
S03 비교 조건	같은 기준으로 후보 비교	3PL 후보, 운임표, 작업료, 일정 가능, 품질 조건
S04 비용 비교	총액과 구성 항목·미산정 사유 확인	운임/작업비/기타비용, 후보별 합계, 선택 이유
S05 검수·내보내기	근거를 남긴 결과 공유	입력값·요금 기준·무게 출처·선택/제외 이유·검수 상태

화면 와이어프레임·상호작용

입력

프로젝트명 [텍스트]
배송 범위 [국내/해외]
국가 [선택] · 예정일 [날짜]
상품 | 수량 | 박스당 수량 | 무게 출처
[행 추가] [샘플 불러오기] [비교 조건 확인]

비교 결과

3PL | 일정 가능 | 운임 | 작업비 | 미산정 | 합계
선택 [라디오] · 선택 이유 [텍스트]
박스별 상세 [펼치기]
[조건 수정] [검수 완료] [결과 내보내기]

트리거	반응
국내/해외 전환	적용 국가·운임 기준을 다시 확인. 과거 계산 결과는 검수 해제.
수량·포장·무게·요금 변경	박스와 비교 결과를 재계산하고 이전 검수 완료 상태를 해제.
필수 항목 누락	행 번호와 항목명으로 안내하고 첫 오류 위치에 초점 이동.
일정 불가 후보 선택	기본 선택 차단. 예외 협의가 필요하면 확인 필요 상태로 두고 사유 기록.
더 비싼 업체 선택	허용. 일정·품질·프로젝트 일괄 운영 등 선택 사유 기록.
미산정 비용 존재	0원으로 표시하지 않고 ‘확인 필요’. 확정 비교와 미확정 결과를 구분.

입력·유효성 명세

입력	검증·예외
수량	1 이상의 정수. 공백·음수·소수·NaN은 행 번호와 함께 오류. 취소/미출고 수량 0은 요청 처리 정책과 별개.
박스당 수량	1 이상의 정수. 실제 혼합 포장 제약이 없다고 가정하지 않는다.
국가	운임표의 국가 코드와 매칭. 미지원 국가는 수동 확인 대상으로 남김.
청구무게	양수 g 단위. kg 입력은 단위 선택 후 환산. 미확인 값을 0g으로 보정하지 않음.
일정	프로젝트 예정일과 작업 가능 여부 확인. 달력 날짜만으로 업체 가용성을 자동 확정하지 않음.
요금	통화·적용 기간·국가·무게 구간이 필요. 공란을 무료로 해석하지 않는다.
개인정보	비교 계산에 불필요한 이름·주소·전화번호는 보관하지 않는 방향. 실제 주문서 검수와 분리.

박스·작업료 계산 정책

규칙	개발 지시
단일 상품 박스 분할	수량 q, 박스 한도 c일 때 ceil(q/c)개로 분할. 박스별 수량 합이 q와 같아야 한다.
혼합 상품	상품별 환산 용량과 포장 규칙은 C-3을 참조. 이 문서의 단일 상품 계산 예시를 혼합 포장 전체 로직으로 대체하지 않는다.
사은품	앨범과 함께 보내는 사은품은 첫 박스 연결 규칙을 적용하고, 별도 박스 생성/중복 반영 여부를 검수. 용량 환산값 1과 주문번호 -1은 서로 다른 규칙.
추가 작업료	무료 수량 한도가 4라면 5번째부터 발생. max(0, 박스 내 과금 수량-무료 한도)×단가. 사은품 과금 제외 여부는 계약/기존 규칙 확인.
포장·부자재	계약에 포함된 비용을 별도의 box_quotes로 이중 합산하지 않는다. 포함 여부 미확인 시 항목별 확인 필요.
무게 반올림	실제 계약 기준 우선. 과거 500g 단위 처리와 새 구간 정책을 혼용하지 않는다.
운임 구간	(weight_from_g, weight_to_g]를 기준으로 제안. 경계가 계약과 다르면 프로필에서 명시하며 자동 추정 금지.
합계	각 박스 운임+작업비+확인된 기타 비용의 합. 미산정 항목이 하나라도 있으면 확정 총액으로 제시하지 않음.

청구무게 예측·수동 반영

항목	명세
예측 대상	3PL이 청구한 박스 단위 무게. 여러 상품과 포장이 포함된 값이며 단일 상품 실측 무게와 구분.
학습 데이터	실제 청구 배송 raw를 전처리해 사용한 역사적 경험. 최초 MSE 확인 이후 지속 성능관리까지 이뤄졌다고 주장하지 않는다.
모델	과거 랜덤 포레스트. 학습은 별도 분석 과정. 본 웹 화면에서 자동 재학습하지 않는다.
서비스 반영	모델 결과를 담당자가 확인해 수동 반영. 모델 버전·기준일·단위·대상 범위를 새 개발 시 명시하도록 제안.
부족한 입력	미지원 상품/혼합 구성 또는 출처 없는 계수는 예측 불가. 실제 무게나 담당자 확인값 입력 유도.
수정	예측값을 수동 변경할 수 있으나 원래 예측값과 변경 사유를 결과에 남기는 기능 제안.
검수	실제 청구값과 차이·운임 구간 변경 여부 확인. 예측은 보조 근거이며 최저가 자동 확정에 사용하지 않음.
후속 관리	MAE/MSE 등 모델 지표와 비용/구간 오차를 함께 관리하는 것은 개선 제안. 과거 달성 정확도로 제시하지 않음.

데이터 구조·통합 연결

구조	필드·관계
warehouses	id, name, 기본 작업비, 무료 수량, 추가 작업료, 계약 근거. 업체 주소·연락처는 C-4 관리.
warehouse_shipping_rates	warehouse_id, country_code, weight_from_g, weight_to_g, amount, currency, 적용 기간 제안. 같은 국가·기간의 구간 중복 차단.
products	id, sku_number, 포장 기준·청구무게 보정값과 출처. 기존 구조의 저장 위치는 C-3/C-4 구현과 합의.
브라우저 작업 상태	프로젝트 구성, 박스, 입력 기준, 후보·선택·미산정 사유. 원본 업로드 파일의 서버 영구 보관은 범위 제외.
결과 공유본	선택 기준·무게 출처·미산정·검수 상태가 포함된 내보내기 결과. 별도 자동화 작업 백업 테이블을 새로 만들지 않음.

위 데이터 항목 중 적용 기간·예측 출처·선택 사유는 개발 제안이다. 과거 파일 또는 현재 JSON 저장소에 같은 필드가 이미 있다는 뜻은 아니다.

요구사항 정의

ID	요구	인수 기준
LC-R01	동일 입력 기준으로 후보 비교	국가·구성·청구무게·요금 기준이 결과에 함께 표시
LC-R02	근거 있는 비용 분해	박스별 운임·작업료·무료 한도·추가 수량 확인 가능
LC-R03	미지원 구간의 명시	해당 항목 확인 필요, 합계 확정/최저가 배지 부여 금지
LC-R04	일정·품질 고려 선택	최저가 이외 후보 선택과 이유 입력 허용
LC-R05	예측/수동값 출처 구분	단위·기준·수정 사유를 함께 확인
LC-R06	입력 변경 후 재검수	수량·요금·무게 변경 시 검수 완료 해제
LC-R07	검수 가능한 공유 결과	입력·계산 근거·미산정·선택 사유가 유지
LC-R08	개인정보 최소화	계산에 불필요한 원본 주소·전화번호를 공유본에 포함하지 않음

계산 상호작용 예시

단일 상품·국내 운임의 상호작용 예시다. 아래 요금은 기능 설명을 위해 만든 가상 값이며 실제 계약/분석 결과가 아니다. 혼합 포장·ML 예측은 수행하지 않는다.

예외·팝업·재처리

상황	안내·동작
필수값 누락	‘2행의 수량을 확인해주세요.’처럼 위치와 항목 안내. 계산 실행 전 차단.
국가/무게 운임 미존재	‘해당 국가·무게의 운임이 없습니다. 기준 확인 후 다시 계산해주세요.’
예측 대상 불일치	‘이 구성에 적용할 예측 기준이 없습니다. 청구무게를 직접 확인해주세요.’
요금 기준 변경	‘요금 기준이 변경되어 검수가 해제되었습니다.’ 재계산·재확인 필요.
비싼 업체 선택	금액 차이와 일정·품질 이유를 확인. 임의로 최저가로 되돌리지 않음.
재처리	현재 입력으로 새 결과를 계산하며 이전 결과를 누적 합산하지 않음. 완료/실패 상태와 수정 필요한 입력을 구분.

인수 테스트

ID	시나리오	기대 결과
LC-T01	12개·박스당10개	박스2개, 구성10+2, 전체12 일치
LC-T02	수량0·음수·소수·공백	해당 입력/행 안내, 계산 차단
LC-T03	무료 한도4에서 수량4와5	추가 작업 수량0과1
LC-T04	무게1000g·1001g·2000g·2001g	예시 구간별 조회, 지원 범위 밖은 확인 필요
LC-T05	운임 없는 국가	0원/최저가 표시 안 함
LC-T06	구간 중복 또는 날짜 중복	어드민 입력 단계에서 모호한 요금 차단
LC-T07	예측값을 수동 수정	출처·변경 사유 확인, 재검수 필요
LC-T08	더 비싸지만 일정 가능한 업체 선택	선택 유지와 사유 기록
LC-T09	혼합 상품을 단일 상품 계산기로 입력 시도	데모 범위 안내. 실제 개발은 C-3 포장 규칙 사용
LC-T10	조건 변경 후 내보내기	이전 검수 상태가 유지되지 않음
LC-T11	입력 원본에 개인정보 포함	공유 계산 결과에 불필요한 개인정보 제외
LC-T12	사은품이 별도 박스로 처리되는 결과	기존 담당자의 기준과 비교, 첫 박스 연결을 수정 후 재검수

위 표는 구현 시 인수 기준이며 모두 실행 완료한 소프트웨어 테스트를 뜻하지 않는다.

검증 지표·단계별 개발

단계	결과물·확인
1. 비교 기준 정리	분석값·계약·일정·포장 기준과 누락 항목 확인
2. 작은 코드 실험	일부 실제 배송 조건과 수작업 계산값 대조, 경계·무료 한도 검증
3. Streamlit 기능화	구성 입력→조건 확인→비교→검수→내보내기
4. 청구무게 보정	모델 결과를 확인해 수동 반영, 실제 청구와 차이 기록
5. 통합 서비스 연결 제안	C-3 박스 결과와 C-4 공통 요금을 재사용. 도입 후 처리시간·미산정률·비용차이·예측오차 측정

확인 필요·연결 문서

확인 사항	현재 상태
계약별 운임·부자재·최소비용·할증	실제 요금표를 근거로 확정해야 함. 가상 데모 값으로 대체 금지
비용 성과 산출 범위	사용자가 확인한 연평균 수치. 두 성과의 범위는 분리하고 모델 기여로 일반화하지 않음
전체 개선 과정 근거	개선 분석 정리 HTML과 원본 보고서 경로를 별도 연결
실제 Streamlit 체험본·영상	준비 중. 새 통합 프로토타입을 과거 Streamlit으로 표시하지 않음

C-3 자동화·예측 명세 · C-4 요금·기준 관리 · 물류비 개선 전체 과정 · 포트폴리오로