sam-react-prod/claudedocs/item-master/[NEXT-2025-11-26] item-master-api-pending-tasks.md

품목기준관리 - 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)

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

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

독립 엔티티 API (완료)

• GET /sections - sections.list() (is_template 필터 지원)
• POST /sections - sections.createIndependent()
• POST /sections/{id}/clone - sections.clone()
• GET /sections/{id}/usage - sections.getUsage()
• GET /fields - fields.list()
• POST /fields - fields.createIndependent()
• POST /fields/{id}/clone - fields.clone()
• GET /fields/{id}/usage - fields.getUsage()
• GET /bom-items - bomItems.list()
• POST /bom-items - bomItems.createIndependent()

링크 관리 API (완료)

• POST /pages/{id}/link-section - pages.linkSection()
• DELETE /pages/{id}/unlink-section/{sectionId} - pages.unlinkSection()
• POST /sections/{id}/link-field - sections.linkField()
• DELETE /sections/{id}/unlink-field/{fieldId} - sections.unlinkField()
• GET /pages/{id}/structure - pages.getStructure()

섹션 템플릿 API 수정 (완료)

• sections.list({ is_template: true }) 로 템플릿 조회 가능

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

인터페이스 수정 (완료)

• ItemSection 인터페이스에 title, group_id, is_template, is_default, description 추가
• ItemSection.section_name → title 변경
• ItemSection.bomItems → bom_items 변경
• ItemMasterField 인터페이스에 is_common, default_value, options, validation_rules, properties 추가

Transformer 수정 (완료)

• transformSectionResponse: 새 필드 추가 (group_id, is_template, is_default, description)
• transformMasterFieldResponse: 새 필드 추가 및 속성명 통일
• field_type 변환 제거 (API와 동일한 값 사용)

TypeScript 오류 수정 (완료 ✅)

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

기능 추가 (완료 ✅)

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

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

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

2.5 섹션 탭 UI - ✅ 완료

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

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

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

---

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

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

3.1 초기화 API 연결 - ✅ 완료

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

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

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

3.3 섹션 CRUD API 연결 - ✅ 완료

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

3.4 필드 CRUD API 연결 - ✅ 완료

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

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

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

3.6 BOM CRUD API 연결 - ✅ 완료

• BOM 생성 API 연결 (addBOMItem → itemMasterApi.bomItems.create())
• BOM 수정 API 연결 (updateBOMItem → itemMasterApi.bomItems.update())
• BOM 삭제 API 연결 (deleteBOMItem → itemMasterApi.bomItems.delete())
• 독립 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 작업 시작