From 704807e07de99b9448fa4a2f7eb078157605e79b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Wed, 18 Mar 2026 13:22:56 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[receiving]=20=ED=94=84=EB=A1=A0?= =?UTF-8?q?=ED=8A=B8=EC=97=94=EB=93=9C=20=EC=A0=84=EB=8B=AC=EC=9A=A9=20?= =?UTF-8?q?=ED=92=88=EB=AA=A9=EA=B2=80=EC=83=89=20=EB=B2=84=EA=B7=B8=20?= =?UTF-8?q?=EC=88=98=EC=A0=95=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 문제현상, 원인, 수정내용, 확인 체크리스트 포함 - INDEX.md 등록 --- INDEX.md | 1 + .../receiving-item-search-fix-20260318.md | 138 ++++++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 frontend/api-specs/receiving-item-search-fix-20260318.md diff --git a/INDEX.md b/INDEX.md index 1efc45e..ce9046d 100644 --- a/INDEX.md +++ b/INDEX.md @@ -286,6 +286,7 @@ DB 도메인별: | [vehicle-api.md](frontend/api-specs/vehicle-api.md) | 차량관리 API 명세 (20개 엔드포인트: 차량목록, 차량일지, 정비이력, 사진) | | [stock-production-api.md](frontend/api-specs/stock-production-api.md) | 재고생산관리 API 명세 (기존 수주 API + STOCK 타입) | | [stock-receiving-changes-20260317.md](frontend/api-specs/stock-receiving-changes-20260317.md) | 입고관리/재고현황 변경사항 (로트번호 자동채번, 재고 조정 이동, API 스펙) | +| [receiving-item-search-fix-20260318.md](frontend/api-specs/receiving-item-search-fix-20260318.md) | 입고등록 품목검색 버그 수정 (per_page/itemType 파라미터, 프론트엔드 전달용) | | [ai-token-usage-api.md](frontend/api-specs/ai-token-usage-api.md) | AI 토큰사용량 API 명세 (2개 엔드포인트 + 화면 가이드 + 타입 정의) | | [vehicle-react-implementation.md](plans/vehicle-react-implementation.md) | 차량관리 React 구현 요청서 (3개 메뉴, 컴포넌트 구조, 타입 정의) | | [stock-production-react-request.md](plans/stock-production-react-request.md) | 재고생산관리 React 구현 요청서 (수주 화면 단순화, API 스펙 포함) | diff --git a/frontend/api-specs/receiving-item-search-fix-20260318.md b/frontend/api-specs/receiving-item-search-fix-20260318.md new file mode 100644 index 0000000..97f0fb7 --- /dev/null +++ b/frontend/api-specs/receiving-item-search-fix-20260318.md @@ -0,0 +1,138 @@ +# 입고등록 품목 검색 버그 수정 (2026-03-18) + +**날짜:** 2026-03-18 +**작업자:** R&D실 (백엔드) +**대상:** React 프론트엔드 +**API 상태:** 수정 완료, develop 배포 대기 + +--- + +## 문제 현상 + +입고등록 화면에서 품목코드 검색 시 두 가지 문제 발생: + +1. **전체 품목 표시**: FG(완제품), PT(부품) 등 입고 대상이 아닌 품목까지 검색됨 +2. **20건 제한**: `per_page=50`을 전송해도 항상 20건만 반환 + +--- + +## 원인 + +API와 React 간 **파라미터 이름 불일치**: + +``` +React (fetchItems) API (ItemsController) +───────────────── ──────────────────── +per_page=50 ──→ ❌ 무시 size 파라미터만 읽음 (기본 20) +itemType=RM,SM,CS ──→ ❌ 무시 type / item_type만 읽음 +``` + +--- + +## 수정 완료 항목 + +### 1. API — `ItemsController.php` (백엔드 수정 완료) + +`GET /api/v1/items` 엔드포인트가 이제 다음 파라미터도 수용: + +| 파라미터 | 설명 | 비고 | +|---------|------|------| +| `per_page` | 페이지당 건수 | 기존 `size`와 동일하게 동작 | +| `itemType` | 품목 유형 (camelCase) | 기존 `type`, `item_type`과 동일하게 동작 | + +> 기존 `size`, `type`, `item_type` 파라미터는 변경 없이 그대로 동작한다 (하위호환). + +### 2. React — `ReceivingDetail.tsx` (프론트엔드 수정 완료) + +```typescript +// 변경 전 + + +// 변경 후 — 원자재/부자재/소모품만 검색 + +``` + +### 3. React — `actions.ts` dead code 제거 + +`searchItems()` 함수, `ItemOption` 인터페이스, `MOCK_ITEMS` 상수를 제거했다. +실제 품목검색은 `ItemSearchModal` → `fetchItems()` (`lib/api/items.ts`)를 통해 이루어지며, +`actions.ts`의 `searchItems()`는 어디서도 import하지 않는 미사용 코드였다. + +--- + +## 품목 유형 필터 기준 + +입고등록에서 검색되는 품목: + +| item_type | 한글 | 검색 여부 | +|-----------|------|:---------:| +| `RM` | 원자재 | ✅ | +| `SM` | 부자재 | ✅ | +| `CS` | 소모품 | ✅ | +| `FG` | 완제품 | ❌ | +| `PT` | 부품 | ❌ | +| `SF` | 반제품 | ❌ | +| `BN` | 절곡품 | ❌ | + +--- + +## 프론트엔드 작업 사항 + +> **코드 수정은 이미 완료됨.** 아래는 `git pull` 후 확인할 내용. + +### 확인 체크리스트 + +``` +git pull origin develop +``` + +- [ ] 입고등록(`/material/receiving-management?mode=new`) 진입 +- [ ] 품목코드 검색 모달 열기 +- [ ] 아무 글자 입력 후 검색 +- [ ] 검색 결과에 RM/SM/CS만 표시되는지 확인 +- [ ] FG/PT 품목이 없는지 확인 +- [ ] 품목이 20건 이상일 때 모두 표시되는지 확인 + +### 수정된 파일 (React) + +| 파일 | 변경 내용 | +|------|----------| +| `src/components/material/ReceivingManagement/ReceivingDetail.tsx` | `ItemSearchModal`에 `itemType="RM,SM,CS"` prop 추가 | +| `src/components/material/ReceivingManagement/actions.ts` | 미사용 `searchItems()` 함수 제거 (52줄) | + +--- + +## API 호출 예시 (참고용) + +``` +GET /api/v1/items?search=철판&itemType=RM,SM,CS&per_page=50 + +응답: +{ + "success": true, + "data": { + "data": [...], // RM/SM/CS 품목만 + "per_page": 50, // 50건 기준 페이징 + "total": 34 + } +} +``` + +--- + +## 관련 문서 + +- [stock-receiving-changes-20260317.md](stock-receiving-changes-20260317.md) — 입고관리 전체 변경사항 (섹션 4 업데이트됨) + +--- + +**최종 업데이트**: 2026-03-18