vexplor_dev/docs/plans/transaction-packaging-loading-plan.md

거래 단위 포장재·적재함 추적 시스템 구현 계획

작성일: 2026-05-13 작성자: mhkim@wace.me 선행 적용 대상: COMPANY_7 성격: 신규 도메인 (입고/출고/재고이동 공통)

---

1. 배경

1.1 현재 한계

• pkg_unit / loading_unit 마스터에 포장재·적재함 정의는 등록 가능
• 입고/출고/재고이동 시 "어떤 라인이 어떤 포장재로 어떤 적재함에 담겼는지" 저장하는 트랜잭션 테이블이 없음
• POP 장바구니 UI(InboundCartPage, OutboundCartPage)에서 입력은 받지만 DB 영속화되지 않음

1.2 도입 목표

• 입고/출고/재고이동 등 모든 트랜잭션에서 포장재·적재함 사용 내역을 영속화
• 박스(라벨) 단위 개체 추적 — 부분 출고, LOT 분리, 유통기한, 적재함 이동을 박스 단위로 관리
• 신규 트랜잭션 영역이 추가되어도 DDL 변경 없이 확장 (polymorphic source_type + source_id 패턴)

---

2. 현황 분석

2.1 기존 마스터 테이블 (재사용)

테이블	역할
pkg_unit	포장재 마스터 (BOX-L, BOX-M 등)
pkg_unit_item	포장재-품목 매핑
loading_unit	적재함 마스터 (LU-PAL, LU-CRT 등)
loading_unit_pkg	적재함-포장재 매핑

2.2 신규 테이블 (이 계획서 범위)

테이블	역할	카디널리티
transaction_loading	적재함 사용 인스턴스	작업 헤더당 N건 (loading_seq 로 동종 적재함 구분)
transaction_packaging	박스(라벨) 단위 포장 사용	박스 1개 = row 1개

2.3 영향 받는 기존 테이블

테이블	영향
inbound_detail	컬럼 변경 없음. 컨트롤러에서 패키징 분해 로직 추가만
outbound_mng	동일
inventory_stock	유지 — 옵션 1(이중 관리), 트랜잭션 단위로 동시 갱신
inventory_history	유지 — 품목 단위 이력만 기록 (박스 단위 이력은 Phase 3 의 별도 테이블로)

---

3. 핵심 설계 결정

항목	결정	근거
박스 단위 모델	박스 1개 = transaction_packaging row 1개	부분 출고/LOT/유통기한을 박스별로 독립 관리하기 위해
pkg_count 컬럼	삭제 (항상 1)	박스 1개 = row 1개라 불필요
quantity 의미	박스 1개에 실제 담긴 수량	잔량 박스도 같은 모델로 자연 표현 (예: 마지막 박스 quantity=30)
라벨 형식	{문서번호}-P{4자리} (예: INB-2026-001-P0001)	단순/가독성/문서 추적 용이
라벨 UNIQUE	(company_code, package_label)	회사 단위 유일
라벨 동시성	입고 트랜잭션 내 SELECT MAX(seq)+1 + UNIQUE 제약 retry	별도 sequence 객체 불필요
적재함 없는 입고	loading_id NULL 허용	LU-DIRECT 가상 적재함 미도입 (마스터 오염 방지)
적재함 인스턴스 구분	loading_code + loading_seq 조합	같은 종류 적재함을 한 작업에 여러 개 따로 사용하는 케이스
부분 출고	quantity UPDATE + 로그	라벨 분할(-S1) 미사용 — 형식 폭주 방지, 박스 라벨 안정성
출고 처리	row 의 status='SHIPPED' 변경	Phase 1 단순. 이력 추적은 Phase 3 의 transaction_package_movement 로
재고 동기화	옵션 1 (이중 관리)	기존 화면 영향 최소. 같은 트랜잭션 내 inventory_stock + transaction_packaging 동시 갱신
잔량(미포장)	별도 처리 안 함 (마지막 박스 quantity 가 작은 형태로 흡수)	pkg_code=NULL 행/is_remainder 플래그 불필요
포장 중첩	미지원 (loading_id 1단계만)	1차 범위 단순화
바코드 인쇄	1차는 텍스트 라벨 / 2차 ZPL 연동	출시 범위 축소

---

4. 테이블 스키마

4.1 transaction_loading — 적재함 사용 인스턴스

컬럼	타입	설명
id	VARCHAR(500) PK	UUID
company_code	VARCHAR(500) NOT NULL	멀티테넌시
source_type	VARCHAR(500) NOT NULL	'inbound', 'outbound', 'inventory_move' 등 (헤더 레벨)
source_doc_id	VARCHAR(500) NOT NULL	inbound_mng.id / outbound_mng.id 등 헤더 ID
loading_code	VARCHAR(500) NOT NULL	loading_unit.loading_code
loading_seq	INT	같은 적재함 종류를 한 작업에서 여러 개 쓸 때 구분 (1, 2, 3...)
loading_name	VARCHAR(500)	마스터 스냅샷
memo	VARCHAR(500)	비고
status	VARCHAR(500)	(예약) 'ACTIVE'/'CLOSED' 등
writer	VARCHAR(500)
created_by	VARCHAR(500)
created_date	TIMESTAMP DEFAULT NOW()
updated_date	TIMESTAMP DEFAULT NOW()

인덱스:

• (company_code, source_type, source_doc_id)
• (company_code, loading_code)

4.2 transaction_packaging — 박스(라벨) 단위 포장 사용

컬럼	타입	설명
id	VARCHAR(500) PK	UUID
company_code	VARCHAR(500) NOT NULL	멀티테넌시
source_type	VARCHAR(500) NOT NULL	'inbound_detail', 'outbound_detail', 'inventory_move_detail' 등 (라인 레벨)
source_id	VARCHAR(500) NOT NULL	디테일 라인의 id
package_label	VARCHAR(500) NOT NULL	라벨 (예: INB-2026-001-P0001)
pkg_code	VARCHAR(500) NOT NULL	pkg_unit.pkg_code
quantity	NUMERIC(18,4) NOT NULL	이 박스 1개에 실제 담긴 수량
loading_id	VARCHAR(500)	transaction_loading.id — NULL 허용 (적재함 없는 입고)
seq_no	INT	라인 내 박스 순번 (1, 2, 3, ...)
status	VARCHAR(500) DEFAULT 'STORED'	STORED / SHIPPED / SCRAPPED / DAMAGED
lot_no	VARCHAR(500)	로트번호 (옵션)
expire_date	DATE	유통기한 (옵션)
writer	VARCHAR(500)
created_by	VARCHAR(500)
created_date	TIMESTAMP DEFAULT NOW()
updated_date	TIMESTAMP DEFAULT NOW()

제약:

• UNIQUE (company_code, package_label)

인덱스:

• (company_code, source_type, source_id)
• (company_code, loading_id)
• (company_code, package_label)
• (company_code, status)

---

5. 입고/출고/재고이동 흐름

5.1 입고 등록 (자동 분해)

사용자 입력 (집계형 UX 유지)

• 품목 라인별 입고 수량
• 포장재 + 단위당 수량 + 박스 개수
• 적재함 선택 (없으면 NULL)

백엔드 처리 (단일 트랜잭션)

1. inbound_mng / inbound_detail INSERT (기존 로직)
2. 적재함 신규 인스턴스면 transaction_loading INSERT → loading_id 획득
3. 라인 수량을 박스 단위로 분해 → transaction_packaging N개 INSERT
   • 예: 입고 1030 / BOX-50 → 20 row (quantity=50) + 1 row (quantity=30) = 21 row
4. 라벨 자동 발번: {문서번호}-P{4자리} 시퀀스
5. inventory_stock += 총합, inventory_history INSERT (기존 흐름 그대로)

응답: 발번된 라벨 목록 (인쇄 대상)

5.2 출고 (Phase 2 범위)

1. 출고 요청 (수주/지시) → 품목 + 수량 입력
2. 라벨 선택 (자동 FEFO/FIFO / 수동 / 바코드 스캔)
3. 박스 전체 출고:
   • 해당 row status='SHIPPED', updated_date=NOW()
4. 박스 부분 출고 (예: 50 박스 중 20개만 나감):
   • quantity 50→30 UPDATE
   • 라벨/박스는 그대로 유지 (분할 없음)
   • inventory_history 에 '출고' 한 줄 (품목 단위)
5. inventory_stock 차감 (기존 흐름)

5.3 재고이동 (Phase 2)

• 박스의 loading_id 만 새 인스턴스로 UPDATE
• inventory_stock 의 창고/위치 컬럼 동기화

---

6. API 명세 (Phase 1 범위)

메서드	경로	역할
POST	/api/packaging/labels/generate	입고 시 라벨 자동 발번 (입고 컨트롤러 내부 호출)
GET	/api/packaging	라벨 조회 (viewMode=summary 집계 / detail 박스 목록)
GET	/api/packaging/:label	라벨 1건 상세
GET	/api/loading	적재함 인스턴스 조회

수정 API:

• POST /api/inbound — 자동 분해 로직 추가 (단일 트랜잭션 안에서 transaction_packaging/loading INSERT)

Phase 2 추가 예정:

• PATCH /api/packaging/:id/status
• PATCH /api/packaging/:id/move

---

7. 프론트엔드 영향

7.1 적용 범위 (1차)

• frontend/app/(main)/COMPANY_7/pop/_components/inbound/*
• frontend/app/(main)/COMPANY_7/logistics/packaging/page.tsx (조회)
• 검증 완료 후 COMPANY_8/9/16/28/29/30 등으로 확대

7.2 수정 대상 파일

파일	변경 내용
pop/_components/inbound/InboundCartPage.tsx	백엔드 응답으로 받은 라벨 목록 표시 영역 추가
pop/_components/inbound/NumberPadModal.tsx	동작 변경 없음 (UI 그대로, 백엔드가 분해)
logistics/packaging/page.tsx	라벨 조회 뷰 추가 (집계/상세 토글)
lib/api/packaging.ts	신규 엔드포인트 클라이언트 추가

---

8. 단계별 로드맵

Phase 1 — MVP (이번 계획서 범위)

• DDL 마이그레이션 적용
• 백엔드 packagingService.ts 신규 (분해/발번)
• receivingController.ts 에 패키징 INSERT 통합
• 라벨 조회 API
• 프론트 라벨 결과 표시
• COMPANY_7 검증

Phase 2 — 운영 안정화

• 출고 시 라벨 선택 UI (자동/수동/스캔)
• 부분 출고 quantity UPDATE 로직
• 상태/위치 변경 API
• 재고이동에서 박스 단위 이동

Phase 3 — 고도화

• transaction_package_movement 이력 테이블
• 바코드 인쇄 (ZPL)
• 스캐너 입력 연동
• FEFO/FIFO 자동 선택

---

9. 위험 및 완화책

위험	완화책
inventory_stock 과 transaction_packaging 정합성 불일치	모든 변경을 단일 DB 트랜잭션으로 묶음. 서비스 레이어에 단일 진입점 강제
동시 입고 시 라벨 시퀀스 충돌	UNIQUE 제약 + 트랜잭션 내 retry
적재함 NULL 허용으로 쿼리 분기 증가	LEFT JOIN transaction_loading 패턴으로 통일
COMPANY_7 외 회사 확대 시 코드 중복	공통 라이브러리화 후 회사별 페이지에서 import

---

10. 기존 데이터 처리

• 신규 입고부터만 적용 — 기존 inbound 데이터는 마이그레이션하지 않음
• 운영 중 변경된 입고를 박스 단위로 풀어내는 것은 입력 의도가 불명확해 데이터 왜곡 위험
• 필요 시 Phase 3 에 별도 마이그레이션 스크립트 작성 검토

---

11. 검증 계획

11.1 단위

• 박스 분해 함수: 1030 / 50 → 21 row (20×50, 1×30)
• 라벨 발번: 동시 호출 시 충돌 없이 순차 발번
• 트랜잭션 롤백: 한쪽 실패 시 inventory_stock/transaction_packaging 모두 원복

11.2 통합 (COMPANY_7)

• POP 입고 장바구니 → 등록 → 라벨 21개 발번 → 조회 화면에서 21개 표시 확인
• 잔량 케이스 (1030/50=21박스): 마지막 박스 quantity=30 표시 확인
• 같은 종류 적재함 2개 따로 사용: loading_seq 1, 2 로 구분 확인
• 적재함 없는 입고: loading_id=NULL 정상 저장 확인

11.3 회귀

• 기존 입고/출고/재고이동 화면 동작 유지
• 재고현황 화면 (inventory_stock 기반) 수치 변화 없음

---

12. 마이그레이션 파일

• 위치: db/migrations/add_transaction_packaging_loading.sql
• 양식: 기존 add_packaging_to_pop_production.sql 패턴 준수 (헤더 주석 / 검증 쿼리 / 롤백 섹션)