# 품목기준관리(ItemMaster) 프론트엔드 가이드

> 📌 **품목설정 시스템의 구조, API, 잠금 기능에 대한 프론트엔드 개발 가이드**

---

## 1. 개요

품목기준관리(ItemMaster)는 제품의 입력 화면을 구성하는 **페이지-섹션-필드** 구조를 관리하는 시스템입니다.

### 1.1 핵심 개념

| 엔티티 | 설명 | 예시 |
|--------|------|------|
| **Page** | 품목 유형별 화면 (FG, PT, SM, RM, CS) | "완제품 기본정보", "부품 상세" |
| **Section** | 페이지 내 논리적 영역 | "제품 상세", "BOM 정보" |
| **Field** | 섹션 내 입력 항목 | "제품명", "규격", "단가" |
| **BomItem** | BOM 섹션 내 부품 항목 | "부품A x 2개" |

### 1.2 아키텍처 특징

- **독립 엔티티 구조**: 섹션, 필드, BOM은 독립적으로 존재하며 재사용 가능
- **링크 테이블**: `entity_relationships`로 관계 관리
- **연결 잠금**: 중요한 구조는 잠금으로 보호 가능

---

## 2. 데이터 구조

### 2.1 엔티티 관계도

```
┌─────────────────────────────────────────────────────────────────┐
│                         ItemPage                                │
│  (id, page_name, item_type, is_active)                         │
└─────────────┬──────────────────────────────────────────────────┘
              │ entity_relationships (is_locked)
              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        ItemSection                              │
│  (id, title, type, is_template, is_default)                    │
└─────────────┬───────────────────────────────────┬──────────────┘
              │ entity_relationships              │ entity_relationships
              │ (is_locked)                       │ (is_locked)
              ▼                                   ▼
┌─────────────────────────────┐     ┌─────────────────────────────┐
│         ItemField           │     │        ItemBomItem          │
│  (id, field_name,           │     │  (id, item_code,            │
│   field_type, is_required)  │     │   item_name, quantity)      │
└─────────────────────────────┘     └─────────────────────────────┘
```

### 2.2 entity_relationships 테이블

모든 엔티티 간 관계는 `entity_relationships` 테이블로 관리됩니다.

```typescript
interface EntityRelationship {
  id: number;
  tenant_id: number;
  group_id: number;           // 1: ItemMaster
  parent_type: 'page' | 'section';
  parent_id: number;
  child_type: 'section' | 'field' | 'bom';
  child_id: number;
  order_no: number;
  is_locked: boolean;         // ⭐ 잠금 여부
  locked_by?: number;
  locked_at?: string;
  metadata?: object;
}
```

---

## 3. 잠금(Lock) 기능

### 3.1 잠금의 의미

**연결이 잠기면:**
- 해당 연결(관계)를 해제할 수 없음
- 연결된 자식 엔티티를 삭제할 수 없음
- 이름 변경, 속성 추가 등 **비구조적 수정은 허용**

```
예시: page→section 연결이 잠김
├─ ❌ 섹션을 페이지에서 분리할 수 없음
├─ ❌ 해당 섹션을 삭제할 수 없음
├─ ✅ 섹션 제목 변경 가능
└─ ✅ 섹션에 새 필드 추가 가능
```

### 3.2 잠금 상태 확인

init API 응답에 `is_locked` 필드가 포함됩니다.

```typescript
// GET /api/v1/item-master/init 응답
{
  "pages": [
    {
      "id": 1,
      "page_name": "완제품 기본정보",
      "sections": [
        {
          "id": 10,
          "title": "제품 상세",
          "is_locked": true,    // ⭐ 이 연결이 잠김
          "fields": [
            {
              "id": 100,
              "field_name": "제품명",
              "is_locked": false  // ⭐ 이 연결은 잠기지 않음
            }
          ]
        }
      ]
    }
  ]
}
```

### 3.3 프론트엔드 처리 가이드

```typescript
// 잠금 상태에 따른 UI 처리 예시
interface SectionProps {
  section: ItemSection;
  isLocked: boolean;  // 부모로부터 전달받은 잠금 상태
}

function SectionItem({ section, isLocked }: SectionProps) {
  return (
    <div className={isLocked ? 'locked-section' : ''}>
      <h3>
        {section.title}
        {isLocked && <LockIcon />}  {/* 잠금 아이콘 표시 */}
      </h3>

      {/* 잠금 시 삭제/분리 버튼 비활성화 */}
      <button
        disabled={isLocked}
        onClick={handleUnlink}
      >
        분리
      </button>

      <button
        disabled={isLocked}
        onClick={handleDelete}
      >
        삭제
      </button>

      {/* 수정은 항상 가능 */}
      <button onClick={handleEdit}>
        수정
      </button>
    </div>
  );
}
```

### 3.4 잠금 관련 에러 처리

잠금된 항목에 대해 삭제/해제 시도 시 에러가 반환됩니다.

```typescript
// 에러 응답 예시
{
  "success": false,
  "message": "잠금된 연결은 해제할 수 없습니다.",
  "error": "relationship_locked"
}

// 프론트엔드 에러 처리
try {
  await deleteSection(sectionId);
} catch (error) {
  if (error.response?.data?.error === 'entity_protected_by_locked_relationship') {
    toast.error('잠금된 연결로 보호된 항목은 삭제할 수 없습니다.');
  }
}
```

---

## 4. API 엔드포인트

### 4.1 초기화 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/v1/item-master/init` | 전체 데이터 로드 (페이지, 섹션, 커스텀탭, 단위옵션) |

**응답 구조:**
```typescript
interface InitResponse {
  pages: ItemPage[];          // 페이지 + 연결된 섹션/필드
  sections: ItemSection[];    // 모든 독립 섹션 (재사용 풀)
  customTabs: CustomTab[];
  unitOptions: UnitOption[];
}
```

### 4.2 페이지 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/v1/item-master/pages` | 페이지 목록 |
| POST | `/api/v1/item-master/pages` | 페이지 생성 |
| PUT | `/api/v1/item-master/pages/{id}` | 페이지 수정 |
| DELETE | `/api/v1/item-master/pages/{id}` | 페이지 삭제 |

### 4.3 섹션 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/v1/item-master/sections` | 독립 섹션 목록 |
| POST | `/api/v1/item-master/sections` | 독립 섹션 생성 |
| POST | `/api/v1/item-master/pages/{pageId}/sections` | 섹션 생성 + 페이지 연결 |
| PUT | `/api/v1/item-master/sections/{id}` | 섹션 수정 |
| DELETE | `/api/v1/item-master/sections/{id}` | 섹션 삭제 |
| POST | `/api/v1/item-master/sections/{id}/clone` | 섹션 복제 |
| GET | `/api/v1/item-master/sections/{id}/usage` | 사용처 조회 |

### 4.4 필드 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/v1/item-master/fields` | 독립 필드 목록 |
| POST | `/api/v1/item-master/fields` | 독립 필드 생성 |
| POST | `/api/v1/item-master/sections/{sectionId}/fields` | 필드 생성 + 섹션 연결 |
| PUT | `/api/v1/item-master/fields/{id}` | 필드 수정 |
| DELETE | `/api/v1/item-master/fields/{id}` | 필드 삭제 |
| POST | `/api/v1/item-master/fields/{id}/clone` | 필드 복제 |
| GET | `/api/v1/item-master/fields/{id}/usage` | 사용처 조회 |

### 4.5 BOM API

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/v1/item-master/bom-items` | 독립 BOM 목록 |
| POST | `/api/v1/item-master/bom-items` | 독립 BOM 생성 |
| POST | `/api/v1/item-master/sections/{sectionId}/bom-items` | BOM 생성 + 섹션 연결 |
| PUT | `/api/v1/item-master/bom-items/{id}` | BOM 수정 |
| DELETE | `/api/v1/item-master/bom-items/{id}` | BOM 삭제 |

### 4.6 순서 변경 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| PUT | `/api/v1/item-master/pages/{pageId}/sections/reorder` | 섹션 순서 변경 |
| PUT | `/api/v1/item-master/sections/{sectionId}/fields/reorder` | 필드 순서 변경 |

---

## 5. 필드 타입

### 5.1 지원 필드 타입

| field_type | 설명 | 렌더링 컴포넌트 |
|------------|------|----------------|
| `textbox` | 텍스트 입력 | `<Input type="text" />` |
| `number` | 숫자 입력 | `<Input type="number" />` |
| `dropdown` | 드롭다운 선택 | `<Select />` |
| `checkbox` | 체크박스 | `<Checkbox />` |
| `date` | 날짜 선택 | `<DatePicker />` |
| `textarea` | 장문 텍스트 | `<Textarea />` |

### 5.2 필드 속성

```typescript
interface ItemField {
  id: number;
  field_name: string;
  field_type: FieldType;
  order_no: number;
  is_required: boolean;
  is_locked?: boolean;        // init 응답에 포함
  default_value?: string;
  placeholder?: string;
  display_condition?: object; // 조건부 표시
  validation_rules?: object;  // 유효성 검사 규칙
  options?: object;           // dropdown 옵션 등
  properties?: object;        // 추가 설정
  category?: string;
  description?: string;
  is_common?: boolean;
}
```

---

## 6. 상태 관리 권장 패턴

### 6.1 Zustand Store 예시

```typescript
interface ItemMasterStore {
  // 데이터
  pages: ItemPage[];
  sections: ItemSection[];
  customTabs: CustomTab[];
  unitOptions: UnitOption[];

  // 상태
  isLoading: boolean;
  selectedPageId: number | null;
  selectedSectionId: number | null;

  // 액션
  fetchInit: () => Promise<void>;
  addSection: (pageId: number, data: CreateSectionDTO) => Promise<void>;
  updateSection: (id: number, data: UpdateSectionDTO) => Promise<void>;
  deleteSection: (id: number) => Promise<void>;
  reorderSections: (pageId: number, items: ReorderItem[]) => Promise<void>;

  // 유틸리티
  getSectionsByPage: (pageId: number) => ItemSection[];
  isEntityLocked: (entityType: string, entityId: number) => boolean;
}
```

### 6.2 잠금 상태 캐싱

```typescript
// 잠금 상태를 Map으로 캐싱
const lockStatusMap = new Map<string, boolean>();

function buildLockStatusMap(pages: ItemPage[]) {
  pages.forEach(page => {
    page.sections?.forEach(section => {
      lockStatusMap.set(`section:${section.id}`, section.is_locked);

      section.fields?.forEach(field => {
        lockStatusMap.set(`field:${field.id}`, field.is_locked);
      });

      section.bom_items?.forEach(bom => {
        lockStatusMap.set(`bom:${bom.id}`, bom.is_locked);
      });
    });
  });
}

function isLocked(entityType: string, entityId: number): boolean {
  return lockStatusMap.get(`${entityType}:${entityId}`) || false;
}
```

---

## 7. 주의사항

### 7.1 삭제 시 동작
- **페이지 삭제**: 연결된 섹션/필드는 삭제되지 않고 관계만 해제
- **섹션 삭제**: 연결된 필드/BOM은 삭제되지 않고 관계만 해제
- **잠금된 연결이 있으면**: 삭제/해제 불가

### 7.2 복제(Clone) 시 동작
- 섹션 복제: 섹션 + 필드 + BOM 모두 복제
- 필드 복제: 필드만 복제
- 복제된 항목은 독립 엔티티로 생성됨

### 7.3 순서 변경
- Drag & Drop 후 reorder API 호출 필요
- `items` 배열에 `{id, order_no}` 형태로 전달

---

## 8. 변경 이력

| 날짜 | 버전 | 변경 내용 |
|------|------|----------|
| 2025-11-27 | 1.0.0 | 잠금(Lock) 기능 추가 |
| 2025-11-26 | 0.9.0 | 독립 엔티티 아키텍처 적용 |
| 2025-11-20 | 0.8.0 | entity_relationships 링크 테이블 도입 |