sam-docs/projects/mes/ITEM_MANAGEMENT_MIGRATION_GUIDE.md

품목관리 마이그레이션 가이드 (Next.js 15)

작성일: 2025-11-13 (Updated) 프론트엔드: Next.js 15 App Router + React 19 백엔드: PHP Laravel 상태 관리: Zustand 소스: React 프로젝트 → Next.js 15 마이그레이션

---

📑 목차

1. 프로젝트 개요
2. 하이브리드 아키텍처
3. 데이터 구조
4. Next.js 15 구조
5. API 연동 전략
6. 마이그레이션 계획
7. Zustand 상태 관리
8. Server/Client Components
9. 주의사항

---

1. 프로젝트 개요

1.1 목표

1차 목표: 물리적 페이지 구축 및 Laravel API 연동 2차 목표: 템플릿 기반 동적 페이지 생성 시스템 (선택적 확장)

1.2 핵심 요구사항

1. ✅ 품목 유형 관리: 제품/부품/원자재/부자재/소모품 (FG/PT/SM/RM/CS)
2. ✅ 계층 구조: 제품이 최상위, BOM을 통해 하위 품목 연결
3. ✅ 유형별 고유 필드: 각 품목 유형마다 전용 입력 항목
4. ✅ Laravel API 연동: RESTful API 호출
5. ✅ Next.js 15 최적화: Server Components, App Router
6. 🎯 하이브리드 전략: 물리적 페이지 (80%) + 동적 템플릿 (20%)

1.3 프로젝트 환경

소스 프로젝트

• 경로: /Users/byeongcheolryu/codebridgex/sam_project/sma-react-v2.0
• 스택: React 18 + Vite
• 메인 파일:
  • src/components/ItemManagement.tsx (7,919줄)
  • src/components/contexts/DataContext.tsx (6,697줄)
  • src/components/ItemMasterDataManagement.tsx (1,413줄)

타겟 프로젝트

• 경로: 현재 프로젝트 (sam-react-prod)
• 스택: Next.js 15 + React 19 + Zustand
• 특징:

  {
    "next": "15.5.6",
    "react": "19.2.0",
    "tailwindcss": "4",
    "zustand": "5.0.8",
    "next-intl": "4.4.0",
    "react-hook-form": "7.66.0",
    "zod": "4.1.12"
  }
  

---

2. 하이브리드 아키텍처

2.1 전략 개요

┌─────────────────────────────────────────────────────────────────┐
│                    품목관리 하이브리드 시스템                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                 ┌────────────┴────────────┐
                 │                         │
      ┌──────────▼──────────┐   ┌─────────▼──────────┐
      │  🏢 물리적 페이지     │   │  🎨 동적 템플릿      │
      │  (Next.js 페이지)    │   │  (DB 기반 생성)     │
      │                     │   │                    │
      │  ✅ 80% 사용 케이스  │   │  ✅ 20% 특수 케이스 │
      │  ✅ 타입 안정성      │   │  ✅ 고객사 커스터마이징│
      │  ✅ 빌드 타임 최적화 │   │  ✅ 런타임 유연성    │
      │  ✅ Server Components│   │  ✅ 코드 수정 불필요 │
      └──────────┬──────────┘   └─────────┬──────────┘
                 │                         │
                 └────────────┬────────────┘
                              │
                   ┌──────────▼──────────┐
                   │   Zustand Store     │
                   │  (전역 상태 관리)     │
                   │                     │
                   │  - itemStore        │
                   │  - templateStore    │
                   └──────────┬──────────┘
                              │
                   ┌──────────▼──────────┐
                   │   Laravel API       │
                   │                     │
                   │  - REST API         │
                   │  - PostgreSQL/MySQL │
                   │  - File Storage     │
                   └─────────────────────┘

2.2 왜 하이브리드인가?

물리적 페이지 (우선 구축)

장점:

• ✅ 성능: Server Components로 빌드 타임 최적화
• ✅ 안정성: TypeScript 타입 체크, 컴파일 타임 검증
• ✅ SEO: 서버 렌더링 자동 지원
• ✅ 개발 속도: 명확한 구조, 빠른 개발

사용 케이스 (80%):

• 제품(FG), 부품(PT), 원자재(RM), 부자재(SM), 소모품(CS) 등록
• 표준 BOM 관리
• 일반 품목 조회/수정

동적 템플릿 (선택적 확장)

장점:

• ✅ 유연성: 코드 수정 없이 DB로 페이지 생성
• ✅ 커스터마이징: 고객사별 특수 필드 추가
• ✅ 실험: 시범 운영, A/B 테스트

사용 케이스 (20%):

• 고객사 전용 품목 페이지
• 프로젝트별 특수 품목
• 시범 운영 페이지

2.3 데이터 흐름

물리적 페이지 흐름

사용자 요청
    ↓
Server Component (RSC)
    ↓
Laravel API 직접 호출 (서버)
    ↓
데이터 fetching
    ↓
Client Component로 전달
    ↓
사용자 인터랙션 (Zustand)
    ↓
API 변경 요청
    ↓
Revalidation

동적 템플릿 흐름

사용자 요청
    ↓
Template 조회 (DB)
    ↓
DynamicForm 렌더링
    ↓
조건부 필드 표시
    ↓
사용자 입력
    ↓
Laravel API 전송

---

3. 데이터 구조

3.1 ItemMaster (품목 마스터)

interface ItemMaster {
  // === 공통 필드 (모든 품목 유형) ===
  id: string;
  itemCode: string;                    // 품목 코드 (예: "KD-FG-001")
  itemName: string;                    // 품목명
  itemType: 'FG' | 'PT' | 'SM' | 'RM' | 'CS';
  unit: string;                        // 단위 (EA, SET, KG, M 등)
  specification?: string;              // 규격
  isActive?: boolean;                  // 활성/비활성

  // === 분류 ===
  category1?: string;                  // 대분류
  category2?: string;                  // 중분류
  category3?: string;                  // 소분류

  // === 가격 정보 ===
  purchasePrice?: number;              // 구매 단가
  salesPrice?: number;                 // 판매 단가
  marginRate?: number;                 // 마진율
  processingCost?: number;             // 가공비
  laborCost?: number;                  // 노무비
  installCost?: number;                // 설치비

  // === BOM (자재명세서) ===
  bom?: BOMLine[];                     // 하위 품목 구성
  bomCategories?: string[];            // BOM 카테고리

  // === 제품(FG) 전용 필드 ===
  productCategory?: 'SCREEN' | 'STEEL'; // 제품 카테고리
  lotAbbreviation?: string;            // 로트 약자 (예: "KD")
  note?: string;                       // 비고

  // === 부품(PT) 전용 필드 ===
  partType?: 'ASSEMBLY' | 'BENDING' | 'PURCHASED';
  partUsage?: 'GUIDE_RAIL' | 'BOTTOM_FINISH' | 'CASE' | 'DOOR' | 'BRACKET' | 'GENERAL';

  // 조립 부품
  installationType?: string;           // 설치 유형 (벽면형/측면형)
  assemblyType?: string;               // 종류 (M/T/C/D/S/U)
  sideSpecWidth?: string;              // 측면 규격 가로 (mm)
  sideSpecHeight?: string;             // 측면 규격 세로 (mm)
  assemblyLength?: string;             // 길이 (2438/3000/3500/4000/4300)

  // 가이드레일
  guideRailModelType?: string;         // 가이드레일 모델 유형
  guideRailModel?: string;             // 가이드레일 모델

  // 절곡품
  bendingDiagram?: string;             // 전개도 이미지 URL
  bendingDetails?: BendingDetail[];    // 전개도 상세 데이터
  material?: string;                   // 재질 (EGI 1.55T, SUS 1.2T)
  length?: string;                     // 길이/목함 (mm)
  bendingLength?: string;              // 절곡품 길이 규격

  // === 인정 정보 (제품/부품) ===
  certificationNumber?: string;        // 인정번호
  certificationStartDate?: string;     // 인정 유효기간 시작일
  certificationEndDate?: string;       // 인정 유효기간 종료일
  specificationFile?: string;          // 시방서 파일 URL
  specificationFileName?: string;      // 시방서 파일명
  certificationFile?: string;          // 인정서 파일 URL
  certificationFileName?: string;      // 인정서 파일명

  // === 메타데이터 ===
  safetyStock?: number;                // 안전재고
  leadTime?: number;                   // 리드타임
  isVariableSize?: boolean;            // 가변 크기 여부
  revisions?: ItemRevision[];          // 수정 이력

  createdAt?: string;
  updatedAt?: string;
}

3.2 BOMLine (자재명세서)

interface BOMLine {
  id: string;
  childItemCode: string;               // 하위 품목 코드
  childItemName: string;               // 하위 품목명
  quantity: number;                    // 기준 수량
  unit: string;                        // 단위
  unitPrice?: number;                  // 단가
  quantityFormula?: string;            // 수량 계산식 (예: "W * 2", "H + 100")
  note?: string;                       // 비고

  // 절곡품 관련
  isBending?: boolean;
  bendingDiagram?: string;             // 전개도 이미지 URL
  bendingDetails?: BendingDetail[];    // 전개도 상세 데이터
}

3.3 BendingDetail (절곡품 전개도)

interface BendingDetail {
  id: string;
  no: number;                          // 번호
  input: number;                       // 입력값
  elongation: number;                  // 연신율 (기본값 -1)
  calculated: number;                  // 연신율 계산 후 값
  sum: number;                         // 합계
  shaded: boolean;                     // 음영 여부
  aAngle?: number;                     // A각
}

3.4 동적 페이지 관련 (선택적)

// 템플릿 시스템용 (2차 목표)
interface ItemPage {
  id: string;
  pageName: string;                    // 페이지명
  itemType: 'FG' | 'PT' | 'SM' | 'RM' | 'CS';
  sections: ItemSection[];             // 페이지 내 섹션들
  isActive: boolean;                   // 사용 여부
  absolutePath?: string;               // 절대경로
  createdAt: string;
  updatedAt?: string;
}

interface ItemSection {
  id: string;
  title: string;                       // 섹션 제목
  description?: string;                // 설명
  category?: string[];                 // 카테고리 조건
  fields: ItemField[];                 // 섹션에 포함된 항목들
  type?: 'fields' | 'bom';             // 섹션 타입
  order: number;                       // 섹션 순서
  isCollapsible: boolean;              // 접기/펼치기 가능 여부
  isCollapsed: boolean;                // 기본 접힘 상태
}

interface ItemField {
  id: string;
  name: string;                        // 항목명
  fieldKey: string;                    // 필드 키
  property: ItemFieldProperty;         // 속성
  displayCondition?: FieldDisplayCondition; // 조건부 표시
}

---

4. Next.js 15 구조

4.1 디렉토리 구조

src/
├── app/
│   └── [locale]/
│       ├── (protected)/
│       │   ├── items/                          # 🏢 물리적 페이지 (우선 구축)
│       │   │   ├── page.tsx                    # 품목 목록 (Server Component)
│       │   │   ├── create/
│       │   │   │   └── page.tsx                # 품목 등록
│       │   │   └── [id]/
│       │   │       ├── page.tsx                # 품목 상세
│       │   │       └── edit/
│       │   │           └── page.tsx            # 품목 수정
│       │   │
│       │   ├── item-templates/                 # 🎨 동적 페이지 (선택적)
│       │   │   └── [pageId]/
│       │   │       └── page.tsx                # 템플릿 기반 렌더링
│       │   │
│       │   └── item-master-data/               # 🛠️ 관리 도구
│       │       └── page.tsx                    # 템플릿 생성/편집
│       │
│       └── api/                                # API Routes (선택적 프록시)
│           └── items/
│               └── route.ts
│
├── components/
│   ├── items/                                  # 품목 관리 컴포넌트
│   │   ├── ItemForm.tsx                        # 'use client'
│   │   ├── ItemList.tsx                        # Server Component 가능
│   │   ├── ItemListClient.tsx                  # 'use client' (상호작용)
│   │   ├── BOMManager.tsx                      # 'use client'
│   │   ├── BendingDiagramInput.tsx             # 'use client'
│   │   └── FileUpload.tsx                      # 'use client'
│   │
│   ├── dynamic-forms/                          # 동적 폼 (선택적)
│   │   ├── DynamicForm.tsx                     # 'use client'
│   │   ├── DynamicField.tsx
│   │   └── ConditionalSection.tsx
│   │
│   └── ui/                                     # shadcn/ui 컴포넌트
│       ├── button.tsx
│       ├── input.tsx
│       ├── select.tsx
│       ├── form.tsx
│       └── ...
│
├── stores/
│   ├── itemStore.ts                            # Zustand - 품목 상태
│   ├── templateStore.ts                        # Zustand - 템플릿 상태
│   └── types.ts                                # 공통 타입 정의
│
├── lib/
│   ├── api/
│   │   ├── items.ts                            # 품목 API 클라이언트
│   │   ├── bom.ts                              # BOM API 클라이언트
│   │   └── templates.ts                        # 템플릿 API
│   │
│   └── utils/
│       ├── validation.ts                       # Zod 스키마
│       └── formatters.ts                       # 데이터 포맷팅
│
└── types/
    └── item.ts                                 # 품목 관련 타입

4.2 파일별 역할

Server Components (기본)

// src/app/[locale]/(protected)/items/page.tsx
import { fetchItems } from '@/lib/api/items';

export default async function ItemsPage() {
  // 서버에서 직접 데이터 fetching
  const items = await fetchItems();

  return (
    <div>
      <h1>품목 목록</h1>
      {/* Client Component로 전달 */}
      <ItemListClient items={items} />
    </div>
  );
}

Client Components ('use client')

// src/components/items/ItemForm.tsx
'use client'

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { useItemStore } from '@/stores/itemStore';

export default function ItemForm() {
  const { addItem } = useItemStore();
  const form = useForm({
    resolver: zodResolver(itemSchema),
  });

  // 폼 제출, 이벤트 핸들러 등
}

---

5. API 연동 전략

5.1 Laravel API 엔드포인트

// Laravel 백엔드 API
const LARAVEL_API_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000';

// 품목 CRUD
GET    /api/items                    # 품목 목록
GET    /api/items/:itemCode          # 품목 상세
POST   /api/items                    # 품목 등록
PUT    /api/items/:itemCode          # 품목 수정
DELETE /api/items/:itemCode          # 품목 삭제

// BOM 관리
GET    /api/items/:itemCode/bom           # BOM 목록
GET    /api/items/:itemCode/bom/tree      # BOM 계층구조
POST   /api/items/:itemCode/bom           # BOM 추가
PUT    /api/items/:itemCode/bom/:lineId   # BOM 수정
DELETE /api/items/:itemCode/bom/:lineId   # BOM 삭제

// 파일 업로드
POST   /api/items/:itemCode/files         # 파일 업로드
DELETE /api/items/:itemCode/files/:type   # 파일 삭제

5.2 API 클라이언트 구현

// src/lib/api/items.ts
import type { ItemMaster } from '@/types/item';

const API_URL = process.env.NEXT_PUBLIC_API_URL;

export async function fetchItems(params?: {
  itemType?: string;
  search?: string;
  category1?: string;
}): Promise<ItemMaster[]> {
  const queryParams = new URLSearchParams(params as any);
  const response = await fetch(`${API_URL}/api/items?${queryParams}`, {
    headers: {
      'Authorization': `Bearer ${getToken()}`,
    },
  });

  if (!response.ok) {
    throw new Error('Failed to fetch items');
  }

  const data = await response.json();
  return data.data;
}

export async function createItem(item: Partial<ItemMaster>): Promise<ItemMaster> {
  const response = await fetch(`${API_URL}/api/items`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${getToken()}`,
    },
    body: JSON.stringify(item),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Failed to create item');
  }

  const data = await response.json();
  return data.data;
}

// 나머지 CRUD 함수들...

5.3 Server Component에서 API 호출

// src/app/[locale]/(protected)/items/page.tsx
import { fetchItems } from '@/lib/api/items';

export default async function ItemsPage({
  searchParams,
}: {
  searchParams: { type?: string; search?: string };
}) {
  // 서버에서 직접 API 호출 (토큰은 쿠키에서 자동으로)
  const items = await fetchItems({
    itemType: searchParams.type,
    search: searchParams.search,
  });

  return (
    <div>
      <h1>품목 목록</h1>
      <ItemListClient items={items} />
    </div>
  );
}

5.4 Client Component에서 API 호출

// src/components/items/ItemForm.tsx
'use client'

import { createItem } from '@/lib/api/items';
import { useRouter } from 'next/navigation';

export default function ItemForm() {
  const router = useRouter();

  const handleSubmit = async (data: ItemMaster) => {
    try {
      await createItem(data);
      router.push('/items');
      router.refresh(); // Server Component 재검증
    } catch (error) {
      console.error('Failed to create item:', error);
    }
  };

  // 폼 렌더링...
}

---

6. 마이그레이션 계획

6.1 단계별 계획 (수정됨)

Phase 1: 프로젝트 기반 구축 (2-3일)

✅ Next.js 15 프로젝트 구조 이해
✅ 데이터 구조 확정 (TypeScript 타입)
⏳ Laravel API 스펙 확인
⏳ 환경 변수 설정 (.env.local)
⏳ 인증 토큰 관리 전략

Phase 2: 공통 컴포넌트 마이그레이션 (3-4일)

⏳ shadcn/ui 컴포넌트 확인 (이미 설치됨)
⏳ 공통 폼 컴포넌트 (Input, Select, Button 등)
⏳ 레이아웃 컴포넌트 (PageHeader, FormActions 등)
⏳ 유효성 검사 (Zod 스키마 작성)

Phase 3: Zustand Store 구성 (2-3일)

⏳ itemStore.ts 작성
  - addItem, updateItem, deleteItem
  - 클라이언트 상태 관리
⏳ templateStore.ts 작성 (선택적)
⏳ 타입 정의 (types.ts)

Phase 4: 물리적 페이지 구축 (5-6일)

⏳ 품목 목록 페이지 (Server Component)
⏳ 품목 등록 페이지
⏳ 품목 상세 페이지
⏳ 품목 수정 페이지
⏳ BOM 관리 컴포넌트
⏳ 절곡품 전개도 입력
⏳ 파일 업로드

Phase 5: Laravel API 연동 (3-4일)

⏳ API 클라이언트 함수 작성
⏳ 에러 처리
⏳ 로딩 상태 관리
⏳ 낙관적 업데이트 (Optimistic UI)
⏳ revalidation 전략

Phase 6: 테스트 및 최적화 (2-3일)

⏳ 기능 테스트
⏳ 성능 최적화
⏳ UI/UX 개선
⏳ 버그 수정

Phase 7: 동적 템플릿 시스템 (선택적) (3-4일)

⏳ ItemPage 템플릿 렌더링
⏳ 동적 필드 생성
⏳ 조건부 표시 로직
⏳ 템플릿 관리 페이지

Phase 8: 배포 준비 (1-2일)

⏳ 프로덕션 빌드 테스트
⏳ 환경 변수 설정
⏳ 문서 최종 검토

총 예상 소요 기간: 21-30일

6.2 우선순위 매트릭스

┌─────────────────────────────────────────────────────┐
│  높은 우선순위 (즉시 시작)                           │
├─────────────────────────────────────────────────────┤
│  1. 타입 정의 (types/item.ts)                       │
│  2. API 클라이언트 (lib/api/items.ts)               │
│  3. Zustand Store (stores/itemStore.ts)             │
│  4. 품목 목록 페이지 (Server Component)              │
│  5. 품목 등록 폼 (Client Component)                  │
├─────────────────────────────────────────────────────┤
│  중간 우선순위                                       │
├─────────────────────────────────────────────────────┤
│  6. BOM 관리                                        │
│  7. 파일 업로드                                     │
│  8. 품목 수정/삭제                                  │
│  9. 검색/필터                                       │
├─────────────────────────────────────────────────────┤
│  낮은 우선순위 (나중에)                              │
├─────────────────────────────────────────────────────┤
│  10. 절곡품 전개도 (복잡도 높음)                     │
│  11. 버전 관리                                      │
│  12. 동적 템플릿 시스템                              │
│  13. 고급 검색                                      │
└─────────────────────────────────────────────────────┘

---

7. Zustand 상태 관리

7.1 itemStore 구조

// src/stores/itemStore.ts
import { create } from 'zustand';
import type { ItemMaster } from '@/types/item';

interface ItemStore {
  // State
  items: ItemMaster[];
  selectedItem: ItemMaster | null;
  isLoading: boolean;
  error: string | null;

  // Actions
  setItems: (items: ItemMaster[]) => void;
  addItem: (item: ItemMaster) => void;
  updateItem: (itemCode: string, updates: Partial<ItemMaster>) => void;
  deleteItem: (itemCode: string) => void;
  selectItem: (item: ItemMaster | null) => void;
  setLoading: (isLoading: boolean) => void;
  setError: (error: string | null) => void;

  // Helpers
  getItemByCode: (itemCode: string) => ItemMaster | undefined;
  getItemsByType: (itemType: string) => ItemMaster[];
}

export const useItemStore = create<ItemStore>((set, get) => ({
  // Initial state
  items: [],
  selectedItem: null,
  isLoading: false,
  error: null,

  // Actions
  setItems: (items) => set({ items }),

  addItem: (item) => set((state) => ({
    items: [...state.items, item],
  })),

  updateItem: (itemCode, updates) => set((state) => ({
    items: state.items.map((item) =>
      item.itemCode === itemCode ? { ...item, ...updates } : item
    ),
  })),

  deleteItem: (itemCode) => set((state) => ({
    items: state.items.filter((item) => item.itemCode !== itemCode),
  })),

  selectItem: (item) => set({ selectedItem: item }),

  setLoading: (isLoading) => set({ isLoading }),

  setError: (error) => set({ error }),

  // Helpers
  getItemByCode: (itemCode) => {
    return get().items.find((item) => item.itemCode === itemCode);
  },

  getItemsByType: (itemType) => {
    return get().items.filter((item) => item.itemType === itemType);
  },
}));

7.2 사용 예시

// Client Component에서 사용
'use client'

import { useItemStore } from '@/stores/itemStore';

export default function ItemForm() {
  const { addItem, setLoading, setError } = useItemStore();

  const handleSubmit = async (data: ItemMaster) => {
    setLoading(true);
    try {
      const newItem = await createItem(data);
      addItem(newItem); // Zustand store 업데이트
    } catch (error) {
      setError(error.message);
    } finally {
      setLoading(false);
    }
  };

  return <form onSubmit={handleSubmit}>...</form>;
}

---

8. Server/Client Components

8.1 컴포넌트 분류 기준

Server Components (기본)

• ✅ 데이터 fetching
• ✅ DB 직접 접근
• ✅ 민감한 정보 처리 (API 키 등)
• ✅ 큰 의존성 사용 (번들 크기 감소)

예시:

// src/app/[locale]/(protected)/items/page.tsx
// 'use client' 없음 = Server Component

import { fetchItems } from '@/lib/api/items';

export default async function ItemsPage() {
  const items = await fetchItems();

  return (
    <div>
      <h1>품목 목록</h1>
      <ItemListClient items={items} />
    </div>
  );
}

Client Components ('use client')

• ✅ 상호작용 (onClick, onChange 등)
• ✅ 상태 관리 (useState, useEffect)
• ✅ 브라우저 API (localStorage, window 등)
• ✅ 이벤트 리스너

예시:

// src/components/items/ItemForm.tsx
'use client'

import { useState } from 'react';
import { useForm } from 'react-hook-form';

export default function ItemForm() {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const form = useForm();

  return <form>...</form>;
}

8.2 하이브리드 패턴

// Server Component (부모)
// src/app/[locale]/(protected)/items/page.tsx
import { fetchItems } from '@/lib/api/items';
import ItemListClient from '@/components/items/ItemListClient';

export default async function ItemsPage() {
  // 서버에서 데이터 fetching
  const items = await fetchItems();

  return (
    <div>
      {/* Client Component에 데이터 전달 */}
      <ItemListClient items={items} />
    </div>
  );
}

// Client Component (자식)
// src/components/items/ItemListClient.tsx
'use client'

import type { ItemMaster } from '@/types/item';

interface Props {
  items: ItemMaster[];
}

export default function ItemListClient({ items }: Props) {
  const [selectedItem, setSelectedItem] = useState<ItemMaster | null>(null);

  return (
    <div>
      {items.map((item) => (
        <div key={item.id} onClick={() => setSelectedItem(item)}>
          {item.itemName}
        </div>
      ))}
    </div>
  );
}

8.3 품목관리 컴포넌트 분류

컴포넌트	타입	이유
items/page.tsx	Server	데이터 fetching
ItemListClient.tsx	Client	선택, 필터 상호작용
ItemForm.tsx	Client	폼 입력, 유효성 검사
BOMManager.tsx	Client	동적 추가/삭제
BendingDiagramInput.tsx	Client	Canvas 조작
FileUpload.tsx	Client	파일 선택, 업로드

---

9. 주의사항

9.1 Next.js 15 특이사항

App Router 라우팅

// ❌ 잘못된 방법 (Pages Router)
import { useRouter } from 'next/router';

// ✅ 올바른 방법 (App Router)
import { useRouter } from 'next/navigation';

다국어 지원 (next-intl)

// src/app/[locale]/(protected)/items/page.tsx
import { useTranslations } from 'next-intl';

export default function ItemsPage() {
  const t = useTranslations('Items');

  return <h1>{t('title')}</h1>; // "품목 목록"
}

쿠키 기반 인증

// Server Component에서 쿠키 자동 포함
export async function fetchItems() {
  // cookies는 자동으로 포함됨
  const response = await fetch(`${API_URL}/api/items`);
}

// Client Component에서 수동 포함
const response = await fetch('/api/items', {
  credentials: 'include', // 쿠키 포함
});

9.2 성능 최적화

1. Server Components 최대한 활용

// ✅ 서버에서 데이터 fetching (빠름)
export default async function ItemsPage() {
  const items = await fetchItems();
  return <ItemList items={items} />;
}

// ❌ 클라이언트에서 useEffect (느림)
'use client'
export default function ItemsPage() {
  useEffect(() => {
    fetchItems().then(setItems);
  }, []);
}

2. 이미지 최적화

import Image from 'next/image';

// ✅ Next.js Image 컴포넌트 사용
<Image
  src={item.bendingDiagram}
  alt="절곡품 전개도"
  width={500}
  height={300}
  priority={false}
/>

3. 동적 임포트

// 무거운 컴포넌트 지연 로딩
import dynamic from 'next/dynamic';

const BendingDiagramInput = dynamic(
  () => import('@/components/items/BendingDiagramInput'),
  { ssr: false } // 클라이언트에서만 렌더링
);

9.3 보안

CSRF 보호

// Laravel API는 Sanctum CSRF 토큰 필요
const response = await fetch(`${API_URL}/api/items`, {
  method: 'POST',
  headers: {
    'X-CSRF-TOKEN': getCsrfToken(), // Laravel Sanctum 토큰
    'Content-Type': 'application/json',
  },
  credentials: 'include',
});

환경 변수

# .env.local
NEXT_PUBLIC_API_URL=http://localhost:8000
LARAVEL_API_KEY=secret_key_here

// ✅ 서버에서만 사용
const API_KEY = process.env.LARAVEL_API_KEY; // NEXT_PUBLIC_ 없음

// ✅ 클라이언트에서도 사용
const API_URL = process.env.NEXT_PUBLIC_API_URL; // NEXT_PUBLIC_ 있음

---

10. 다음 단계

10.1 즉시 시작 가능한 작업

1. 타입 정의 작성

# src/types/item.ts
- ItemMaster 인터페이스
- BOMLine 인터페이스
- BendingDetail 인터페이스

2. API 클라이언트 작성

# src/lib/api/items.ts
- fetchItems()
- createItem()
- updateItem()
- deleteItem()

3. Zustand Store 작성

# src/stores/itemStore.ts
- 기본 상태 정의
- CRUD 액션 구현

10.2 마이그레이션 체크리스트

환경 설정:

• Laravel API URL 설정
• 인증 토큰 관리 전략
• CORS 설정 확인
• 환경 변수 설정

타입 정의:

• ItemMaster 타입
• BOMLine 타입
• BendingDetail 타입
• API 응답 타입

공통 컴포넌트:

• 폼 컴포넌트 (react-hook-form)
• 테이블 컴포넌트
• 모달 컴포넌트
• 파일 업로드 컴포넌트

페이지 구현:

• 품목 목록 (Server Component)
• 품목 등록 (Client Component)
• 품목 상세 (하이브리드)
• 품목 수정 (Client Component)

기능 구현:

• BOM 관리
• 절곡품 전개도
• 파일 업로드
• 검색/필터

---

11. 참고 자료

11.1 Next.js 15 공식 문서

• App Router
• Server Components
• Data Fetching

11.2 라이브러리 문서

• Zustand
• React Hook Form
• Zod
• next-intl

11.3 기술 스택

{
  "프론트엔드": {
    "프레임워크": "Next.js 15.5.6",
    "라이브러리": "React 19.2.0",
    "언어": "TypeScript 5",
    "스타일링": "Tailwind CSS 4",
    "상태관리": "Zustand 5.0.8",
    "폼": "react-hook-form 7.66.0",
    "검증": "Zod 4.1.12",
    "다국어": "next-intl 4.4.0"
  },
  "백엔드": {
    "프레임워크": "Laravel (PHP)",
    "데이터베이스": "PostgreSQL 또는 MySQL",
    "인증": "Laravel Sanctum",
    "스토리지": "로컬 또는 AWS S3"
  }
}

---

부록

A. 용어 정의

용어	설명
FG	Finished Goods (완제품)
PT	Parts (부품)
SM	Sub-Materials (부자재)
RM	Raw Materials (원자재)
CS	Consumables (소모품)
BOM	Bill of Materials (자재명세서)
RSC	React Server Components
SSR	Server-Side Rendering
CSR	Client-Side Rendering

B. 품목 코드 체계

형식: {업체코드}-{품목유형}-{일련번호}

예시:

• KD-FG-001: 케이디 제품 001번
• KD-PT-001: 케이디 부품 001번
• KD-RM-001: 케이디 원자재 001번

C. 문의 및 지원

마이그레이션 과정에서 질문이나 문제가 발생하면 이 문서를 참조하여 진행하세요.

세션 시작 시 전달 내용:

"품목관리 마이그레이션 작업을 계속하고 싶습니다. Next.js 15 기준 ITEM_MANAGEMENT_MIGRATION_GUIDE.md 문서를 참조해주세요."

---

문서 끝