# 백엔드 품목 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` (유지) |

```typescript
// 변경 후 코드
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 응답**에 다음 정보 포함 필요:
   ```typescript
   {
     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 요청 형식 정리

### 품목 목록 조회

```bash
# 전체 조회 (품목관리 그룹)
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 필수)

```bash
# 단건 조회
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)
- [x] `useItemList.ts` - 전체 조회 시 `group_id=1` 추가
- [x] `useItemList.ts` - 통계 조회 시 `group_id=1` 추가
- [x] 문서 작성

### 백엔드 대기
- [ ] 백엔드 `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` - 테넌트 데이터 격리