SERVICE PLANNING · C-4 · 2026.11.01

3PL과 운영 기준 관리

3PL·주소·요금·포장 기준·상시판매 대상·관리 계정을 유지하는 운영 명세.

개발 전달용 상세 명세 v1.0 · 하나의 서비스 / 단계별 구현 설계

C-4 / DEVELOPMENT SPECIFICATION

서비스 개요·관리 범위

물류 담당자가 반복 계산과 요청 처리에서 같은 기준을 쓰도록, 3PL·주소·운임·상품 포장·상시판매 대상·계정을 관리한다.

범위	소유
3PL·주소·요금	warehouses + warehouse_shipping_rates
상품포장·무게	products의pack_capacity·charge_weight_g.상품기본정보는C-1공유.
상시판매	recurring_rules + recurring_rule_lines.자동실행·실행이력·알림은제외.
계정	actors.서버인증과역할은C-0공유.

carrier/box_quotes/sku_sequence/actor_session/정기실행·알림·공통감사 테이블을새로추가하지 않는다.상품수정이력은C-1의업무원장확장,요청상태이력은C-2의업무기록으로유지한다.

C-4 / DEVELOPMENT SPECIFICATION

권한·메뉴·요구사항

사용자	읽기	변경
요청자	상품·보관3PL의표시명	운영기준화면접근불가
물류 담당자	가공에필요한3PL·요금·포장 기준	C-1바코드/속성/재고수정가능.계약·운임·계정은불가
어드민	전체	3PL·요금·포장계수·상시판매·계정생성/재설정

요구 ID	개발 지시	검수 기준
C4-R01	3PL 업체와 주소·연락처를 등록·수정한다.	warehouse_id 유지,임의센터/별도carrier생성없음
C4-R02	국내/해외 기본 비용과 추가 작업비를 관리한다.	0과미등록구분·5개부터추가시무료4개
C4-R03	국가·무게구간별 운임을 관리한다.	구간중복 차단·경계값일관·누락은미산정
C4-R04	상품 포장 수량·청구무게를 명시적으로 변경한다.	이번계산임시값과DB영구값구분
C4-R05	상시판매 rule과 대상 상품을 등록한다.	규칙+규칙상품만저장,정기실행/알림테이블없음
C4-R06	어드민이 계정을 만들고 비밀번호를 재설정한다.	ID·이름·역할·팀·비밀번호,평문저장/노출없음
C4-R07	기준 변경이 다른 모듈에 미치는 영향을 안내한다.	요청주소·과거파일자동덮어쓰기없음
C4-R08	운영 기준의 누락·오류를 찾고 복구한다.	실패시기존값 유지,참조 중데이터물리삭제제한

C-4 / DEVELOPMENT SPECIFICATION

3PL 목록·추가·주소 수정

3PL 관리화면 구조 예시

업체	주소	연락처	운임	관리
다보내	예시주소	예시담당자	국가·무게기준	상세
패박	예시주소	예시담당자	국가·무게기준	상세

3PL 등록·수정화면 구조 예시

업체명 *다보내

주소 *우편번호·기본주소·상세주소

담당자·연락처선택

메모수거·입고 제약 등

필드·행동	규칙
업체명	공백 차단·비슷한업체명은중복확인.같은ID의주소변경은새업체생성이아님.
주소	우편번호·기본·상세별도입력.실수령주소와구분.
삭제	상품/요청/운임/rule참조 중이면물리삭제차단.미사용정리방식은추가합의.
추가	새업체선택값C-1/C-2에반영.캘린더행·색상확장정책은확인 필요.

C-4 / DEVELOPMENT SPECIFICATION

기본 배송비·작업비·추가비

필드	의미·유효성
domestic_base_fee	국내박스기본배송비.0은무료,빈값은미등록.
domestic_labor_fee / overseas_labor_fee	국내·해외기본작업료,각박스단위.
material_fee	부자재비.기존예시100/150원은이항목.
free_item_qty	추가작업비가없는일반상품수량.5개부터추가이면4.
extra_unit_fee	초과개당추가작업비.
extra_fee_cap	NULL=상한없음 /0=추가비0으로제한.기존코드0=무상한과변환구분.

추가작업비 = max(0, 청구대상수량 − 무료수량) × 초과단가
상한이 NULL이 아니면 min(추가작업비, 상한)
국내 = 기본배송비 + 국내작업료 + 부자재 + 추가작업비
해외 = 국가·무게운임 + 해외작업료 + 부자재 + 추가작업비

증정품추가작업비제외는사용자설명기본안.물리적인품목수량·박스무게와청구대상수량을분리해표시한다.실제청구계약이우선이며불명확한경우미산정/확인 필요.

C-4 / DEVELOPMENT SPECIFICATION

국가·무게 구간 · 경계와 누락

운임표화면 구조 예시

국가	시작g(초과)	종료g(이하)	운임(예시)
JP	0	500	예시단가
JP	500	1000	예시단가

개념	설명
weight_from_g	해당구간의최소경계.포함하지않음.
weight_to_g	최대경계.포함함.따라서0
경계예시	500g은첫구간,501g은둘째구간.500g올림프로필을쓸경우올림후값으로매칭.
중복	같은3PL·국가에서범위겹침차단.연속구간끝=다음시작은허용.
누락	국가/범위없으면미산정.0원·가장가까운가격으로자동대체하지않음.
계약차이	운송서비스/부피무게·구간반올림방식이별도이면프로필확인 필요.현재필드만으로모든계약을표현한다고주장하지않음.

C-4 / DEVELOPMENT SPECIFICATION

상품별 포장·무게 기준

상품 기준 관리화면 구조 예시

상품	품번	한박스에몇개?	청구무게계수g
예시A	300000	10	300
예시B	500000	15	200

한박스수량은1 이상 정수.청구무게계수는0보다큰g.용량환산과무게는다른단위다.과거RF결과를사람이반영한계수이며이화면에서모델을새로학습하지않는다.

이번자동화화면에서보정한임시값은상품DB에자동저장하지 않는다.어드민이이화면에서명시저장한값만다음작업기본값이된다.바코드·속성·3PL·재고수정은C-1정책대로변경이력에남긴다.

C-4 / DEVELOPMENT SPECIFICATION

상시판매 rule · 대상 상품

상시판매 rule 추가화면 구조 예시

규칙명 *예시 상시판매

3PL *다보내

작성자인증 어드민

대상 품번	상품명	선택
300000	예시상품A	✓
500000	예시상품B	✓

데이터	명세
recurring_rules	id/name/warehouse_id/created_by
recurring_rule_lines	id/rule_id/product_id.동일 규칙 상품 중복 불가.
사용	C-3에서규칙을선택하면해당상품·3PL기준을읽어작업을시작.원본주문서는담당자가선택.
제외	요일스케줄러·정기실행원장·알림감사·자동발송을만들지않음.
삭제	규칙과대상 상품관계를한트랜잭션으로삭제하는안.과거다운로드파일은변경하지않음.

C-4 / DEVELOPMENT SPECIFICATION

어드민 계정 생성·비밀번호 재설정

계정 관리화면 구조 예시

ID	이름	역할	팀	관리
sample_user	예시사용자	요청자	상품기획	비밀번호 재설정
sample_staff	예시물류	물류 담당자	물류	비밀번호 재설정

계정 생성화면 구조 예시

ID *중복없는로그인ID

비밀번호 *초기비밀번호

이름 *표시이름

역할 *요청자 / 물류 담당자 / 물류 어드민

팀 *조직표시

항목	정책
ID	대소문자중복판정은login_id COLLATE NOCASE.형식허용범위는서버에서고정검사.
비밀번호	현재코드기준8~128자검사를기본안으로사용.서버에서salt와해시저장,평문 응답/로그금지.
초기화	어드민이대상ID를확인하고새비밀번호설정.현재비밀번호조회불가.
필드제외	credential_version·must_reset·is_active·actor_session은논리명세에없음.현앱구현필드와구분.
계정생성안내	로그인아래 “계정이 없는 경우 직접 물류팀에게 요청하세요”.셀프회원가입없음.
세션처리	비밀번호변경시기존로그인을어떻게만료할지는정책확인 필요.세션테이블을몰래추가하지 않음.

C-4 / DEVELOPMENT SPECIFICATION

기준 변경 전파·API·데이터

actors

필드/제약	타입	논리 정의
id	TEXT	PRIMARY KEY NOT NULL
login_id	TEXT	COLLATE NOCASE NOT NULL
name	TEXT	NOT NULL
role	TEXT	NOT NULL
team	TEXT	NOT NULL
password_hash	TEXT	NOT NULL
password_salt	TEXT	NOT NULL
created_at	TEXT	NOT NULL
UNIQUE	(login_id)

warehouses

필드/제약	타입	논리 정의
id	TEXT	PRIMARY KEY NOT NULL
name	TEXT	NOT NULL
postal_code	TEXT
address	TEXT	NOT NULL
address_detail	TEXT
contact_name	TEXT
contact_phone	TEXT
memo	TEXT
domestic_base_fee	NUMERIC
domestic_labor_fee	NUMERIC
overseas_labor_fee	NUMERIC
material_fee	NUMERIC
free_item_qty	INTEGER
extra_unit_fee	NUMERIC
extra_fee_cap	NUMERIC
created_by	TEXT	NOT NULL REFERENCES actors(id) ON DELETE RESTRICT
created_at	TEXT	NOT NULL
CHECK	(domestic_base_fee	IS NULL OR domestic_base_fee >= 0)
CHECK	(free_item_qty	IS NULL OR free_item_qty >= 0)

warehouse_shipping_rates

필드/제약	타입	논리 정의
id	TEXT	PRIMARY KEY NOT NULL
warehouse_id	TEXT	NOT NULL REFERENCES warehouses(id) ON DELETE RESTRICT
country_code	TEXT	NOT NULL
weight_from_g	INTEGER	NOT NULL
weight_to_g	INTEGER	NOT NULL
shipping_fee	NUMERIC	NOT NULL
UNIQUE	(warehouse_id,	country_code, weight_from_g)
CHECK	(weight_from_g	>= 0)
CHECK	(weight_to_g	> weight_from_g)
CHECK	(shipping_fee	>= 0)

recurring_rules

필드/제약	타입	논리 정의
id	TEXT	PRIMARY KEY NOT NULL
name	TEXT	NOT NULL
warehouse_id	TEXT	NOT NULL REFERENCES warehouses(id) ON DELETE RESTRICT
created_by	TEXT	NOT NULL REFERENCES actors(id) ON DELETE RESTRICT

recurring_rule_lines

필드/제약	타입	논리 정의
id	TEXT	PRIMARY KEY NOT NULL
rule_id	TEXT	NOT NULL REFERENCES recurring_rules(id) ON DELETE RESTRICT
product_id	TEXT	NOT NULL REFERENCES products(id) ON DELETE RESTRICT
UNIQUE	(rule_id,	product_id)

제안 API	서버 검사
POST/PATCH /warehouses	어드민·이름/주소·참조 관계·기본요금
POST/PATCH /warehouses/:id/rates	어드민·국가·구간양수·겹침·비용
PATCH /products/:id/packing	어드민·수량/무게양수·변경사유
POST/PATCH /recurring-rules	어드민·업체/대상 상품FK·중복
POST /actors · POST /actors/:id/reset-password	어드민·ID중복·해시저장·평문 미반환

3PL주소변경은기존요청의수령주소를자동덮어쓰지않는다.진행중C-3작업은시작기준을표시하고기준변경감지시재계산을안내한다.기존XLSX는사용자파일이므로자동업데이트하지않는다.

C-4 / DEVELOPMENT SPECIFICATION

인수 테스트·기초 데이터·확인 필요

테스트 ID	연결 요구	시나리오	기대 결과
C4-T01	C4-R01	3PL주소변경	ID유지,선택목록갱신,요청수령주소불변
C4-T02	C4-R02	무료수량4,상품5개	1개추가작업비만발생
C4-T03	C4-R02	상한NULL과0비교	무상한과추가비0구분
C4-T04	C4-R03	500/501g매칭	각경계구간에정확히1건
C4-T05	C4-R03	겹친구간저장	저장 차단·기존기준유지
C4-T06	C4-R03	운임없는국가가공	미산정 표시
C4-T07	C4-R04	이번 작업임시무게변경	상품 DB 자동 변경 없음
C4-T08	C4-R05	같은rule상품2번등록	중복 차단
C4-T09	C4-R05	규칙등록후일정대기	자동실행없음
C4-T10	C4-R06	요청자계정생성API호출	403
C4-T11	C4-R06	비밀번호재설정	새해시저장·기존값노출없음
C4-T12	C4-R07	기준변경중자동화재계산	입력파일유지·금액새계산
C4-T13	C4-R08	참조 중3PL삭제	차단·사용중인대상안내

초기데이터는상품품번·현재고·당월요청·다보내/패박의확인된계약요금부터넣는다.실제3PL정산표와세금·부피무게·도서산간추가비의포함여부는담당자확인전임의로채우지않는다.