# BOM 관리 시스템 개발 현황

## 1. 개요

BOM(Bill of Materials) 관리 시스템은 제품의 구성 부품을 계층적으로 관리하는 기능입니다.
V2 컴포넌트 기반으로 구현되어 있으며, 설정 패널을 통해 모든 기능을 동적으로 구성할 수 있습니다.

---

## 2. 아키텍처

### 2.1 전체 구조

```
[프론트엔드]                           [백엔드]                      [데이터베이스]
v2-bom-tree (트리 뷰)  ──── /api/bom ────── bomService.ts ────── bom, bom_detail
v2-bom-item-editor     ──── /api/table-management ──────────── bom_history, bom_version
V2BomTreeConfigPanel   (설정 패널)
```

### 2.2 관련 파일 목록

#### 프론트엔드

| 파일 | 설명 |
|------|------|
| `frontend/lib/registry/components/v2-bom-tree/BomTreeComponent.tsx` | BOM 트리/레벨 뷰 메인 컴포넌트 |
| `frontend/lib/registry/components/v2-bom-tree/BomVersionModal.tsx` | 버전 관리 모달 |
| `frontend/lib/registry/components/v2-bom-tree/BomHistoryModal.tsx` | 이력 관리 모달 |
| `frontend/lib/registry/components/v2-bom-tree/BomDetailEditModal.tsx` | BOM 항목 수정 모달 |
| `frontend/lib/registry/components/v2-bom-tree/BomTreeRenderer.tsx` | 트리 렌더러 |
| `frontend/lib/registry/components/v2-bom-tree/index.ts` | 컴포넌트 정의 (v2-bom-tree) |
| `frontend/components/v2/config-panels/V2BomTreeConfigPanel.tsx` | BOM 트리 설정 패널 |
| `frontend/lib/registry/components/v2-bom-item-editor/BomItemEditorComponent.tsx` | BOM 항목 편집기 (에디터 모드) |

#### 백엔드

| 파일 | 설명 |
|------|------|
| `backend-node/src/routes/bomRoutes.ts` | BOM API 라우트 정의 |
| `backend-node/src/controllers/bomController.ts` | BOM 컨트롤러 (이력/버전) |
| `backend-node/src/services/bomService.ts` | BOM 서비스 (비즈니스 로직) |

#### 데이터베이스

| 파일 | 설명 |
|------|------|
| `db/migrations/062_create_bom_history_version_tables.sql` | 이력/버전 테이블 DDL |

---

## 3. 데이터베이스 스키마

### 3.1 bom (BOM 헤더)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | VARCHAR (UUID) | PK |
| item_id | VARCHAR | 완제품 품목 ID (item_info FK) |
| bom_name | VARCHAR | BOM 명칭 |
| version | VARCHAR | 현재 사용중인 버전명 |
| revision | VARCHAR | 차수 |
| base_qty | NUMERIC | 기준수량 |
| unit | VARCHAR | 단위 |
| remark | TEXT | 비고 |
| company_code | VARCHAR | 회사 코드 (멀티테넌시) |

### 3.2 bom_detail (BOM 상세 - 자식 품목)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | VARCHAR (UUID) | PK |
| bom_id | VARCHAR | BOM 헤더 FK |
| parent_detail_id | VARCHAR | 부모 detail FK (NULL = 1레벨) |
| child_item_id | VARCHAR | 자식 품목 ID (item_info FK) |
| quantity | NUMERIC | 구성수량 (소요량) |
| unit | VARCHAR | 단위 |
| process_type | VARCHAR | 공정구분 (제조/외주 등) |
| loss_rate | NUMERIC | 손실율 |
| level | INTEGER | 레벨 |
| base_qty | NUMERIC | 기준수량 |
| revision | VARCHAR | 차수 |
| remark | TEXT | 비고 |
| company_code | VARCHAR | 회사 코드 |

### 3.3 bom_history (BOM 이력)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | VARCHAR (UUID) | PK |
| bom_id | VARCHAR | BOM 헤더 FK |
| revision | VARCHAR | 차수 |
| version | VARCHAR | 버전 |
| change_type | VARCHAR | 변경구분 (등록/수정/추가/삭제) |
| change_description | TEXT | 변경내용 |
| changed_by | VARCHAR | 변경자 |
| changed_date | TIMESTAMP | 변경일시 |
| company_code | VARCHAR | 회사 코드 |

### 3.4 bom_version (BOM 버전)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | VARCHAR (UUID) | PK |
| bom_id | VARCHAR | BOM 헤더 FK |
| version_name | VARCHAR | 버전명 (1.0, 2.0 ...) |
| revision | INTEGER | 생성 시점의 차수 |
| status | VARCHAR | 상태 (developing / active / inactive) |
| snapshot_data | JSONB | 스냅샷 (bom 헤더 + bom_detail 전체) |
| created_by | VARCHAR | 생성자 |
| created_date | TIMESTAMP | 생성일시 |
| company_code | VARCHAR | 회사 코드 |

---

## 4. API 명세

### 4.1 이력 API

| Method | Path | 설명 |
|--------|------|------|
| GET | `/api/bom/:bomId/history` | 이력 목록 조회 |
| POST | `/api/bom/:bomId/history` | 이력 등록 |

**Query Params**: `tableName` (설정 패널에서 지정한 이력 테이블명, 기본값: `bom_history`)

### 4.2 버전 API

| Method | Path | 설명 |
|--------|------|------|
| GET | `/api/bom/:bomId/versions` | 버전 목록 조회 |
| POST | `/api/bom/:bomId/versions` | 신규 버전 생성 |
| POST | `/api/bom/:bomId/versions/:versionId/load` | 버전 불러오기 (데이터 복원) |
| POST | `/api/bom/:bomId/versions/:versionId/activate` | 버전 사용 확정 |
| DELETE | `/api/bom/:bomId/versions/:versionId` | 버전 삭제 |

**Body/Query**: `tableName`, `detailTable` (설정 패널에서 지정한 테이블명)

---

## 5. 버전 관리 구조

### 5.1 핵심 원리

**각 버전은 생성 시점의 BOM 전체 구조(헤더 + 모든 디테일)를 JSONB 스냅샷으로 저장합니다.**

```
버전 1.0 (active)
  └─ snapshot_data: { bom: {...}, details: [{...}, {...}, ...] }

버전 2.0 (developing)
  └─ snapshot_data: { bom: {...}, details: [{...}, {...}, ...] }

버전 3.0 (inactive)
  └─ snapshot_data: { bom: {...}, details: [{...}, {...}, ...] }
```

### 5.2 버전 상태 (status)

| 상태 | 설명 |
|------|------|
| `developing` | 개발중 - 신규 생성 시 기본 상태 |
| `active` | 사용중 - "사용 확정" 후 운영 상태 |
| `inactive` | 사용중지 - 이전에 active였다가 다른 버전이 확정된 경우 |

### 5.3 버전 워크플로우

```
[현재 BOM 데이터]
      │
      ▼
신규 버전 생성 ───► 버전 N.0 (status: developing)
                      │
                      ├── 불러오기: 해당 스냅샷의 데이터로 현재 BOM을 복원
                      │              (status 변경 없음, BOM 헤더 version 변경 없음)
                      │
                      ├── 사용 확정: status → active, 
                      │              기존 active 버전 → inactive,
                      │              BOM 헤더의 version 필드 갱신
                      │
                      └── 삭제: active 상태가 아닌 경우만 삭제 가능
```

### 5.4 불러오기 vs 사용 확정

| 동작 | 불러오기 (Load) | 사용 확정 (Activate) |
|------|----------------|---------------------|
| BOM 데이터 복원 | O (detail 전체 교체) | X |
| BOM 헤더 업데이트 | O (base_qty, unit 등) | version 필드만 |
| 버전 status 변경 | X | active로 변경 |
| 기존 active 비활성화 | X | O (→ inactive) |
| BOM 목록 새로고침 | O (refreshTable) | O (refreshTable) |

---

## 6. 설정 패널 구성

`V2BomTreeConfigPanel.tsx`에서 아래 항목을 설정할 수 있습니다:

### 6.1 기본 탭

| 설정 항목 | 설명 | 기본값 |
|-----------|------|--------|
| 디테일 테이블 | BOM 상세 데이터 테이블 | `bom_detail` |
| 외래키 | BOM 헤더와의 연결 키 | `bom_id` |
| 부모키 | 부모-자식 관계 키 | `parent_detail_id` |
| 이력 테이블 | BOM 변경 이력 테이블 | `bom_history` |
| 버전 테이블 | BOM 버전 관리 테이블 | `bom_version` |
| 이력 기능 표시 | 이력 버튼 노출 여부 | `true` |
| 버전 기능 표시 | 버전 버튼 노출 여부 | `true` |

### 6.2 컬럼 탭

- 소스 테이블 (bom/item_info 등)에서 표시할 컬럼 선택
- 디테일 테이블에서 표시할 컬럼 선택
- 컬럼 순서 드래그앤드롭
- 컬럼별 라벨, 너비, 정렬 설정

---

## 7. 뷰 모드

### 7.1 트리 뷰 (기본)

- 계층적 들여쓰기로 부모-자식 관계 표현
- 레벨별 시각 구분:
  - **0레벨 (가상 루트)**: 파란색 배경 + 파란 좌측 바
  - **1레벨**: 흰색 배경 + 초록 좌측 바
  - **2레벨**: 연회색 배경 + 주황 좌측 바
  - **3레벨 이상**: 진회색 배경 + 보라 좌측 바
- 펼침/접힘 (정전개/역전개)

### 7.2 레벨 뷰

- 평면 테이블 형태로 표시
- "레벨0", "레벨1", "레벨2" ... 컬럼에 체크마크로 계층 표시
- 같은 레벨별 배경색 구분 적용

---

## 8. 주요 기능 목록

| 기능 | 상태 | 설명 |
|------|------|------|
| BOM 트리 표시 | 완료 | 계층적 트리 뷰 + 레벨 뷰 |
| BOM 항목 편집 | 완료 | 더블클릭으로 수정 모달 (0레벨: bom, 하위: bom_detail) |
| 이력 관리 | 완료 | 변경 이력 조회/등록 모달 |
| 버전 관리 | 완료 | 버전 생성/불러오기/사용 확정/삭제 |
| 설정 패널 | 완료 | 테이블/컬럼/기능 동적 설정 |
| 디자인 모드 프리뷰 | 완료 | 실제 화면과 일치하는 디자인 모드 표시 |
| 컬럼 크기 조절 | 완료 | 헤더 드래그로 컬럼 너비 변경 |
| 텍스트 말줄임 | 완료 | 긴 텍스트 `...` 처리 |
| 레벨별 시각 구분 | 완료 | 배경색 + 좌측 컬러 바 |
| 정전개/역전개 | 완료 | 전체 펼침/접기 토글 |
| 좌우 스크롤 | 완료 | 컬럼 크기가 커질 때 수평 스크롤 |
| BOM 목록 자동 새로고침 | 완료 | 버전 불러오기/확정 후 좌측 패널 자동 리프레시 |
| BOM 하위 품목 저장 | 완료 | BomItemEditorComponent에서 직접 INSERT/UPDATE/DELETE |
| 차수 (Revision) 자동 증가 | 미구현 | BOM 변경 시 헤더 revision 자동 +1 |

---

## 9. 보안 고려사항

- **SQL 인젝션 방지**: `safeTableName()` 함수로 테이블명 검증 (`^[a-zA-Z_][a-zA-Z0-9_]*$`)
- **멀티테넌시**: 모든 API에서 `company_code` 필터링 적용
- **최고 관리자**: `company_code = "*"` 시 전체 데이터 조회 가능
- **인증**: `authenticateToken` 미들웨어로 모든 라우트 보호

---

## 10. 향후 개선 사항

- [ ] 차수(Revision) 자동 증가 구현 (BOM 헤더 레벨)
- [ ] 버전 비교 기능 (두 버전 간 diff)
- [ ] BOM 복사 기능
- [ ] 이력 자동 등록 (수정/저장 시 자동으로 이력 생성)
- [ ] Excel 내보내기/가져오기
- [ ] BOM 유효성 검증 (순환참조 방지 등)