sam-react-prod/claudedocs/item-master/[IMPL-2025-12-15] backend-item-api-migration.md

백엔드 품목 API 통합 마이그레이션

개요

항목	내용
작성일	2025-12-15
배경	백엔드에서 product/material 분리 구조 → 통합 구조로 변경
영향	프론트엔드 품목 목록 API 호출 방식 변경

---

백엔드 변경사항 요약

주요 커밋

aaf7979 fix: ItemsFileController 파일 API 오류 수정
18ef35a refactor: 레거시 product_id/material_id 컬럼 삭제
4f3b218 feat: Phase 5 - 참조 테이블 모델 item_id 마이그레이션
20ad6da fix: P0 Critical 이슈 수정 - 삭제된 Product/Material 참조 제거
039fd62 refactor: products/materials 테이블 및 관련 코드 삭제
9cc7cd1 fix: ItemService newQuery()에 item_type 필터 추가
d1afa6e feat: ItemService 동적 테이블 라우팅 구현

핵심 변경

1. products, materials 테이블 삭제 → items 테이블로 통합
2. ItemService가 item_type 기반 동적 테이블 라우팅 구현
3. API 호출 시 item_type 또는 group_id 필수

---

프론트엔드 수정 (2025-12-15)

수정 파일

• src/hooks/useItemList.ts

변경 내용

1. 품목 목록 조회 (fetchItems)

조회 타입	변경 전	변경 후
전체 조회	파라미터 없음	group_id=1
타입별 조회	type=FG	type=FG (유지)

// 변경 후 코드
if (filters.type && filters.type !== 'all') {
  // 특정 타입 조회: type 파라미터 사용
  params.append('type', filters.type);
} else {
  // 전체 조회: group_id=1 (품목관리 그룹)
  params.append('group_id', '1');
}

2. 전체 통계 조회 (fetchTotalStats)

조회 타입	변경 전	변경 후
전체	/api/proxy/items?size=1	/api/proxy/items?group_id=1&size=1
타입별	/api/proxy/items?type=FG&size=1	(유지)

---

현재 하드코딩 값 (향후 동적 변경 예정)

하드코딩된 값 목록

항목	현재 값	위치	비고
group_id	1	useItemList.ts	품목관리 그룹 고정
ItemType	'FG' | 'PT' | 'SM' | 'RM' | 'CS'	src/types/item.ts	품목 유형 고정
통계 타입	5개 고정 (FG, PT, SM, RM, CS)	useItemList.ts	TotalStats 인터페이스

향후 동적 변경 계획

백엔드 품목기준관리에서 그룹(Group) 상위 개념이 추가되면:

1. init API 응답에 다음 정보 포함 필요:

   {
     groupId: number,           // 현재 페이지의 group_id
     itemTypes: string[],       // 이 그룹에서 사용하는 item_type 목록
     // 예: ['FG', 'PT', 'SM', 'RM', 'CS']
   }
   

2. 프론트엔드 수정 필요:

   • useItemList.ts: 하드코딩된 group_id=1 제거 → API 응답값 사용
   • src/types/item.ts: ItemType 타입을 동적으로 처리
   • TotalStats: 고정 타입 대신 동적 item_type 목록 기반으로 변경

3. 영향 범위:

   • 품목 목록 페이지
   • 품목 통계 (타입별 카운트)
   • 품목 필터 드롭다운
   • 품목 생성/수정 폼의 타입 선택

---

API 요청 형식 정리

품목 목록 조회

# 전체 조회 (품목관리 그룹)
GET /api/proxy/items?group_id=1

# 타입별 조회
GET /api/proxy/items?type=FG
GET /api/proxy/items?type=PT
GET /api/proxy/items?type=SM
GET /api/proxy/items?type=RM
GET /api/proxy/items?type=CS

# 검색 + 페이지네이션
GET /api/proxy/items?group_id=1&search=검색어&page=1&size=20
GET /api/proxy/items?type=FG&search=검색어&page=1&size=20

품목 상세/수정/삭제 (item_type 필수)

# 단건 조회
GET /api/proxy/items/{id}?item_type=FG

# 수정
PUT /api/proxy/items/{id}
Body: { item_type: 'FG', ... }

# 삭제
DELETE /api/proxy/items/{id}?item_type=FG

---

체크리스트

완료 (2025-12-15)

• useItemList.ts - 전체 조회 시 group_id=1 추가
• useItemList.ts - 통계 조회 시 group_id=1 추가
• 문서 작성

백엔드 대기

• 백엔드 group_id 파라미터 처리 구현 확인
• init API에 groupId, itemTypes 정보 추가 요청

향후 작업 (동적 변경 시)

• useItemList.ts - group_id 하드코딩 제거 → Context/API 응답값 사용
• src/types/item.ts - ItemType 동적 처리
• TotalStats 인터페이스 동적 타입 지원
• 품목 필터 드롭다운 동적 렌더링

---

참고

관련 파일

• src/hooks/useItemList.ts - 품목 목록 훅
• src/types/item.ts - ItemType 타입 정의
• src/lib/api/item-master.ts - 품목기준관리 API

관련 문서

• claudedocs/security/[PLAN-2025-12-12] tenant-data-isolation-implementation.md - 테넌트 데이터 격리