# BOM Tree 시각화 React 구현 요청

**날짜:** 2026-03-18
**요청자:** R&D실 (백엔드)
**대상:** React 프론트엔드
**API 상태:** 구현 완료 (tree 엔드포인트 존재)

---

## 변경 요약

품목관리 또는 품목기준관리에서 **BOM(Bill of Materials) 트리를 시각적으로 표시**하는 UI를 추가한다.

---

## 1. 배경

### 현재 상태

| 시스템 | BOM Tree UI | 비고 |
|--------|:----------:|------|
| MNG (Laravel) | ✅ 구현됨 | 3-panel: 검색 + 트리 + 상세 |
| 서비스 (React) | ❌ 미구현 | API는 있으나 UI 없음 |

### MNG 참고 화면

```
MNG 품목관리 (item-management)
┌──────────┬──────────────────────────┬──────────────┐
│ 품목 검색 │   BOM 트리 시각화         │ 품목 상세    │
│          │                          │              │
│ 🔍 검색   │  ▼ [FG] 제품A            │ 코드: P-001  │
│          │    ├─ [PT] 부품B (x2)    │ 이름: 제품A   │
│ · P-001  │    │  └─ [RM] SUS 철판 (x5)│ 유형: 완제품 │
│ · P-002  │    ├─ [SM] 볼트 M8 (x10) │              │
│          │    └─ [RM] EGI 판재 (x3) │              │
└──────────┴──────────────────────────┴──────────────┘
```

---

## 2. 구현 위치

### 품목관리 > 품목 상세에 BOM 탭 추가

```
품목관리 (/master-data/item-management)
└─ 품목 상세 (/master-data/item-management/{id})
   ├─ 기본정보 탭 (기존)
   ├─ BOM Tree 탭 ← 신규 추가
   └─ 기타 탭 (기존)
```

> 새 메뉴 생성 불필요. 기존 품목 상세 화면에 탭 하나 추가.
> BOM 데이터가 없는 품목(원자재 등)은 "BOM 정보가 없습니다" 표시.

---

## 3. BOM Tree UI 명세

### 3.1 트리 노드 구조

```
▼ [FG] P-001 | 제품A                          x1
  ├─ ▼ [PT] PT-001 | 가이드레일 조립품          x2
  │    ├─ [RM] 20000 | SUS1.2*1219*2438        x5
  │    ├─ [SM] 80067 | 가스켓쫄대(삼각)         x10
  │    └─ [SM] 80061 | 8인치후렌지              x2
  ├─ [RM] 30000 | EGI1.2*1219*2438             x3
  └─ [SM] 00043 | 불연지퍼                     x20
```

### 3.2 노드 요소

| 요소 | 설명 |
|------|------|
| ▼/▶ | 펼침/접힘 토글 (자식 있을 때만) |
| 유형 뱃지 | `[FG]` `[PT]` `[RM]` `[SM]` `[CS]` — 색상 구분 |
| 코드 | 품목코드 (monospace) |
| 품목명 | 품목 이름 |
| 수량 | `x2`, `x5` — 부모 대비 필요 수량 |

### 3.3 유형별 뱃지 색상

| 유형 | 코드 | 색상 | 설명 |
|------|------|------|------|
| 완제품 | FG | 🔵 blue | 최상위 제품 |
| 부품 | PT | 🟢 green | 조립 부품 (자식 가질 수 있음) |
| 원자재 | RM | 🟠 orange | 미가공 원자재 (leaf) |
| 부자재 | SM | 🟣 purple | 부자재 (leaf) |
| 소모품 | CS | ⚪ gray | 소모품 (leaf) |

### 3.4 인터랙션

| 동작 | 설명 |
|------|------|
| 노드 펼침/접힘 | 화살표 클릭 시 자식 노드 토글 |
| 전체 펼침 | 버튼 클릭 시 모든 노드 펼침 |
| 전체 접힘 | 버튼 클릭 시 루트만 표시 |
| 노드 클릭 | (선택) 해당 품목 상세 정보 표시 또는 품목 상세 페이지 이동 |

---

## 4. API 스펙 (구현 완료)

### 4.1 Items BOM Tree

```
GET /api/v1/items/{id}/bom/tree
```

**응답:**

```json
{
  "success": true,
  "data": {
    "id": 100,
    "code": "P-001",
    "name": "제품A",
    "item_type": "FG",
    "specification": "...",
    "unit": "EA",
    "quantity": 1,
    "depth": 0,
    "children": [
      {
        "id": 200,
        "code": "PT-001",
        "name": "가이드레일 조립품",
        "item_type": "PT",
        "quantity": 2,
        "depth": 1,
        "children": [
          {
            "id": 300,
            "code": "20000",
            "name": "SUS1.2*1219*2438",
            "item_type": "RM",
            "quantity": 5,
            "depth": 2,
            "children": []
          }
        ]
      },
      {
        "id": 400,
        "code": "00043",
        "name": "불연지퍼",
        "item_type": "SM",
        "quantity": 20,
        "depth": 1,
        "children": []
      }
    ]
  }
}
```

### 4.2 Products BOM Tree (제품 기반)

```
GET /api/v1/products/{id}/bom
```

**응답 구조 동일** — `type` 필드가 `PRODUCT` 또는 `MATERIAL`로 구분.

### 4.3 BOM Flat List (참고)

```
GET /api/v1/items/{id}/bom          → 1단계 자식만 (flat)
GET /api/v1/items/{id}/bom/tree     → 전체 계층 (recursive)
```

---

## 5. TypeScript 타입

```typescript
interface BomTreeNode {
  id: number;
  code: string;
  name: string;
  item_type: 'FG' | 'PT' | 'RM' | 'SM' | 'CS';
  specification?: string;
  unit?: string;
  quantity: number;
  depth: number;
  children: BomTreeNode[];
}

// 유형별 뱃지 색상 매핑
const ITEM_TYPE_COLORS: Record<string, string> = {
  FG: 'bg-blue-100 text-blue-800',
  PT: 'bg-green-100 text-green-800',
  RM: 'bg-orange-100 text-orange-800',
  SM: 'bg-purple-100 text-purple-800',
  CS: 'bg-gray-100 text-gray-800',
};

const ITEM_TYPE_LABELS: Record<string, string> = {
  FG: '완제품', PT: '부품', RM: '원자재', SM: '부자재', CS: '소모품',
};
```

---

## 6. 컴포넌트 구조 제안

```
BomTreeViewer/
├─ BomTreeViewer.tsx      # 메인 컨테이너 (API 호출 + 상태 관리)
├─ BomTreeNode.tsx        # 개별 노드 (재귀 렌더링)
├─ BomTreeToolbar.tsx     # 전체 펼침/접힘 버튼
└─ types.ts               # BomTreeNode 타입
```

### 재귀 렌더링 핵심

```tsx
function BomTreeNode({ node, level = 0 }: { node: BomTreeNode; level?: number }) {
  const [isOpen, setIsOpen] = useState(level < 2); // 2단계까지 기본 펼침
  const hasChildren = node.children.length > 0;

  return (
    <div style={{ marginLeft: level * 24 }}>
      <div className="flex items-center gap-2 py-1 hover:bg-gray-50 rounded">
        {/* 펼침/접힘 */}
        {hasChildren ? (
          <button onClick={() => setIsOpen(!isOpen)}>
            {isOpen ? '▼' : '▶'}
          </button>
        ) : <span className="w-4" />}

        {/* 유형 뱃지 */}
        <span className={`text-xs px-1.5 py-0.5 rounded ${ITEM_TYPE_COLORS[node.item_type]}`}>
          {node.item_type}
        </span>

        {/* 코드 + 이름 */}
        <span className="font-mono text-sm text-gray-500">{node.code}</span>
        <span className="text-sm">{node.name}</span>

        {/* 수량 */}
        <span className="text-sm text-blue-600 ml-auto">x{node.quantity}</span>
      </div>

      {/* 재귀: 자식 노드 */}
      {isOpen && hasChildren && node.children.map(child => (
        <BomTreeNode key={child.id} node={child} level={level + 1} />
      ))}
    </div>
  );
}
```

---

## 7. Server Action 예시

```typescript
// actions.ts
export async function getBomTree(itemId: number) {
  return fetchApi(`/items/${itemId}/bom/tree`);
}
```

---

## 작업 체크리스트

- [ ] `BomTreeViewer` 컴포넌트 생성 (재귀 트리 렌더링)
- [ ] 유형별 뱃지 색상 적용 (FG/PT/RM/SM/CS)
- [ ] 펼침/접힘 토글 구현
- [ ] 전체 펼침/접힘 버튼
- [ ] `GET /api/v1/items/{id}/bom/tree` 연동
- [ ] 품목 상세 또는 독립 페이지에 배치
- [ ] (선택) 노드 클릭 시 품목 상세 이동

---

## 참고

- MNG BOM Tree 구현: `mng/resources/views/item-management/index.blade.php` (라인 248-316)
- API Tree 빌더: `api/app/Services/Products/ProductComponentResolver.php`
- Items BOM API: `api/app/Http/Controllers/Api/V1/ItemsBomController.php`