# Item Master API 백엔드 처리 요구사항

**작성일**: 2025-11-23
**작성자**: Claude Code (Frontend 타입 에러 수정 및 API 연결 테스트)
**목적**: Item Master 기능 API 연동을 위한 백엔드 설정 및 확인 필요 사항 정리

---

## 🚨 우선순위 1: CORS 설정 필요

### 현재 발생 중인 에러
```
Access to fetch at 'https://api.codebridge-x.com/item-master/init'
from origin 'http://localhost:3001'
has been blocked by CORS policy:
Request header field x-api-key is not allowed by
Access-Control-Allow-Headers in preflight response.
```

### 필요한 조치
**API 서버 CORS 설정에 `X-API-Key` 헤더 추가 필요**

```yaml
# 현재 설정 (추정)
Access-Control-Allow-Headers: Content-Type, Authorization

# 필요한 설정
Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key
```

### 영향받는 엔드포인트
- 모든 Item Master API 엔드포인트 (`/item-master/*`)
- Frontend에서 모든 요청에 `x-api-key` 헤더를 포함하여 전송

### 테스트 방법
```bash
# CORS preflight 테스트
curl -X OPTIONS https://api.codebridge-x.com/item-master/init \
  -H "Origin: http://localhost:3001" \
  -H "Access-Control-Request-Method: GET" \
  -H "Access-Control-Request-Headers: x-api-key" \
  -v

# 예상 응답 헤더
Access-Control-Allow-Origin: http://localhost:3001
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key
```

---

## ⚙️ 우선순위 2: API 엔드포인트 구조 확인

### Frontend에서 호출하는 엔드포인트

| 메서드 | 엔드포인트 | 용도 | 상태 |
|--------|------------|------|------|
| GET | `/item-master/init` | 초기 데이터 로드 (페이지, 섹션, 필드) | ❓ 미확인 |
| POST | `/item-master/pages` | 새 페이지 생성 | ❓ 미확인 |
| PUT | `/item-master/pages/:id` | 페이지 수정 | ❓ 미확인 |
| DELETE | `/item-master/pages/:id` | 페이지 삭제 | ❓ 미확인 |
| POST | `/item-master/sections` | 새 섹션 생성 | ❓ 미확인 |
| PUT | `/item-master/sections/:id` | 섹션 수정 | ❓ 미확인 |
| DELETE | `/item-master/sections/:id` | 섹션 삭제 | ❓ 미확인 |
| POST | `/item-master/fields` | 새 필드 생성 | ❓ 미확인 |
| PUT | `/item-master/fields/:id` | 필드 수정 | ❓ 미확인 |
| DELETE | `/item-master/fields/:id` | 필드 삭제 | ❓ 미확인 |
| POST | `/item-master/bom` | BOM 항목 추가 | ❓ 미확인 |
| PUT | `/item-master/bom/:id` | BOM 항목 수정 | ❓ 미확인 |
| DELETE | `/item-master/bom/:id` | BOM 항목 삭제 | ❓ 미확인 |

### 확인 필요 사항
- [ ] 각 엔드포인트가 구현되어 있는지 확인
- [ ] Base URL이 `https://api.codebridge-x.com`가 맞는지 확인
- [ ] 인증 방식이 `X-API-Key` 헤더 방식이 맞는지 확인
- [ ] Response 형식이 Frontend 기대값과 일치하는지 확인

---

## 🔑 우선순위 3: 환경 변수 및 API 키 확인

### 현재 Frontend 설정
```env
# .env.local
NEXT_PUBLIC_API_URL=https://api.codebridge-x.com
NEXT_PUBLIC_API_KEY=42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a
```

### Frontend 코드에서 사용 중
```typescript
// src/lib/api/item-master.ts
const BASE_URL = process.env.NEXT_PUBLIC_API_BASE_URL || 'http://api.sam.kr/api/v1';
```

### 문제점
- `.env.local`에는 `NEXT_PUBLIC_API_URL`로 정의
- 코드에서는 `NEXT_PUBLIC_API_BASE_URL` 참조
- 현재는 fallback URL(`http://api.sam.kr/api/v1`)을 사용 중

### 확인 필요 사항
- [ ] Item Master API Base URL이 기존 Auth API와 동일한지 (`https://api.codebridge-x.com`)
- [ ] API 키가 Item Master 엔드포인트에서 유효한지 확인
- [ ] API 키 권한에 Item Master 관련 권한이 포함되어 있는지 확인

### 권장 조치
**옵션 1**: 동일 Base URL 사용
```env
NEXT_PUBLIC_API_URL=https://api.codebridge-x.com
NEXT_PUBLIC_API_KEY=42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a
```
→ Frontend 코드 수정 필요: `NEXT_PUBLIC_API_BASE_URL` → `NEXT_PUBLIC_API_URL`

**옵션 2**: 별도 Base URL 사용
```env
NEXT_PUBLIC_API_URL=https://api.codebridge-x.com  # Auth용
NEXT_PUBLIC_API_BASE_URL=https://api.codebridge-x.com  # Item Master용
NEXT_PUBLIC_API_KEY=42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a
```
→ 추가 환경 변수 설정 필요

---

## 📋 예상 API Response 형식

### GET /item-master/init
```typescript
{
  "success": true,
  "data": {
    "itemPages": [
      {
        "id": number,
        "tenant_id": number,
        "page_name": string,
        "page_order": number,
        "item_type": string,
        "absolute_path": string | null,
        "sections": [
          {
            "id": number,
            "tenant_id": number,
            "page_id": number,
            "section_title": string,
            "section_type": "fields" | "bom_table",
            "section_order": number,
            "fields": Field[],  // section_type이 "fields"일 때
            "bomItems": BOMItem[]  // section_type이 "bom_table"일 때
          }
        ]
      }
    ]
  }
}
```

### Field 타입
```typescript
{
  "id": number,
  "tenant_id": number,
  "section_id": number,
  "field_name": string,
  "field_type": "text" | "number" | "select" | "date" | "textarea",
  "field_order": number,
  "is_required": boolean,
  "default_value": string | null,
  "options": string[] | null,  // field_type이 "select"일 때
  "validation_rules": object | null,
  "created_at": string,
  "updated_at": string
}
```

### BOMItem 타입
```typescript
{
  "id": number,
  "tenant_id": number,
  "section_id": number,
  "item_code": string | null,
  "item_name": string,
  "quantity": number,
  "unit": string | null,
  "unit_price": number | null,
  "total_price": number | null,
  "spec": string | null,
  "note": string | null,
  "created_by": number | null,
  "updated_by": number | null,
  "created_at": string,
  "updated_at": string
}
```

---

## ✅ Frontend에서 완료된 작업

### 1. TypeScript 타입 에러 수정 완료
- ✅ BOMItem 생성 시 `section_id`, `updated_at` 누락 수정
- ✅ 미사용 변수 ESLint 에러 해결 (underscore prefix)
- ✅ Navigator API SSR 호환성 수정 (`typeof window` 체크)
- ✅ 상수 조건식 에러 해결 (주석 처리)
- ✅ 미사용 import 제거 (Badge)

**수정 파일**: `/src/components/items/ItemMasterDataManagement/tabs/HierarchyTab/index.tsx`

### 2. API 클라이언트 구현 완료
**파일**: `/src/lib/api/item-master.ts`

구현된 함수:
- `initItemMaster()` - 초기 데이터 로드
- `createItemPage()` - 페이지 생성
- `updateItemPage()` - 페이지 수정
- `deleteItemPage()` - 페이지 삭제
- `createSection()` - 섹션 생성
- `updateSection()` - 섹션 수정
- `deleteSection()` - 섹션 삭제
- `createField()` - 필드 생성
- `updateField()` - 필드 수정
- `deleteField()` - 필드 삭제
- `createBOMItem()` - BOM 항목 생성
- `updateBOMItem()` - BOM 항목 수정
- `deleteBOMItem()` - BOM 항목 삭제

모든 함수에 에러 핸들링 및 로깅 포함

---

## 🧪 테스트 계획 (백엔드 준비 완료 후)

### 1단계: CORS 설정 확인
```bash
curl -X OPTIONS https://api.codebridge-x.com/item-master/init \
  -H "Origin: http://localhost:3001" \
  -H "Access-Control-Request-Headers: x-api-key" \
  -v
```

### 2단계: Init API 테스트
```bash
curl -X GET https://api.codebridge-x.com/item-master/init \
  -H "x-api-key: 42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a" \
  -v
```

### 3단계: Frontend 통합 테스트
- [ ] 페이지 로드 시 init API 호출 성공
- [ ] 새 페이지 생성 및 저장
- [ ] 섹션 추가/수정/삭제
- [ ] 필드 추가/수정/삭제
- [ ] BOM 항목 추가/수정/삭제
- [ ] 에러 핸들링 (네트워크 에러, 인증 에러 등)

---

## 📞 연락 필요 사항

**백엔드 팀 확인 후 회신 필요:**
1. CORS 설정 완료 예정일
2. Item Master API 엔드포인트 구현 상태
3. API Base URL 및 인증 방식 확인
4. Response 형식 최종 확인

**Frontend 팀 대기 중:**
- 백엔드 준비 완료 후 즉시 통합 테스트 진행 가능
- 현재 TypeScript 컴파일 에러 없음, UI 구현 완료

---

## 📎 참고 파일

- API 클라이언트: `/src/lib/api/item-master.ts`
- Context 정의: `/src/contexts/ItemMasterContext.tsx`
- UI 컴포넌트: `/src/components/items/ItemMasterDataManagement/tabs/HierarchyTab/index.tsx`
- 환경 변수: `/.env.local`