sam-react-prod/claudedocs/item-master/[IMPL-2026-01-09] item-management-api-integration.md

[IMPL-2026-01-09] 자재관리(품목관리) API 연동

작업 개요

• 작업자: Claude Code
• 작업일: 2026-01-09
• Phase: 2.3 자재관리 (시공사 페이지 API 연동 계획)
• 이전 Phase: 2.2 거래처관리 완료

변경 사항 요약

Backend (api/)

1. 라우트 추가

파일: routes/api.php

// Items (통합 품목 관리 - items 테이블)
Route::prefix('items')->group(function () {
    Route::get('', [ItemsController::class, 'index'])->name('v1.items.index');
    Route::get('/stats', [ItemsController::class, 'stats'])->name('v1.items.stats'); // 신규
    Route::post('', [ItemsController::class, 'store'])->name('v1.items.store');
    Route::get('/code/{code}', [ItemsController::class, 'showByCode'])->name('v1.items.show_by_code');
    Route::get('/{id}', [ItemsController::class, 'show'])->name('v1.items.show');
    Route::put('/{id}', [ItemsController::class, 'update'])->name('v1.items.update');
    Route::delete('/batch', [ItemsController::class, 'batchDestroy'])->name('v1.items.batch_destroy');
    Route::delete('/{id}', [ItemsController::class, 'destroy'])->name('v1.items.destroy');
});

중요: /stats 라우트는 /{id} 보다 먼저 정의하여 "stats"가 ID로 캡처되는 것을 방지

Frontend (react/)

1. actions.ts 완전 재작성

파일: src/components/business/construction/item-management/actions.ts

변경 전: Mock 데이터 기반 (mockItems, mockOrderItems 배열) 변경 후: 실제 API 연동

주요 구현 내용

타입 변환 함수

함수명	용도
transformItemType()	Backend item_type → Frontend itemType
transformToBackendItemType()	Frontend itemType → Backend item_type
transformSpecification()	Backend options → Frontend specification
transformOrderType()	Backend options → Frontend orderType
transformStatus()	Backend is_active + options → Frontend status
transformOrderItems()	Backend options → Frontend orderItems
transformItem()	API 응답 → Item 타입
transformItemDetail()	API 응답 → ItemDetail 타입
transformItemToApi()	ItemFormData → API 요청 데이터

품목 유형 매핑

Frontend (Korean)	Backend (Code)
제품	FG
부품	PT
소모품	CS (또는 SM)
공과	RM

API 함수

함수명	API Endpoint	설명
getItemList()	GET /api/v1/items	품목 목록 조회
getItemStats()	GET /api/v1/items/stats	품목 통계 조회
getItem()	GET /api/v1/items/{id}	품목 상세 조회
createItem()	POST /api/v1/items	품목 등록
updateItem()	PUT /api/v1/items/{id}	품목 수정
deleteItem()	DELETE /api/v1/items/{id}	품목 삭제
deleteItems()	DELETE /api/v1/items/batch	품목 일괄 삭제
getCategoryOptions()	GET /api/v1/categories	카테고리 목록 조회

Frontend 전용 필터링

Backend에서 지원하지 않는 필터는 Frontend에서 처리:

• 규격 (specification) 필터
• 구분 (orderType) 필터
• 날짜 범위 (startDate, endDate) 필터
• 정렬 (sortBy: latest/oldest)

필드 매핑 상세

Item 기본 필드

Frontend	Backend	변환 방식
id	id	String 변환
itemNumber	code	직접 매핑
itemName	name	직접 매핑
itemType	item_type	transformItemType()
categoryId	category_id	String 변환
categoryName	category.name	nested 접근
unit	unit	직접 매핑 (기본값: EA)
specification	options.specification	transformSpecification()
orderType	options.orderType	transformOrderType()
status	is_active + options.status	transformStatus()
createdAt	created_at	직접 매핑
updatedAt	updated_at	직접 매핑

ItemDetail 추가 필드

Frontend	Backend	변환 방식
note	description	직접 매핑
orderItems	options.orderItems	transformOrderItems()

테스트 체크리스트

API 연동 확인

• 품목 목록 조회 (GET /items)
• 품목 통계 조회 (GET /items/stats)
• 품목 상세 조회 (GET /items/{id})
• 품목 등록 (POST /items)
• 품목 수정 (PUT /items/{id})
• 품목 삭제 (DELETE /items/{id})
• 품목 일괄 삭제 (DELETE /items/batch)
• 카테고리 목록 조회 (GET /categories)

필터링 확인

• 검색 필터 (search → q)
• 품목유형 필터 (itemType → type)
• 카테고리 필터 (categoryId → category_id)
• 활성상태 필터 (status → active)
• 규격 필터 (Frontend only)
• 구분 필터 (Frontend only)
• 날짜 필터 (Frontend only)

데이터 변환 확인

• 품목유형 한글 ↔ 코드 변환
• 상태값 변환 (is_active ↔ status)
• options JSON 필드 파싱/생성

관련 파일

수정된 파일

1. api/routes/api.php - /items/stats 라우트 추가
2. react/src/components/business/construction/item-management/actions.ts - Mock → API 변환

참조 파일

• api/app/Http/Controllers/Api/V1/ItemsController.php
• api/app/Services/ItemService.php
• react/src/components/business/construction/item-management/types.ts
• react/src/lib/api.ts

다음 단계

Phase 2.4 예정

• 자재관리 (품목관리) UI 컴포넌트 연동 테스트
• 에러 핸들링 개선
• 로딩 상태 처리

향후 개선 사항

• Backend에서 추가 필터 지원 시 Frontend 필터 제거
• options 필드 구조 표준화
• 품목 일괄 등록 API 추가 고려