SamProject/sam-docs
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f4ae2ee53a81c2c07e1bee037001908cb54e13bf
sam-docs/plans/receiving-management-analysis-plan.md
권혁성 0cb8a3af22 docs: 견적 V2 변경 이력 및 계획 문서 추가 
- 견적 V2 API 연동 변경 이력 (4개 파일)
- 입고관리 분석 계획
- 재고 통합 계획

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 22:12:17 +09:00

452 lines
17 KiB
Markdown
Raw Blame History

# 입고관리 시스템 분석 및 개발 계획
> **작성일**: 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 스킬로 생성되었습니다.*
Reference in New Issue View Git Blame Copy Permalink