sam-docs/plans/sub/items-plan.md

품목관리 (Items) API 연동 계획

작성일: 2026-01-08 상위 문서: construction-api-integration-plan.md 상태: ⏳ 대기

---

1. 컴포넌트 분석

1.1 파일 위치

react/src/
├── app/[locale]/(protected)/construction/order/base-info/items/
│   └── page.tsx
└── components/business/construction/item-management/
    ├── ItemManagementClient.tsx
    ├── actions.ts
    └── types.ts

1.2 현재 Mock 데이터

actions.ts 내 Mock 함수:

// getItemList에서 Mock 품목 데이터 생성
// 품목: 품목코드, 품목명, 카테고리, 규격, 단위, 단가 등

1.3 현재 함수 목록

함수명	용도	Mock 상태
getItemList	품목 목록 조회	✅ Mock
getItemStats	품목 통계 조회	✅ Mock
deleteItem	품목 삭제	✅ Mock
deleteItems	품목 일괄 삭제	✅ Mock
getCategoryOptions	카테고리 옵션 조회	✅ Mock

---

2. API 설계

2.1 엔드포인트

Method	Endpoint	용도
GET	/api/construction/items	목록 조회
GET	/api/construction/items/stats	통계 조회
GET	/api/construction/items/{id}	상세 조회
POST	/api/construction/items	등록
PUT	/api/construction/items/{id}	수정
DELETE	/api/construction/items/{id}	삭제
DELETE	/api/construction/items/bulk	일괄 삭제
POST	/api/construction/items/import	엑셀 일괄 등록

2.2 요청/응답 스키마

목록 조회 Request:

interface GetItemListParams {
  page?: number;
  size?: number;
  categoryId?: string;
  status?: ItemStatus;
  search?: string;
}

---

3. 작업 항목

3.1 Backend (API)

#	작업	상태	비고
1	ItemController 생성	⏳	시공사용
2	ItemService 생성	⏳
3	ItemFormRequest 생성	⏳
4	Item 모델 확인/수정	⏳
5	routes/api.php 등록	⏳
6	Swagger 문서 작성	⏳

3.2 Frontend (React)

#	작업	상태	비고
1	actions.ts Mock → API 변환	⏳
2	API 클라이언트 연동	⏳
3	에러 핸들링 추가	⏳
4	types.ts 정합성 확인	⏳

---

4. 타입 정의

4.1 Item 타입

interface Item {
  id: string;
  itemCode: string;
  itemName: string;
  categoryId: string;
  categoryName: string;
  specification?: string;
  unit: string;
  unitPrice: number;
  status: ItemStatus;
  description?: string;
  createdAt: string;
  updatedAt: string;
}

type ItemStatus = 'active' | 'inactive' | 'discontinued';

4.2 ItemStats 타입

interface ItemStats {
  total: number;
  active: number;
  inactive: number;
  byCategory: {
    categoryId: string;
    categoryName: string;
    count: number;
  }[];
}

---

5. 변경 이력

날짜	작업	상태
2026-01-08	문서 초안 작성	✅

---

상위 문서: construction-api-integration-plan.md