# 입고관리 시스템 분석 및 개발 계획

> **작성일**: 2026-01-26
> **목적**: 입고관리 시스템 현황 분석 및 미완성 기능 개발
> **기준 문서**: react/src/components/material/ReceivingManagement/, api/app/Services/ReceivingService.php
> **상태**: 🔄 분석 완료

---

## 📍 현재 진행 상태

| 항목 | 내용 |
|------|------|
| **마지막 완료 작업** | 시스템 분석 완료 |
| **다음 작업** | 미완성 기능 식별 및 개발 계획 수립 |
| **진행률** | 분석 완료 (0/N 개발) |
| **마지막 업데이트** | 2026-01-26 |

---

## 1. 시스템 개요

### 1.1 상태 흐름 (Status Flow)

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         입고관리 상태 흐름도                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  발주완료 ──→ 배송중 ──→ 검사대기 ──→ 입고대기 ──→ 입고완료             │
│  (order_     (shipping)  (inspection_  (receiving_   (completed)        │
│   completed)              pending)      pending)                         │
│                                                                          │
│  ┌──────────┐                                                           │
│  │ 입고처리 │ ← 발주완료/배송중 상태에서 바로 입고처리 가능              │
│  └────┬─────┘                                                            │
│       ↓                                                                  │
│  ┌──────────┐                                                           │
│  │ 재고연동 │ → Stock + StockLot 생성 (FIFO)                           │
│  └──────────┘                                                           │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

### 1.2 핵심 연동

```
입고처리(process) 완료 시:
├── Receiving.status → 'completed'
├── StockService.increaseFromReceiving(receiving)
│   ├── Stock 조회/생성
│   ├── StockLot 생성 (FIFO 순서)
│   └── 감사 로그 기록
└── 재고 현황 자동 갱신
```

---

## 2. 구현 현황 분석

### 2.1 API 계층 (✅ 완성도 높음)

| 엔드포인트 | 메서드 | 컨트롤러 | 서비스 | 상태 |
|-----------|--------|---------|--------|:----:|
| `/api/v1/receivings` | GET | index() | index() | ✅ |
| `/api/v1/receivings/stats` | GET | stats() | stats() | ✅ |
| `/api/v1/receivings/{id}` | GET | show() | show() | ✅ |
| `/api/v1/receivings` | POST | store() | store() | ✅ |
| `/api/v1/receivings/{id}` | PUT | update() | update() | ✅ |
| `/api/v1/receivings/{id}` | DELETE | destroy() | destroy() | ✅ |
| `/api/v1/receivings/{id}/process` | POST | process() | process() | ✅ |

**API 파일:**
- `api/app/Http/Controllers/Api/V1/ReceivingController.php`
- `api/app/Services/ReceivingService.php`
- `api/app/Models/Tenants/Receiving.php`
- `api/app/Http/Requests/V1/Receiving/*.php`

### 2.2 Frontend 계층 (✅ 대부분 완성)

| 컴포넌트 | 파일명 | 기능 | API 연동 | 상태 |
|---------|--------|------|:--------:|:----:|
| 입고 목록 | `ReceivingList.tsx` | 목록 조회, 통계, 필터링 | ✅ | ✅ |
| 입고 상세 | `ReceivingDetail.tsx` | 상세 보기, 상태별 액션 | ✅ | ✅ |
| 입고 처리 | `ReceivingProcessDialog.tsx` | 입고LOT, 수량 입력 | ✅ | ✅ |
| 입고증 | `ReceivingReceiptDialog.tsx` | 입고증 출력 | - | ✅ |
| **검사 등록** | `InspectionCreate.tsx` | IQC 검사 등록 | ❌ TODO | ⚠️ |
| 성공 다이얼로그 | `SuccessDialog.tsx` | 완료 알림 | - | ✅ |

**Frontend 파일:**
- `react/src/components/material/ReceivingManagement/`
  - `actions.ts` - API 호출 함수
  - `types.ts` - 타입 정의
  - `ReceivingList.tsx` - 목록 페이지
  - `ReceivingDetail.tsx` - 상세 페이지
  - `ReceivingProcessDialog.tsx` - 입고처리 다이얼로그
  - `InspectionCreate.tsx` - 검사 등록 (⚠️ API 미연동)

### 2.3 재고 연동 (✅ 완성)

| 기능 | 메서드 | 설명 | 상태 |
|------|--------|------|:----:|
| 입고 시 재고 증가 | `increaseFromReceiving()` | Stock/StockLot 생성 | ✅ |
| FIFO 재고 차감 | `decreaseFIFO()` | 선입선출 기반 차감 | ✅ |
| 재고 예약 | `reserve()` | 수주 확정 시 예약 | ✅ |
| 예약 해제 | `releaseReservation()` | 수주 취소 시 해제 | ✅ |
| 출하 재고 차감 | `decreaseForShipment()` | 출하 시 차감 | ✅ |

**재고 파일:**
- `api/app/Services/StockService.php`
- `api/app/Models/Tenants/Stock.php`
- `api/app/Models/Tenants/StockLot.php`

---

## 3. 미완성 기능 (개발 필요)

### 3.1 🔴 검사 등록 API 미연동

**현재 상태:** `InspectionCreate.tsx` Line 159-176
```typescript
// TODO: API 호출
console.log('검사 저장:', {
  targetId: selectedTargetId,
  inspectionDate,
  inspector,
  lotNo,
  items: inspectionItems,
  opinion,
});

setShowSuccess(true);
```

**필요 작업:**
1. **API 엔드포인트 확인/생성**: `/api/v1/receivings/{id}/inspection` 또는 `/api/v1/inspections`
2. **Backend 서비스**: 검사 저장 로직 (상태 변경 포함)
3. **Frontend 연동**: API 호출 및 에러 처리

### 3.2 ⚠️ 검사 → 입고대기 상태 전환 로직

**현재 흐름 문제:**
```
검사대기(inspection_pending) → [검사 등록] → ???
```

**필요 사항:**
- 검사 완료 시 상태를 `receiving_pending`으로 변경
- 검사 결과 저장 테이블 필요 (있는지 확인 필요)

### 3.3 ⏳ 검사 이력 조회 기능 (추후)

- 검사 결과 조회 화면
- 검사 이력 관리

---

## 4. 상태별 화면 및 버튼 매핑

### 4.1 상태별 UI 구성

| 상태 | 한글명 | 스타일 | 가능한 액션 |
|------|--------|--------|-------------|
| `order_completed` | 발주완료 | gray | 목록, **입고처리** |
| `shipping` | 배송중 | blue | 목록, **입고처리** |
| `inspection_pending` | 검사대기 | orange | 입고증, 목록, **검사등록** |
| `receiving_pending` | 입고대기 | yellow | 목록 |
| `completed` | 입고완료 | green | 입고증, 목록 |

### 4.2 상세 페이지 버튼 로직 (ReceivingDetail.tsx)

```typescript
// Line 126-130
const showInspectionButton = detail.status === 'inspection_pending';
const showReceivingProcessButton =
  detail.status === 'order_completed' || detail.status === 'shipping';
const showReceiptButton =
  detail.status === 'inspection_pending' || detail.status === 'completed';
```

---

## 5. 데이터 구조

### 5.1 Receiving 테이블 (입고)

```php
// api/app/Models/Tenants/Receiving.php
protected $fillable = [
    'tenant_id',
    'receiving_number',    // 입고번호 (자동생성: RV + YYYYMMDD + 4자리)
    'order_no',            // 발주번호
    'order_date',          // 발주일자
    'item_id',             // 품목ID (Stock 연동용)
    'item_code',           // 품목코드
    'item_name',           // 품목명
    'specification',       // 규격
    'supplier',            // 공급업체
    'order_qty',           // 발주수량
    'order_unit',          // 발주단위
    'due_date',            // 납기일
    'receiving_qty',       // 입고수량
    'receiving_date',      // 입고일자
    'lot_no',              // LOT번호
    'supplier_lot',        // 공급업체LOT
    'receiving_location',  // 입고위치 (선택)
    'receiving_manager',   // 입고담당
    'status',              // 상태
    'remark',              // 비고
    'created_by',
    'updated_by',
    'deleted_by',
];
```

### 5.2 Stock/StockLot 테이블 (재고)

```php
// Stock: 품목별 재고 요약
- item_id, stock_qty, available_qty, reserved_qty, lot_count, status

// StockLot: LOT별 재고 상세
- stock_id, lot_no, fifo_order, receipt_date, qty, available_qty
- supplier, supplier_lot, po_number, location, receiving_id
```

### 5.3 Frontend 타입 (types.ts)

```typescript
// 입고 상태
type ReceivingStatus =
  | 'order_completed' | 'shipping' | 'inspection_pending'
  | 'receiving_pending' | 'completed';

// 입고 목록 아이템
interface ReceivingItem { id, orderNo, itemCode, itemName, supplier, orderQty, orderUnit, receivingQty?, lotNo?, status }

// 입고 상세
interface ReceivingDetail { ...ReceivingItem, orderDate?, specification?, dueDate?, receivingDate?, receivingLot?, supplierLot?, receivingLocation?, receivingManager? }

// 입고처리 폼
interface ReceivingProcessFormData { receivingLot, supplierLot?, receivingQty, receivingLocation?, remark? }

// 검사 폼
interface InspectionFormData { targetId, inspectionDate, inspector, lotNo, items: InspectionCheckItem[], opinion? }
```

---

## 6. API 엔드포인트 상세

### 6.1 입고 목록 조회

```
GET /api/v1/receivings
Query: page, per_page, status, search, start_date, end_date, sort_by, sort_dir
Response: { success, message, data: { data[], current_page, last_page, per_page, total } }
```

### 6.2 입고 통계 조회

```
GET /api/v1/receivings/stats
Response: { success, data: { receiving_pending_count, shipping_count, inspection_pending_count, today_receiving_count } }
```

### 6.3 입고처리 (상태 변경 + 재고 연동)

```
POST /api/v1/receivings/{id}/process
Body: { receiving_qty*, lot_no, supplier_lot, receiving_location, remark }
Effect: status → 'completed', Stock + StockLot 생성
```

---

## 7. 개발 우선순위

### Phase 1: 검사 기능 완성 (⚠️ 필수)

| # | 작업 항목 | 예상 범위 | 상태 |
|---|----------|----------|:----:|
| 1.1 | 검사 API 확인/생성 | API | ⏳ |
| 1.2 | InspectionCreate API 연동 | Frontend | ⏳ |
| 1.3 | 검사 → 입고대기 상태 전환 | API | ⏳ |

### Phase 2: 검사 이력 관리 (선택)

| # | 작업 항목 | 예상 범위 | 상태 |
|---|----------|----------|:----:|
| 2.1 | 검사 이력 조회 API | API | ⏳ |
| 2.2 | 검사 이력 화면 | Frontend | ⏳ |

### Phase 3: 개선사항 (후순위)

| # | 작업 항목 | 예상 범위 | 상태 |
|---|----------|----------|:----:|
| 3.1 | 입고증 PDF 다운로드 | Frontend | ⏳ |
| 3.2 | 일괄 입고처리 | API + Frontend | ⏳ |

---

## 8. 참고 파일 경로

### API (Laravel)
```
api/
├── app/Http/Controllers/Api/V1/ReceivingController.php
├── app/Services/ReceivingService.php
├── app/Services/StockService.php
├── app/Models/Tenants/Receiving.php
├── app/Models/Tenants/Stock.php
├── app/Models/Tenants/StockLot.php
├── app/Http/Requests/V1/Receiving/
│   ├── StoreReceivingRequest.php
│   ├── UpdateReceivingRequest.php
│   └── ProcessReceivingRequest.php
├── app/Swagger/v1/ReceivingApi.php
└── routes/api.php (Line 737-744)
```

### Frontend (React/Next.js)
```
react/src/
├── components/material/ReceivingManagement/
│   ├── actions.ts              # API 호출
│   ├── types.ts                # 타입 정의
│   ├── ReceivingList.tsx       # 목록 페이지
│   ├── ReceivingDetail.tsx     # 상세 페이지
│   ├── ReceivingProcessDialog.tsx  # 입고처리
│   ├── InspectionCreate.tsx    # 검사 등록 (⚠️ TODO)
│   ├── SuccessDialog.tsx       # 성공 알림
│   ├── ReceivingReceiptDialog.tsx  # 입고증
│   ├── ReceivingReceiptContent.tsx # 입고증 내용
│   ├── receivingConfig.ts      # 상세 페이지 설정
│   └── inspectionConfig.ts     # 검사 페이지 설정
└── app/[locale]/(protected)/material/receiving-management/
    ├── page.tsx                # 목록 라우트
    ├── [id]/page.tsx           # 상세 라우트
    └── inspection/page.tsx     # 검사 라우트
```

---

## 9. 자기완결성 점검 결과

### 9.1 체크리스트 검증

| # | 검증 항목 | 상태 | 비고 |
|---|----------|:----:|------|
| 1 | 작업 목적이 명확한가? | ✅ | 입고관리 현황 분석 및 미완성 기능 식별 |
| 2 | 성공 기준이 정의되어 있는가? | ✅ | 검사 API 연동 완료 |
| 3 | 작업 범위가 구체적인가? | ✅ | Phase별 작업 항목 정의 |
| 4 | 의존성이 명시되어 있는가? | ✅ | Stock 연동, API 구조 |
| 5 | 참고 파일 경로가 정확한가? | ✅ | 전체 파일 경로 명시 |
| 6 | 단계별 절차가 실행 가능한가? | ✅ | Phase별 작업 순서 |
| 7 | 검증 방법이 명시되어 있는가? | ✅ | API 연동 테스트 |
| 8 | 모호한 표현이 없는가? | ✅ | 구체적 코드 라인 명시 |

### 9.2 새 세션 시뮬레이션 테스트

| 질문 | 답변 가능 | 참조 섹션 |
|------|:--------:|----------|
| Q1. 현재 시스템 상태는? | ✅ | 2. 구현 현황 분석 |
| Q2. 미완성 기능은? | ✅ | 3. 미완성 기능 |
| Q3. 어떤 파일을 수정해야 하는가? | ✅ | 8. 참고 파일 경로 |
| Q4. 상태 흐름은? | ✅ | 1.1 상태 흐름도 |
| Q5. 재고 연동 방식은? | ✅ | 2.3 재고 연동 |

---

## 10. 발주-입고 시스템 연결 분석 🆕

### 10.1 관련 시스템 현황

| 시스템 | 역할 | 모델/서비스 | Receiving 연결 |
|--------|------|-------------|:--------------:|
| **Purchase** (매입관리) | 회계/재무 - 매입 전표 관리 | `Purchase`, `PurchaseService` | ❌ 없음 |
| **Order** (수주관리) | 영업 - 고객 수주 관리 | `Order`, `OrderService` | ❌ 없음 |
| **Receiving** (입고관리) | 물류 - 입고 처리 | `Receiving`, `ReceivingService` | 독립 운영 |

### 10.2 핵심 발견: 발주 시스템 부재

**`Receiving.order_no`는 단순 텍스트 필드:**

```php
// api/app/Models/Tenants/Receiving.php
protected $fillable = [
    'order_no',        // ← FK 아님, 단순 문자열
    'order_date',
    // ...
];

// ❌ Order 모델과 belongsTo 관계 없음
```

**"발주완료(order_completed)" 상태는 수동 설정:**

```php
// api/app/Services/ReceivingService.php:134
$receiving->status = $data['status'] ?? 'order_completed';
```

→ 입고 레코드 생성 시 초기 상태로 설정됨

### 10.3 Purchase vs Receiving 비교

| 구분 | Purchase (매입) | Receiving (입고) |
|------|----------------|------------------|
| **목적** | 재무/회계 전표 | 물류/재고 관리 |
| **상태** | `draft` → `confirmed` | 5단계 상태 흐름 |
| **데이터** | 금액, 세금, 거래처 | 수량, LOT, 위치 |
| **연결** | Client (거래처) | Item (품목), Stock (재고) |
| **번호 형식** | `PU20260126XXXX` | `RV20260126XXXX` |

### 10.4 개발 방향 선택지

| 옵션 | 설명 | 장점 | 단점 | 작업량 |
|------|------|------|------|:------:|
| **A) 발주 시스템 신규 개발** | PurchaseOrder 모델 생성, Receiving FK 연결 | 완전한 구매 프로세스 | 대규모 개발 필요 | 🔴 |
| **B) Order 확장** | 기존 Order에 자재 발주 기능 추가 | 기존 시스템 활용 | Order는 수주 목적 | 🟡 |
| **C) 현재 구조 유지** | Receiving에서 직접 입력 | 변경 없음 | 발주 추적 불가 | 🟢 |

### 10.5 권장 방향

```
┌─────────────────────────────────────────────────────────────────────────┐
│  💡 단기: 옵션 C (현재 구조 유지)                                         │
│                                                                          │
│  - 검사 기능 완성 우선 (Phase 1)                                          │
│  - 발주 시스템은 별도 기획 후 개발                                         │
│                                                                          │
│  📋 장기: 발주 시스템 필요 시                                             │
│                                                                          │
│  발주요청 → 발주승인 → 발주서 발행 → [Receiving 자동 생성]                 │
│  (PurchaseOrder)           ↓                                             │
│                      order_completed 상태로 입고 대기                      │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 11. 변경 이력

| 날짜 | 항목 | 변경 내용 | 파일 |
|------|------|----------|------|
| 2026-01-26 | 분석 | 시스템 분석 및 문서 작성 | - |
| 2026-01-26 | 분석 | 발주-입고 시스템 연결 분석 추가 (섹션 10) | PurchaseService, Purchase 모델 |

---

*이 문서는 /plan 스킬로 생성되었습니다.*