docs: [receiving] 입고 품목검색 수정 이력 추가

- 03-17 문서 섹션4 실제 구현에 맞게 수정 (근본원인, 코드경로 정정) - 변경이력 추가: 20260318_receiving_item_search_fix.md - INDEX.md 등록
2026-03-18 13:17:38 +09:00
parent 5f9eb7f44c
commit 462639a51b
3 changed files with 120 additions and 20 deletions
--- a/INDEX.md
+++ b/INDEX.md
@@ -253,6 +253,7 @@ DB 도메인별:
 | [20260317_account_code_migration_mapping.md](changes/20260317_account_code_migration_mapping.md) | 계정과목 코드 변경 매핑 (더존 3자리 → KIS 5자리) |
 | [20260317_account_code_change_notice.md](changes/20260317_account_code_change_notice.md) | 계정과목 코드 변경 안내 (경리 전달용) |
 | [20260318_notification_settings_soundtype.md](dev/changes/20260318_notification_settings_soundtype.md) | 알림설정 soundType API 연동 + 음원 파일 서빙 (React 미구현 항목 포함) |
+| [20260318_receiving_item_search_fix.md](dev/changes/20260318_receiving_item_search_fix.md) | 입고등록 품목검색 필터/페이징 수정 (per_page/itemType 파라미터 호환성) |

 ---

--- a/dev/changes/20260318_receiving_item_search_fix.md
+++ b/dev/changes/20260318_receiving_item_search_fix.md
@@ -0,0 +1,76 @@
+# 입고등록 품목 검색 필터/페이징 수정
+
+**날짜:** 2026-03-18
+**작업자:** Claude Code
+
+---
+
+## 변경 개요
+
+입고등록 화면의 품목 검색에서 **전체 품목이 표시**되고 **20건 제한**이 풀리지 않는 문제를 수정했다.
+
+### 근본 원인
+
+React와 API 간 파라미터 이름 불일치:
+
+| 문제 | React 전송 | API 수신 | 결과 |
+|------|-----------|---------|------|
+| 페이징 | `per_page=50` | `size` (기본 20) | per_page 무시 → 20건 |
+| 품목유형 | `itemType` (camelCase) | `type` / `item_type` | itemType 무시 → 전체 품목 |
+
+---
+
+## 수정된 파일
+
+| 프로젝트 | 파일 | 변경 내용 |
+|---------|------|----------|
+| API | `app/Http/Controllers/Api/V1/ItemsController.php` | `per_page`, `itemType` 파라미터 수용 추가 |
+| React | `src/components/material/ReceivingManagement/ReceivingDetail.tsx` | `ItemSearchModal`에 `itemType="RM,SM,CS"` prop 추가 |
+
+---
+
+## 상세 변경 사항
+
+### 1. API — ItemsController::index()
+
+```php
+// AS-IS
+'size' => $request->input('size', 20),
+'item_type' => $request->input('type') ?? $request->input('item_type'),
+
+// TO-BE
+'size' => $request->input('size') ?? $request->input('per_page', 20),
+'item_type' => $request->input('type') ?? $request->input('item_type') ?? $request->input('itemType'),
+```
+
+- `per_page` 파라미터도 `size`로 매핑 (React 호환)
+- `itemType` (camelCase) 파라미터도 `item_type`으로 매핑
+
+### 2. React — ReceivingDetail.tsx
+
+```typescript
+<ItemSearchModal
+  ...
+  itemType="RM,SM,CS"  // 원자재(RM) + 부자재(SM) + 소모품(CS)만
+/>
+```
+
+- 입고 대상인 원자재 성격의 품목만 검색되도록 필터 적용
+- FG(완제품), PT(부품), SF(반제품), BN(절곡품) 제외
+
+---
+
+## 영향 범위
+
+- `GET /api/v1/items` 엔드포인트: 기존 `size`/`type`/`item_type` 파라미터 동작 변경 없음 (하위호환)
+- `per_page`, `itemType` 파라미터가 추가로 수용됨 (React `fetchItems()` 호환)
+
+---
+
+## 관련 문서
+
+- [stock-receiving-changes-20260317.md](../frontend/api-specs/stock-receiving-changes-20260317.md) — 섹션 4 체크리스트 업데이트
+
+---
+
+**최종 업데이트**: 2026-03-18
--- a/frontend/api-specs/stock-receiving-changes-20260317.md
+++ b/frontend/api-specs/stock-receiving-changes-20260317.md
@@ -292,36 +292,58 @@ TO-BE:

 ## 4. 입고 품목 검색 개선

+> **상태**: ✅ 구현 완료 (2026-03-18)
+
 ### 현재 문제

 1. **검색 결과 20건 제한**: 품목이 많은 테넌트에서 원하는 품목을 찾기 어려움
 2. **모든 품목 유형 표시**: 가공품, 반제품 등 입고와 무관한 품목도 검색됨
 3. **원자재 입고에 맞지 않는 결과**: 철판, 모터 등 미가공 원자재만 검색되어야 함

-### 변경 내용
+### 근본 원인 (2026-03-18 확인)

-`searchItems()` 함수(`ReceivingManagement/actions.ts`)에서 API 호출 파라미터를 변경한다.
+API와 React 간 **파라미터 이름 불일치**로 인해 필터가 동작하지 않았다:

-```typescript
-// AS-IS (현재)
-url: buildApiUrl('/api/v1/items', { search: query, per_page: 50 }),
+| React가 전송 | API Controller가 읽음 | 결과 |
+|-------------|---------------------|------|
+| `per_page=50` | `size` (기본값 20) | **per_page 무시, 항상 20건** |
+| `itemType=RM,SM,CS` | `type` 또는 `item_type` | **itemType(camelCase) 무시, 전체 품목 반환** |

-// TO-BE (변경)
-url: buildApiUrl('/api/v1/items', {
-  search: query,
-  per_page: 200,          // 검색 제한 완화 (20 → 200)
-  item_type: 'RM,SM,CS',  // 원자재(RM) + 부자재(SM) + 소모품(CS)만
-}),
+### 수정 내용
+
+#### 1) API 수정 — `ItemsController.php`
+
+```php
+// AS-IS
+'size' => $request->input('size', 20),
+'item_type' => $request->input('type') ?? $request->input('item_type'),
+
+// TO-BE (per_page, itemType 파라미터도 수용)
+'size' => $request->input('size') ?? $request->input('per_page', 20),
+'item_type' => $request->input('type') ?? $request->input('item_type') ?? $request->input('itemType'),
 ```

-### API 파라미터 설명
+#### 2) React 수정 — `ReceivingDetail.tsx`

-| 파라미터 | 값 | 설명 |
-|---------|------|------|
-| `per_page` | `200` | 검색 결과 제한 완화 |
-| `item_type` | `RM,SM,CS` | 원자재/부자재/소모품만 (콤마 구분 멀티 지원) |
+실제 품목검색은 `ItemSearchModal` 컴포넌트를 통해 `fetchItems()` (`lib/api/items.ts`)를 호출한다.
+(`actions.ts`의 `searchItems()`는 미사용 dead code)

-> API는 `item_type` 콤마 구분 멀티 필터를 이미 지원한다. 추가 백엔드 작업 불필요.
+```typescript
+// AS-IS — itemType 미전달
+<ItemSearchModal
+  open={isItemSearchOpen}
+  onOpenChange={setIsItemSearchOpen}
+  onSelectItem={handleSelectItem}
+/>
+
+// TO-BE — 원자재/부자재/소모품만 필터링
+<ItemSearchModal
+  open={isItemSearchOpen}
+  onOpenChange={setIsItemSearchOpen}
+  onSelectItem={handleSelectItem}
+  itemType="RM,SM,CS"
+/>
+```

 ### 제외되는 품목 유형

@@ -358,10 +380,11 @@ url: buildApiUrl('/api/v1/items', {
 - [ ] + 추가 버튼 → 입력 폼/모달 → `POST /stocks/{stockId}/adjustments` 연동
 - [ ] 조정 성공 시 재고량 갱신 (기본 정보 리로드)

-### 품목 검색 (actions.ts — searchItems)
+### 품목 검색 (ItemSearchModal + API)

- [ ] `per_page: 50` → `per_page: 200`으로 변경
- [ ] `item_type: 'RM,SM,CS'` 파라미터 추가 (원자재/부자재/소모품만)
+- [x] API `ItemsController`: `per_page`, `itemType`(camelCase) 파라미터 수용 (2026-03-18)
+- [x] `ReceivingDetail.tsx`: `ItemSearchModal`에 `itemType="RM,SM,CS"` prop 전달 (2026-03-18)
+- [ ] (정리) `actions.ts`의 `searchItems()` dead code 제거 (미사용 확인됨)

 ### 재고 조정 모달 (InventoryAdjustmentDialog.tsx)