sam-docs/dev/dev_plans/receiving-management-analysis-plan.md

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

작성일: 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

// 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)

// 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 테이블 (입고)

// 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 테이블 (재고)

// 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)

// 입고 상태
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는 단순 텍스트 필드:

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

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

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

// 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 스킬로 생성되었습니다.