sam-docs/plans/item-inventory-management-plan.md

품목 재고 관리 체계 설계

작성일: 2026-02-12 상태: 설계 확정, 단계별 구현 예정

1. 배경

문제

• 5130(레거시)에서 관리하던 "내화실" 등 품목이 SAM에 제대로 반영되지 않음
• 기존 item_type(FG/PT/SM/RM/CS) 분류만으로는 다양한 관리 방식을 표현할 수 없음
• 소모품 중 LOT 관리가 필요한 품목과 불필요한 품목 구분 불가
• 자체생산 재고품(중간재) 개념 부재

현재 item_type 체계

코드	의미	비고
FG	완제품 (Finished Goods)	출하 대상
PT	부품 (Parts)	BOM 구성
SM	부자재 (Sub Materials)	구매품
RM	원자재 (Raw Materials)	구매품, LOT 관리
CS	소모품 (Consumables)	단순 소진

2. 설계: items.options JSON 기반 관리 속성

핵심 원칙

• 컬럼 추가 금지: FK/조인키만 컬럼 추가, 나머지는 JSON (멀티테넌시 원칙)
• item_type은 "뭐냐", **options는 "어떻게 관리하냐"**를 구분

options 필드 정의

키	타입	값	설명
lot_managed	boolean	true/false	LOT 번호 추적 여부
consumption_method	string	auto/manual/none	소진 처리 방식
production_source	string	purchased/self_produced/both	조달 구분
input_tracking	boolean	true/false	원자재 투입 추적 여부
material	string	-	재질 정보 (선택)

필드 상세

lot_managed

• true: 입고 시 LOT 번호 필수, stock_lots 테이블에 LOT별 수량 추적
• false: LOT 없이 총량만 관리

consumption_method

• auto: 생산 완료 시 BOM 기준 자동 차감
• manual: 사용자가 직접 수량 입력하여 소진 처리
• none: 소진 추적 안 함 (완제품 등)

production_source

• purchased: 구매 입고만 (원자재, 부자재, 소모품)
• self_produced: 자체 생산으로 입고 (중간재, 반제품)
• both: 구매 + 자체 생산 모두 가능

input_tracking

• true: 생산 시 BOM 기반 원자재 투입 기록
• false: 잔재/스크랩 활용 생산 → 투입 추적 불가, 산출물 입고만 기록

3. 품목 유형별 적용

유형 분류표

유형	예시	item_type	lot	consumption	source	input_tracking
구매 소모품 (LOT)	내화실	SM	true	manual	purchased	-
구매 소모품 (비LOT)	장갑, 테이프	CS	false	manual	purchased	-
원자재	실리카원단, EGI코일	RM	true	auto	purchased	-
일반 자체생산	슬랫, 절곡물	PT	true	auto	self_produced	true
잔재 활용 생산	조인트바	PT	true	auto	self_produced	false
완제품	방화스크린	FG	true	none	self_produced	true

유형별 처리 흐름

구매 소모품 - LOT 관리 (내화실)

납품 → 수입검사 → 검사 합격
  → stock_transactions(IN) + LOT 생성
  → 작업일지에 사용 LOT 기록 (추적용)
  → 수동 소진 처리: 사용자가 수량 입력 → stock_transactions(OUT, manual_consumption)

구매 소모품 - 비LOT (장갑, 테이프)

구매 입고 → stock_transactions(IN), LOT 없음
  → 수동 소진 처리: 수량 입력 → stock_transactions(OUT, manual_consumption)

일반 자체생산 (슬랫, 절곡물)

작업지시 시작
  → BOM 기준 원자재 자동 차감: stock_transactions(OUT, work_order_input)
  → 생산 완료
  → 산출물 입고: stock_transactions(IN, production_output) + LOT 생성
  → 상위 조립 시 BOM 기준 자동 차감

잔재 활용 생산 (조인트바)

다른 공정 잔재/스크랩 활용
  → 원자재 투입 기록 없음 (이미 다른 공정에서 차감됨)
  → 생산 완료
  → 산출물 입고만: stock_transactions(IN, production_output) + LOT 생성
  → 상위 조립 시 BOM 기준 자동 차감

4. 내화실 품목 업데이트 (완료)

변경 내역

필드	변경 전	변경 후
code	80019	내화실-WY-MA12
name	실	내화실
unit	m	콘
attributes.spec	(비어있음)	WY-MA12
options	null	아래 참조

options 값

{
  "lot_managed": true,
  "consumption_method": "manual",
  "production_source": "purchased",
  "material": "SUS316L + Para aramid"
}

배포

• 시더: api/database/seeders/data/kyungdong/items.json (커밋 완료)
• SQL: docs/deploys/item-naehwasil-update-20260212.sql

5. 구현 로드맵

Phase 1: 품목 마스터 정비 (현재)

• options 체계 설계
• 내화실 품목 데이터 업데이트
• 슬랫, 절곡물, 조인트바 등 자체생산품 options 설정
• 기존 품목 일괄 options 매핑

Phase 2: 수동 소진 처리

• API: 소모품 사용 처리 엔드포인트 (POST /stocks/{id}/consume)
• React: 소모품 사용 처리 화면
• stock_transactions reason에 manual_consumption 추가

Phase 3: 자체생산품 입고 연동

• 작업지시 완료 시 산출물 자동 입고 로직
• stock_transactions reason에 production_output 추가
• 작업지시번호 기반 LOT 자동 생성 규칙
• input_tracking=false인 경우 투입 차감 스킵 로직

Phase 4: BOM 기반 자동 차감

• consumption_method=auto인 품목 자동 차감 로직
• 작업지시 완료 → BOM 순회 → 해당 품목 stock_transactions(OUT)
• 부족 재고 경고 알림

6. 참고

관련 파일

• Item 모델: api/app/Models/Items/Item.php
• Stock 모델: api/app/Models/Tenants/Stock.php
• StockTransaction 모델: api/app/Models/Tenants/StockTransaction.php
• StockLot 모델: api/app/Models/Tenants/StockLot.php
• 시더 데이터: api/database/seeders/data/kyungdong/items.json

5130 참고 파일

• 내화실 수입검사: 5130/instock/i_fireproofWire.php
• 스크린 작업일지: 5130/output/viewScreenWork.php
• LOT 조회: 5130/output/fetch_lot.php