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 값
```json
{
  "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: 품목 마스터 정비 (현재)
- [x] options 체계 설계
- [x] 내화실 품목 데이터 업데이트
- [ ] 슬랫, 절곡물, 조인트바 등 자체생산품 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`