# 품목기준관리 - API 연동 작업 체크리스트

**작성일**: 2025-11-26
**상태**: ✅ Phase 3 완료
**마지막 업데이트**: 2025-11-26 API 연결 구현 완료 (Phase 3 ✅)

---

## 1. 구조 변경 사항

- `section_templates` 테이블 삭제 → `item_sections.is_template=true`로 통합
- `section_name` → `title`로 통일 (API와 동일)
- `bomItems` → `bom_items`로 통일 (API와 동일)
- `field_type`: API와 Frontend가 동일한 값 사용 ('textbox', 'number', 'dropdown' 등)

---

## 2. API 연동 체크리스트

### 2.1 타입 정의 (src/types/item-master-api.ts)

- [x] ItemSectionResponse에 is_template, is_default, description, group_id 추가
- [x] IndependentSectionRequest 추가
- [x] IndependentFieldRequest 추가
- [x] IndependentBomItemRequest 추가
- [x] SectionUsageResponse 추가
- [x] FieldUsageResponse 추가
- [x] LinkSectionRequest 추가
- [x] LinkFieldRequest 추가
- [x] PageStructureResponse 추가
- [x] MasterFieldResponse에 is_common, default_value, options 추가

### 2.2 API 클라이언트 (src/lib/api/item-master.ts) - ✅ 완료

#### 독립 엔티티 API (완료)
- [x] `GET /sections` - `sections.list()` (is_template 필터 지원)
- [x] `POST /sections` - `sections.createIndependent()`
- [x] `POST /sections/{id}/clone` - `sections.clone()`
- [x] `GET /sections/{id}/usage` - `sections.getUsage()`
- [x] `GET /fields` - `fields.list()`
- [x] `POST /fields` - `fields.createIndependent()`
- [x] `POST /fields/{id}/clone` - `fields.clone()`
- [x] `GET /fields/{id}/usage` - `fields.getUsage()`
- [x] `GET /bom-items` - `bomItems.list()`
- [x] `POST /bom-items` - `bomItems.createIndependent()`

#### 링크 관리 API (완료)
- [x] `POST /pages/{id}/link-section` - `pages.linkSection()`
- [x] `DELETE /pages/{id}/unlink-section/{sectionId}` - `pages.unlinkSection()`
- [x] `POST /sections/{id}/link-field` - `sections.linkField()`
- [x] `DELETE /sections/{id}/unlink-field/{fieldId}` - `sections.unlinkField()`
- [x] `GET /pages/{id}/structure` - `pages.getStructure()`

#### 섹션 템플릿 API 수정 (완료)
- [x] `sections.list({ is_template: true })` 로 템플릿 조회 가능

### 2.3 Context 업데이트 (src/contexts/ItemMasterContext.tsx)

#### 인터페이스 수정 (완료)
- [x] ItemSection 인터페이스에 title, group_id, is_template, is_default, description 추가
- [x] ItemSection.section_name → title 변경
- [x] ItemSection.bomItems → bom_items 변경
- [x] ItemMasterField 인터페이스에 is_common, default_value, options, validation_rules, properties 추가

#### Transformer 수정 (완료)
- [x] transformSectionResponse: 새 필드 추가 (group_id, is_template, is_default, description)
- [x] transformMasterFieldResponse: 새 필드 추가 및 속성명 통일
- [x] field_type 변환 제거 (API와 동일한 값 사용)

#### TypeScript 오류 수정 (완료 ✅)
- [x] bomItems → bom_items 참조 수정 (addBOMItem, updateBOMItem, deleteBOMItem)
- [x] transformers.ts FIELD_TYPE_MAP 오류 수정
- [x] transformPageResponse: order_no, description 추가
- [x] ItemPageResponse: order_no, description 추가
- [x] 전체 타입 검증 완료

#### 기능 추가 (완료 ✅)
- [x] 독립 섹션/필드/BOM 상태 추가
- [x] 링크/언링크 메서드 추가
- [x] 사용처 조회 메서드 추가
- [x] 섹션 템플릿 로직 수정 (is_template 필터)
- [x] 복제 기능 (cloneSection, cloneField)

### 2.4 계층구조(페이지) 탭 UI - ✅ 완료

- [x] 섹션 불러오기 다이얼로그 (ImportSectionDialog.tsx)
- [x] 필드 불러오기 다이얼로그 (ImportFieldDialog.tsx)
- [x] 불러오기 버튼 추가 (HierarchyTab)
- [x] 사용처 표시 UI (다이얼로그 내 Usage Info Panel)

### 2.5 섹션 탭 UI - ✅ 완료

- [x] 섹션 복제(Clone) 버튼 추가 (SectionsTab.tsx)
- [x] 필드 불러오기(Import Field) 버튼 추가 (SectionsTab.tsx)
- [x] ItemMasterDataManagement에서 props 연결 (handleCloneSection, setIsImportFieldDialogOpen)
- [x] TypeScript 오류 수정:
  - section_name → title 변경 (useSectionManagement, useTemplateManagement, DraggableSection, FieldDrawer, ConditionalDisplayUI)
  - bomItems → bom_items 변경 (hooks 파일들)
  - is_template, is_default 필수 속성 추가

### 2.6 마스터 항목 탭 UI - ✅ 완료

- [x] 기본 CRUD UI 구현됨 (MasterFieldTab/index.tsx)
- [x] 필드 타입 배지 표시
- [x] 필수 여부, 카테고리, 속성 타입 배지 표시
- [x] 옵션 목록 표시

---

## 3. Phase 3: API 연결 구현 - ✅ 완료

> **분석 결과**: 모든 API 연결이 이미 Context에서 완료되어 있습니다.

### 3.1 초기화 API 연결 - ✅ 완료

- [x] `/v1/item-master/init` API 호출 구현 (ItemMasterDataManagement.tsx:301-361)
- [x] Context `loadItemPages`, `loadSectionTemplates`, `loadItemMasterFields` 메서드 연결
- [x] 로딩 상태 관리 UI (LoadingSpinner, ErrorMessage)

### 3.2 페이지 CRUD API 연결 - ✅ 완료

- [x] 페이지 생성 API 연결 (`addItemPage` → `itemMasterApi.pages.create()`)
- [x] 페이지 수정 API 연결 (`updateItemPage` → `itemMasterApi.pages.update()`)
- [x] 페이지 삭제 API 연결 (`deleteItemPage` → `itemMasterApi.pages.delete()`)
- [x] 페이지 순서 변경 API 연결 (`reorderPages` → `itemMasterApi.pages.reorder()`)
- [x] 섹션 링크/언링크 API 연결 (`linkSectionToPage`, `unlinkSectionFromPage`)

### 3.3 섹션 CRUD API 연결 - ✅ 완료

- [x] 섹션 생성 API 연결 (`addSectionToPage` → `itemMasterApi.sections.create()`)
- [x] 섹션 수정 API 연결 (`updateSection` → `itemMasterApi.sections.update()`)
- [x] 섹션 삭제/언링크 API 연결 (`deleteSection` → `itemMasterApi.sections.delete()`)
- [x] 섹션 순서 변경 API 연결 (`reorderSections` → `itemMasterApi.sections.reorder()`)
- [x] 독립 섹션 생성 (`createIndependentSection` → `itemMasterApi.sections.createIndependent()`)
- [x] 섹션 복제 (`cloneSection` → `itemMasterApi.sections.clone()`)
- [x] 섹션 사용처 조회 (`getSectionUsage` → `itemMasterApi.sections.getUsage()`)
- [x] 필드 링크/언링크 API 연결 (`linkFieldToSection`, `unlinkFieldFromSection`)

### 3.4 필드 CRUD API 연결 - ✅ 완료

- [x] 필드 생성 API 연결 (`addFieldToSection` → `itemMasterApi.fields.create()`)
- [x] 필드 수정 API 연결 (`updateField` → `itemMasterApi.fields.update()`)
- [x] 필드 삭제/언링크 API 연결 (`deleteField` → `itemMasterApi.fields.delete()`)
- [x] 필드 순서 변경 API 연결 (`reorderFields` → `itemMasterApi.fields.reorder()`)
- [x] 독립 필드 생성 (`createIndependentField` → `itemMasterApi.fields.createIndependent()`)
- [x] 필드 복제 (`cloneField` → `itemMasterApi.fields.clone()`)
- [x] 필드 사용처 조회 (`getFieldUsage` → `itemMasterApi.fields.getUsage()`)

### 3.5 마스터 필드 CRUD API 연결 - ✅ 완료

- [x] 마스터 필드 생성 API 연결 (`addItemMasterField` → `itemMasterApi.masterFields.create()`)
- [x] 마스터 필드 수정 API 연결 (`updateItemMasterField` → `itemMasterApi.masterFields.update()`)
- [x] 마스터 필드 삭제 API 연결 (`deleteItemMasterField` → `itemMasterApi.masterFields.delete()`)

### 3.6 BOM CRUD API 연결 - ✅ 완료

- [x] BOM 생성 API 연결 (`addBOMItem` → `itemMasterApi.bomItems.create()`)
- [x] BOM 수정 API 연결 (`updateBOMItem` → `itemMasterApi.bomItems.update()`)
- [x] BOM 삭제 API 연결 (`deleteBOMItem` → `itemMasterApi.bomItems.delete()`)
- [x] 독립 BOM 생성 (`createIndependentBomItem` → `itemMasterApi.bomItems.createIndependent()`)

### Hooks → Context 연결 현황 - ✅ 완료

| Hook | Context 함수 | 상태 |
|------|-------------|------|
| usePageManagement | `addItemPage`, `updateItemPage`, `deleteItemPage` | ✅ |
| useSectionManagement | `addSectionToPage`, `updateSection`, `deleteSection` | ✅ |
| useFieldManagement | `addFieldToSection`, `updateField`, `deleteField` | ✅ |
| useMasterFieldManagement | `addItemMasterField`, `updateItemMasterField`, `deleteItemMasterField` | ✅ |

---

## 4. 삭제 vs 연결해제 정리

```
[계층구조 탭에서]
├─ 페이지 삭제 → 실제 삭제 (Cascade)
├─ 섹션 제거 → 연결만 끊기 (unlink), 섹션 데이터는 유지
└─ 항목 제거 → 연결만 끊기 (unlink), 항목 데이터는 유지

[섹션 탭에서]
├─ 섹션 삭제 → 실제 삭제 (Cascade)
└─ 항목 삭제 → 실제 삭제

[마스터 항목 탭에서]
└─ 마스터 항목 삭제 → 실제 삭제
```

---

## 4. 데이터 연결 구조

```
독립 필드 (fields, section_id=null)
    │
    ├──[link-field]──→ 섹션에 연결
    │                    ↓
독립 섹션 (sections, page_id=null)
    │
    ├──[link-section]──→ 페이지에 연결
    │                      ↓
페이지 (pages) = 품목유형별 필드 구성
```

---

## 5. 핵심 개념

> **"페이지"는 실제 URL 경로가 아니라, 품목유형별 필드 구성 템플릿이다!**

```
품목기준관리의 "페이지"
  = 품목유형(FG, PT, SM, RM, CS)별로
  = 품목 등록 시 어떤 섹션/필드를 보여줄지 정의하는 템플릿
```

---

## 6. 참고 문서

- `claudedocs/[ANALYSIS-2025-11-21] item-master-notes.md` - 이전 API 문서
- `claudedocs/[ANALYSIS-2025-11-26] item-master-notes.md` - 신규 API 문서
- `~/Desktop/코브라브릿지백엔드문서/[API-2025-11-26] item-master-api-changes.md` - API 변경사항

---

**마지막 업데이트**: 2025-11-26 작업 시작
