sam-docs/history/2025-11/item-master-archived/[API-2025-11-23] item-master-backend-requirements.md

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 헤더 추가 필요

# 현재 설정 (추정)
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 헤더를 포함하여 전송

테스트 방법

# 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.local
NEXT_PUBLIC_API_URL=https://api.codebridge-x.com
NEXT_PUBLIC_API_KEY=42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a

Frontend 코드에서 사용 중

// 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 사용

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 사용

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

{
  "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 타입

{
  "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 타입

{
  "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 설정 확인

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 테스트

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