# BOM 트리 3단계 그룹 표시 — React 프론트엔드 구현 요청서

> **작성일**: 2026-03-18
> **요청자**: R&D실 (백엔드 API 개발 완료)
> **대상**: React 프론트엔드 개발자
> **배포 상태**: 개발서버 배포 완료 (`api.dev.codebridge-x.com`)

---

## 1. 작업 개요

품목관리 > 제품상세 화면의 "부품 구성 (BOM)" 섹션을 **플랫 테이블**에서 **카테고리별 접힘/펼침 그룹 트리**로 교체한다.

**현재**: 17건의 부품이 번호순 테이블로 나열
**변경**: 주자재/모터/제어기/절곡품/부자재/검사비 6개 그룹으로 묶어서 트리 표시

> API가 3단계 트리 구조를 이미 반환하므로, 프론트엔드는 렌더링만 변경하면 된다.

---

## 2. 화면 설계

### 2.1 현재 화면 (교체 대상)

```
부품 구성 (BOM)                    총 17개 품목
┌────┬──────────────────────┬──────────────────┬────────┬──────┐
│ 번호 │ 품목코드              │ 품목명           │  수량  │ 단위 │
├────┼──────────────────────┼──────────────────┼────────┼──────┤
│  1 │ EST-RAW-슬랫-방화     │ 스크린 실리카     │ 10.65  │ m²   │
│  2 │ EST-MOTOR-220V-150K  │ 모터 150K(S)     │     1  │ EA   │
│ .. │ ...                   │ ...              │    ... │ ...  │
│ 17 │ EST-INSPECTION        │ 검사비           │     1  │ EA   │
└────┴──────────────────────┴──────────────────┴────────┴──────┘
```

### 2.2 변경 후 화면

```
부품 구성 (BOM)                    총 17개 품목 · 6개 그룹

▼ 주자재 (1건)
  │ PT  EST-RAW-슬랫-방화      스크린 실리카         x10.65  m²

▼ 모터 (1건)
  │ PT  EST-MOTOR-220V-150K   모터 150K(S) (220V)   x1     EA

▼ 제어기 (1건)
  │ PT  EST-CTRL-노출형        제어기 노출형          x1     EA

▼ 절곡품 (9건)
  │ PT  BD-케이스-500*380      케이스 500*380        x3.22   m
  │ PT  BD-케이스용-연기차단... 케이스용 연기차단재    x3.22   m
  │ PT  BD-마구리-505*385      마구리 505*385        x1     EA
  │ PT  BD-가이드레일-KSS02... 가이드레일 KSS02...   x6.5    m
  │ PT  BD-가이드레일용-연기... 가이드레일용 연기...   x6.5    m
  │ PT  00035                  철재용하장바(SUS)3000  x3      m
  │ PT  BD-L-BAR-KSS02-17*60  L-BAR KSS02 17*60    x3.22   m
  │ PT  BD-보강평철-50          보강평철 50           x3.22   m
  │ PT  90201                  KD환봉(30파이)        x1     EA

▶ 부자재 (4건)                                ← 접힌 상태 (클릭하면 펼침)

▼ 검사비 (1건)
  │ PT  EST-INSPECTION         검사비               x1     Dev
```

### 2.3 동작 설명

| 동작 | 설명 |
|------|------|
| 카테고리 헤더 클릭 | 하위 품목 접힘/펼침 토글 |
| 기본 상태 | 모든 카테고리 펼침 |
| 품목 행 클릭 | 기존과 동일 (해당 품목 상세 표시 등) |

---

## 3. API 엔드포인트

### 3.1 BOM 트리 조회 — `GET /api/v1/items/{id}/bom/tree`

기존 엔드포인트. 인증: `X-API-KEY` + `Bearer Token` (기존과 동일).

**응답 예시** (`GET /api/v1/items/15531/bom/tree`):

```json
{
  "success": true,
  "message": "조회 완료",
  "data": {
    "id": 15531,
    "code": "FG-KSS02-측면형-SUS",
    "name": "KSS02 스크린 SUS마감 측면형",
    "item_type": "FG",
    "unit": "EA",
    "depth": 1,
    "children": [
      {
        "id": 0,
        "code": "",
        "name": "주자재",
        "item_type": "CAT",
        "unit": "",
        "depth": 2,
        "count": 1,
        "children": [
          {
            "id": 15657,
            "code": "EST-RAW-슬랫-방화",
            "name": "스크린 실리카",
            "item_type": "PT",
            "unit": "EA",
            "depth": 3,
            "quantity": 10.65,
            "children": []
          }
        ]
      },
      {
        "id": 0,
        "code": "",
        "name": "모터",
        "item_type": "CAT",
        "unit": "",
        "depth": 2,
        "count": 1,
        "children": [
          {
            "id": 15627,
            "code": "EST-MOTOR-220V-150K",
            "name": "모터 150K(S) (220V)",
            "item_type": "PT",
            "unit": "EA",
            "depth": 3,
            "quantity": 1,
            "children": []
          }
        ]
      },
      {
        "id": 0,
        "code": "",
        "name": "절곡품",
        "item_type": "CAT",
        "unit": "",
        "depth": 2,
        "count": 9,
        "children": [
          {
            "id": 15578,
            "code": "BD-케이스-500*380",
            "name": "케이스 500*380",
            "item_type": "PT",
            "unit": "m",
            "depth": 3,
            "quantity": 3.22,
            "children": []
          }
        ]
      },
      {
        "id": 0,
        "code": "",
        "name": "부자재",
        "item_type": "CAT",
        "count": 4,
        "children": ["...4개 PT 품목..."]
      },
      {
        "id": 0,
        "code": "",
        "name": "검사비",
        "item_type": "CAT",
        "count": 1,
        "children": ["...1개 PT 품목..."]
      }
    ]
  }
}
```

### 3.2 응답 구조 설명

| 필드 | 타입 | 설명 |
|------|------|------|
| `item_type` | `"FG"` / `"CAT"` / `"PT"` | FG=루트 완제품, **CAT=카테고리 그룹 (가상 노드)**, PT=실제 부품 |
| `id` | number | CAT 노드는 `0` (가상), 나머지는 실제 품목 ID |
| `count` | number | CAT 노드에만 존재 — 하위 품목 건수 |
| `quantity` | number | PT 노드에만 존재 — 소요 수량 |
| `children` | array | 하위 노드 배열 (재귀) |
| `code` | string | CAT 노드는 빈 문자열, PT 노드는 품목코드 |

### 3.3 노드 판별 로직

```
item_type === "CAT"  →  카테고리 헤더로 렌더링 (접힘/펼침, count 표시)
item_type !== "CAT"  →  품목 행으로 렌더링 (코드, 품목명, 수량, 단위)
```

---

## 4. 구현 가이드

### 4.1 데이터 로드

```typescript
// FG 품목 상세 페이지에서 BOM 트리 로드
const [bomTree, setBomTree] = useState<BomTreeNode | null>(null);

useEffect(() => {
  if (item?.id && item?.itemType === 'FG') {
    fetch(`/api/proxy/items/${item.id}/bom/tree`)
      .then(res => res.json())
      .then(data => setBomTree(data.data));
  }
}, [item?.id]);
```

### 4.2 타입 정의

```typescript
interface BomTreeNode {
  id: number;
  code: string;
  name: string;
  item_type: 'FG' | 'CAT' | 'PT' | string;
  unit: string;
  depth: number;
  count?: number;      // CAT 노드 — 하위 품목 건수
  quantity?: number;    // PT 노드 — 소요 수량
  children: BomTreeNode[];
}
```

### 4.3 렌더링 컴포넌트

```tsx
function BomTreeNode({ node }: { node: BomTreeNode }) {
  const [isOpen, setIsOpen] = useState(true);
  const isCategory = node.item_type === 'CAT';
  const hasChildren = node.children && node.children.length > 0;

  return (
    <div className={isCategory ? '' : 'ml-6'}>
      {/* 노드 행 */}
      <div
        className={`flex items-center gap-2 py-1.5 px-3 rounded ${
          isCategory
            ? 'bg-gray-50 hover:bg-gray-100 cursor-pointer'
            : 'hover:bg-gray-50'
        }`}
        onClick={() => hasChildren && setIsOpen(!isOpen)}
      >
        {/* 토글 아이콘 */}
        {hasChildren && (
          isOpen
            ? <ChevronDown className="h-4 w-4 text-gray-400 shrink-0" />
            : <ChevronRight className="h-4 w-4 text-gray-400 shrink-0" />
        )}
        {!hasChildren && <span className="w-4" />}

        {isCategory ? (
          /* 카테고리 헤더 */
          <>
            <span className="text-sm font-semibold text-gray-700">{node.name}</span>
            <Badge variant="outline" className="text-xs">{node.count}건</Badge>
          </>
        ) : (
          /* 품목 행 */
          <>
            <Badge className="text-xs">{node.item_type}</Badge>
            <code className="text-xs text-gray-400">{node.code}</code>
            <span className="text-sm text-gray-700 flex-1 truncate">{node.name}</span>
            {node.quantity && (
              <span className="text-xs font-medium text-blue-600 ml-auto">
                x{node.quantity}
              </span>
            )}
            <span className="text-xs text-gray-400">{node.unit}</span>
          </>
        )}
      </div>

      {/* 하위 노드 (접힘/펼침) */}
      {isOpen && hasChildren && (
        <div className={isCategory ? 'border-l-2 border-gray-200 ml-2' : ''}>
          {node.children.map((child, i) => (
            <BomTreeNode key={child.id || `cat-${i}`} node={child} />
          ))}
        </div>
      )}
    </div>
  );
}
```

### 4.4 Card 섹션 교체

기존 `ItemDetailClient.tsx` 557~611줄의 BOM Card를 아래로 교체:

```tsx
{item.itemType === 'FG' && bomTree && bomTree.children?.length > 0 && (
  <Card>
    <CardHeader>
      <div className="flex items-center justify-between">
        <CardTitle className="flex items-center gap-2">
          <Package className="h-5 w-5" />
          부품 구성 (BOM)
        </CardTitle>
        <Badge variant="outline" className="bg-blue-50 text-blue-700">
          총 {bomTree.children.reduce((sum, cat) => sum + (cat.count || 0), 0)}개 품목
          · {bomTree.children.length}개 그룹
        </Badge>
      </div>
    </CardHeader>
    <CardContent>
      {bomTree.children.map((catNode, i) => (
        <BomTreeNode key={i} node={catNode} />
      ))}
    </CardContent>
  </Card>
)}
```

---

## 5. 수정 대상 파일

| 파일 | 변경 내용 |
|------|----------|
| `src/components/items/ItemDetailClient.tsx` | 557~611줄 BOM Card → 트리 컴포넌트로 교체 |
| `src/types/item.ts` (선택) | `BomTreeNode` 타입 추가 |

---

## 6. 테스트 방법

1. 개발서버(`dev.codebridge-x.com`) 접속
2. 품목관리 > FG 품목 선택 (예: `KSS02 스크린 SUS마감 측면형`)
3. BOM 섹션에서 카테고리 그룹 표시 확인
4. 각 카테고리 헤더 클릭 → 접힘/펼침 동작 확인
5. MNG(`admin.codebridge-x.com`) > 품목관리에서 동일 품목의 BOM 탭과 비교

### 테스트 데이터

tenant `프론트_테스트회사`의 FG 품목 18건에 BOM 데이터가 등록되어 있다.

| 품목코드 | 품목명 | BOM 건수 |
|---------|--------|---------|
| FG-KSS01-벽면형-SUS | KSS01 스크린 SUS마감 벽면형 | 17건 |
| FG-KSS02-측면형-SUS | KSS02 스크린 SUS마감 측면형 | 17건 |
| FG-KQTS01-벽면형-SUS | KQTS01 철재 SUS마감 벽면형 | 17건 |
| ... (총 18개 FG) | | |

---

## 7. 체크리스트

- [ ] `GET /api/v1/items/{id}/bom/tree` 호출하여 3단계 트리 데이터 로드
- [ ] `item_type === "CAT"` 노드를 카테고리 헤더로 렌더링
- [ ] 카테고리 헤더에 건수(`count`) Badge 표시
- [ ] 카테고리 클릭 시 접힘/펼침 토글
- [ ] 품목 노드에 타입 뱃지, 코드, 품목명, 수량, 단위 표시
- [ ] FG 품목에서만 BOM 섹션 표시 (기존 조건 유지)
- [ ] BOM 데이터 없는 품목은 섹션 미표시

---

## 관련 문서

- `changes/20260318_item-management-bom-tree.md` — MNG BOM 트리 3단계 구현 완료 내역

---

**최종 업데이트**: 2026-03-18
