# Items 테이블 통합 마이그레이션 계획

## 개요

### 목적
현재 이원화된 `products`/`materials` 테이블을 통합 `items` 테이블 구조로 전환하여:
- BOM 관리 시 `child_item_type` 불필요 (ID만으로 유일 식별)
- 단일 쿼리로 모든 품목 조회 가능
- Service/Controller 코드 50% 감소
- 유지보수성 및 확장성 향상

### 설계 변경 이력
- **2025-12-11 (v1)**: 단일 `items` 테이블에 모든 필드 통합
- **2025-12-11 (v2)**: 4개 테이블로 분리하여 성능 최적화
  - `items`: 핵심 필드 (목록 조회, BOM 계산)
  - `item_details`: 필수/인덱싱 필드 (검색, 필터링)
  - `item_attributes`: 동적 속성 (JSON 기반)
  - `item_bending`: 절곡 정보 (별도 관리)

### 현재 상태 분석

#### 테이블 구조 비교

| 구분 | Products | Materials | 통합 Items |
|------|----------|-----------|------------|
| ID | id (1~808) | id (1~417) | id (새 통합 ID) |
| 타입 | product_type (FG, PT, PRODUCT, SUBASSEMBLY, PART, CS) | material_type (SM, RM, CS) | item_type |
| 코드 | code | material_code | code |
| 이름 | name | name | name |
| 단위 | unit | unit | unit |
| 규격 | - | specification | attributes (JSON) |
| BOM | bom (JSON) | - | bom (JSON) |
| 속성 | attributes, options | attributes, options | attributes, options |

#### 데이터 현황 (2025-12-11)
- Products: **808건**
- Materials: **417건**
- 총합: **1,225건**

#### 참조 테이블 현황

| 테이블 | 참조 방식 | 데이터 |
|--------|----------|--------|
| product_components | parent_product_id, ref_type+ref_id | 16건 |
| bom_template_items | ref_type+ref_id | 1건 |
| orders | product_id | 0건 |
| order_items | product_id | 0건 |
| quotes | product_id | 0건 |
| material_receipts | material_id | 0건 |
| lots | material_id | 0건 |
| price_histories | item_type+item_id | 조회 필요 |

---

## Phase 1: 테이블 생성 및 데이터 이관

### 1.1 items 테이블 (핵심 정보)

```sql
CREATE TABLE items (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL COMMENT '테넌트 ID',

    -- 기본 정보
    item_type VARCHAR(15) NOT NULL COMMENT '품목 유형: FG, PT, SM, RM, CS, PRODUCT, SUBASSEMBLY, PART',
    code VARCHAR(100) NOT NULL COMMENT '품목 코드',
    name VARCHAR(255) NOT NULL COMMENT '품목명',
    unit VARCHAR(20) NULL COMMENT '단위',
    category_id BIGINT UNSIGNED NULL COMMENT '카테고리 ID',

    -- BOM
    bom JSON NULL COMMENT 'BOM [{child_item_id, quantity}, ...]',

    -- 상태
    is_active TINYINT(1) DEFAULT 1 COMMENT '활성 상태',

    -- 레거시 참조 (전환기간용)
    legacy_table VARCHAR(20) NULL COMMENT '원본 테이블: products | materials',
    legacy_id BIGINT UNSIGNED NULL COMMENT '원본 테이블 ID',

    -- 감사 필드
    created_by BIGINT UNSIGNED NULL COMMENT '생성자',
    updated_by BIGINT UNSIGNED NULL COMMENT '수정자',
    deleted_by BIGINT UNSIGNED NULL COMMENT '삭제자',
    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,
    deleted_at TIMESTAMP NULL,

    -- 인덱스
    INDEX idx_items_tenant_type (tenant_id, item_type),
    INDEX idx_items_tenant_code (tenant_id, code),
    INDEX idx_items_tenant_category (tenant_id, category_id),
    INDEX idx_items_tenant_active (tenant_id, is_active),
    INDEX idx_items_legacy (legacy_table, legacy_id),
    UNIQUE KEY uq_items_tenant_code (tenant_id, code, deleted_at),

    -- 외래키
    FOREIGN KEY (tenant_id) REFERENCES tenants(id),
    FOREIGN KEY (category_id) REFERENCES categories(id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
COMMENT='Products + Materials 통합 품목 테이블 (핵심 정보)';
```

### 1.2 item_details 테이블 (필수/인덱싱 필드)

```sql
CREATE TABLE item_details (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    item_id BIGINT UNSIGNED NOT NULL COMMENT 'items 테이블 FK',

    -- Products 전용 (인덱싱/필터링)
    is_sellable TINYINT(1) DEFAULT 1 COMMENT '판매 가능',
    is_purchasable TINYINT(1) DEFAULT 0 COMMENT '구매 가능',
    is_producible TINYINT(1) DEFAULT 0 COMMENT '생산 가능',
    safety_stock INT NULL COMMENT '안전 재고',
    lead_time INT NULL COMMENT '리드타임 (일)',
    is_variable_size TINYINT(1) DEFAULT 0 COMMENT '가변 사이즈 여부',
    product_category VARCHAR(50) NULL COMMENT '제품 카테고리',
    part_type VARCHAR(50) NULL COMMENT '부품 유형',

    -- Materials 전용 (인덱싱/필터링)
    is_inspection VARCHAR(1) DEFAULT 'N' COMMENT '검사 대상 여부',

    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,

    -- 인덱스
    UNIQUE KEY uq_item_details_item_id (item_id),
    INDEX idx_item_details_sellable (is_sellable),
    INDEX idx_item_details_purchasable (is_purchasable),
    INDEX idx_item_details_producible (is_producible),
    INDEX idx_item_details_inspection (is_inspection),

    -- 외래키
    FOREIGN KEY (item_id) REFERENCES items(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
COMMENT='품목 상세 정보 (필수/인덱싱 필드)';
```

### 1.3 item_attributes 테이블 (동적 속성)

```sql
CREATE TABLE item_attributes (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    item_id BIGINT UNSIGNED NOT NULL COMMENT 'items 테이블 FK',

    -- 동적 속성
    attributes JSON NULL COMMENT '동적 속성 (규격 정보 포함)',
    options JSON NULL COMMENT '옵션 (파일, 인증, 설명 등)',

    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,

    -- 인덱스
    UNIQUE KEY uq_item_attributes_item_id (item_id),

    -- 외래키
    FOREIGN KEY (item_id) REFERENCES items(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
COMMENT='품목 동적 속성 (JSON 기반)';
```

### 1.4 item_bending 테이블 (절곡 정보)

```sql
CREATE TABLE item_bending (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    item_id BIGINT UNSIGNED NOT NULL COMMENT 'items 테이블 FK',

    -- 절곡 정보
    diagram VARCHAR(255) NULL COMMENT '절곡 도면 파일',
    details JSON NULL COMMENT '절곡 상세 정보',

    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,

    -- 인덱스
    UNIQUE KEY uq_item_bending_item_id (item_id),

    -- 외래키
    FOREIGN KEY (item_id) REFERENCES items(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
COMMENT='품목 절곡 정보';
```

### 1.5 item_id_mappings 테이블 (전환기간용)

```sql
CREATE TABLE item_id_mappings (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    new_item_id BIGINT UNSIGNED NOT NULL COMMENT '새 items 테이블 ID',
    legacy_table VARCHAR(20) NOT NULL COMMENT '원본 테이블: products | materials',
    legacy_id BIGINT UNSIGNED NOT NULL COMMENT '원본 테이블 ID',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    -- 인덱스
    UNIQUE KEY uq_legacy (legacy_table, legacy_id),
    INDEX idx_new_item (new_item_id),

    -- 외래키
    FOREIGN KEY (new_item_id) REFERENCES items(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
COMMENT='Products/Materials → Items ID 매핑 (전환기간용)';
```

### 1.6 데이터 이관 스크립트

```php
// 1. Products → Items 이관
DB::statement("
    INSERT INTO items (
        tenant_id, item_type, code, name, unit, category_id, bom,
        is_active, created_by, updated_by, deleted_by,
        created_at, updated_at, deleted_at,
        legacy_table, legacy_id
    )
    SELECT
        tenant_id, product_type, code, name, unit, category_id, bom,
        is_active, created_by, updated_by, deleted_by,
        created_at, updated_at, deleted_at,
        'products', id
    FROM products
");

// 2. Products → item_details 이관
DB::statement("
    INSERT INTO item_details (
        item_id, is_sellable, is_purchasable, is_producible,
        safety_stock, lead_time, is_variable_size,
        product_category, part_type, is_inspection,
        created_at, updated_at
    )
    SELECT
        i.id, p.is_sellable, p.is_purchasable, p.is_producible,
        p.safety_stock, p.lead_time, p.is_variable_size,
        p.product_category, p.part_type, 'N',
        p.created_at, p.updated_at
    FROM products p
    JOIN items i ON i.legacy_table = 'products' AND i.legacy_id = p.id
");

// 3. Products → item_attributes 이관
DB::statement("
    INSERT INTO item_attributes (
        item_id, attributes, options, created_at, updated_at
    )
    SELECT
        i.id, p.attributes, p.options, p.created_at, p.updated_at
    FROM products p
    JOIN items i ON i.legacy_table = 'products' AND i.legacy_id = p.id
");

// 4. Products → item_bending 이관 (절곡 정보 있는 경우만)
DB::statement("
    INSERT INTO item_bending (
        item_id, diagram, details, created_at, updated_at
    )
    SELECT
        i.id, p.bending_diagram, p.bending_details, p.created_at, p.updated_at
    FROM products p
    JOIN items i ON i.legacy_table = 'products' AND i.legacy_id = p.id
    WHERE p.bending_diagram IS NOT NULL OR p.bending_details IS NOT NULL
");

// 5. Materials → Items 이관
DB::statement("
    INSERT INTO items (
        tenant_id, item_type, code, name, unit, category_id,
        is_active, created_by, updated_by, deleted_by,
        created_at, updated_at, deleted_at,
        legacy_table, legacy_id
    )
    SELECT
        tenant_id, material_type, material_code, name, unit, category_id,
        is_active, created_by, updated_by, deleted_by,
        created_at, updated_at, deleted_at,
        'materials', id
    FROM materials
");

// 6. Materials → item_details 이관
DB::statement("
    INSERT INTO item_details (
        item_id, is_sellable, is_purchasable, is_producible,
        safety_stock, lead_time, is_variable_size,
        product_category, part_type, is_inspection,
        created_at, updated_at
    )
    SELECT
        i.id, 0, 1, 0,
        NULL, NULL, 0,
        NULL, NULL, m.is_inspection,
        m.created_at, m.updated_at
    FROM materials m
    JOIN items i ON i.legacy_table = 'materials' AND i.legacy_id = m.id
");

// 7. Materials → item_attributes 이관
// options에 기존 Materials 전용 필드 포함
DB::statement("
    INSERT INTO item_attributes (
        item_id, attributes, options, created_at, updated_at
    )
    SELECT
        i.id,
        m.attributes,
        JSON_OBJECT(
            'specification', m.specification,
            'item_name', m.item_name,
            'search_tag', m.search_tag,
            'remarks', m.remarks
        ),
        m.created_at, m.updated_at
    FROM materials m
    JOIN items i ON i.legacy_table = 'materials' AND i.legacy_id = m.id
");

// 8. ID 매핑 테이블 생성
DB::statement("
    INSERT INTO item_id_mappings (new_item_id, legacy_table, legacy_id)
    SELECT id, legacy_table, legacy_id
    FROM items
    WHERE legacy_table IS NOT NULL AND legacy_id IS NOT NULL
");
```

### 1.7 체크리스트

- [ ] items 테이블 마이그레이션 생성
- [ ] item_details 테이블 마이그레이션 생성
- [ ] item_attributes 테이블 마이그레이션 생성
- [ ] item_bending 테이블 마이그레이션 생성
- [ ] item_id_mappings 테이블 마이그레이션 생성
- [ ] Products 데이터 이관 스크립트 실행
- [ ] Materials 데이터 이관 스크립트 실행
- [ ] 데이터 검증 (건수, 필드값 일치)

---

## Phase 2: Item 모델 및 Service 생성

### 2.1 Item 모델

```php
// app/Models/Items/Item.php
class Item extends Model
{
    use BelongsToTenant, ModelTrait, SoftDeletes;

    protected $fillable = [
        'tenant_id', 'item_type', 'code', 'name', 'unit', 'category_id',
        'bom', 'is_active', 'created_by', 'updated_by',
    ];

    protected $casts = [
        'bom' => 'array',
        'is_active' => 'boolean',
    ];

    // 1:1 관계
    public function details() { return $this->hasOne(ItemDetail::class); }
    public function attributes() { return $this->hasOne(ItemAttribute::class); }
    public function bending() { return $this->hasOne(ItemBending::class); }

    // 타입별 스코프
    public function scopeType($q, string $type) { return $q->where('item_type', $type); }
    public function scopeProducts($q) { return $q->whereIn('item_type', ['FG', 'PT', 'PRODUCT', 'SUBASSEMBLY', 'PART']); }
    public function scopeMaterials($q) { return $q->whereIn('item_type', ['SM', 'RM', 'CS']); }
}
```

### 2.2 관련 모델

```php
// app/Models/Items/ItemDetail.php
class ItemDetail extends Model
{
    protected $fillable = [
        'item_id', 'is_sellable', 'is_purchasable', 'is_producible',
        'safety_stock', 'lead_time', 'is_variable_size',
        'product_category', 'part_type', 'is_inspection',
    ];

    protected $casts = [
        'is_sellable' => 'boolean',
        'is_purchasable' => 'boolean',
        'is_producible' => 'boolean',
        'is_variable_size' => 'boolean',
    ];

    public function item() { return $this->belongsTo(Item::class); }
}

// app/Models/Items/ItemAttribute.php
class ItemAttribute extends Model
{
    protected $fillable = ['item_id', 'attributes', 'options'];
    protected $casts = ['attributes' => 'array', 'options' => 'array'];
    public function item() { return $this->belongsTo(Item::class); }
}

// app/Models/Items/ItemBending.php
class ItemBending extends Model
{
    protected $fillable = ['item_id', 'diagram', 'details'];
    protected $casts = ['details' => 'array'];
    public function item() { return $this->belongsTo(Item::class); }
}
```

### 2.3 체크리스트

- [ ] Item 모델 생성
- [ ] ItemDetail 모델 생성
- [ ] ItemAttribute 모델 생성
- [ ] ItemBending 모델 생성
- [ ] UnifiedItemsService 생성
- [ ] ItemRequest (FormRequest) 생성
- [ ] 단위 테스트 작성

---

## Phase 3: API 엔드포인트 전환

### 3.1 신규 API (v2)

| 메서드 | 엔드포인트 | 설명 |
|--------|-----------|------|
| GET | /api/v2/items | 통합 품목 목록 |
| GET | /api/v2/items/{id} | 품목 상세 (with details, attributes, bending) |
| POST | /api/v2/items | 품목 생성 |
| PUT | /api/v2/items/{id} | 품목 수정 |
| DELETE | /api/v2/items/{id} | 품목 삭제 |
| DELETE | /api/v2/items/batch | 일괄 삭제 |

### 3.2 체크리스트

- [ ] v2 라우트 정의
- [ ] UnifiedItemsController 생성
- [ ] Swagger 문서 작성 (v2)
- [ ] v1 API 호환 레이어 구현
- [ ] API 테스트 작성

---

## Phase 4: 참조 테이블 마이그레이션

### 4.1 참조 테이블 목록

| 테이블 | 변경 필요 컬럼 | 작업 |
|--------|--------------|------|
| product_components | ref_type+ref_id → child_item_id | 마이그레이션 |
| bom_template_items | ref_type+ref_id → item_id | 마이그레이션 |
| orders | product_id → item_id | 마이그레이션 |
| order_items | product_id → item_id | 마이그레이션 |
| quotes | product_id → item_id | 마이그레이션 |
| material_receipts | material_id → item_id | 마이그레이션 |
| lots | material_id → item_id | 마이그레이션 |
| price_histories | item_type+item_id → item_id | 마이그레이션 |

### 4.2 체크리스트

- [ ] 각 참조 테이블 마이그레이션 스크립트 작성
- [ ] 관련 모델 업데이트
- [ ] 데이터 검증

---

## Phase 5: 레거시 정리

### 5.1 체크리스트

- [ ] 모든 참조 테이블 전환 완료 확인
- [ ] v1 API 사용량 모니터링 (0 확인)
- [ ] items 레거시 컬럼 제거 (legacy_table, legacy_id)
- [ ] item_id_mappings 테이블 제거
- [ ] products 테이블 제거
- [ ] materials 테이블 제거
- [ ] 최종 테스트

---

## 테이블 구조 요약

```
┌─────────────────────────────────────────────────────────────────┐
│                         items (핵심)                             │
├─────────────────────────────────────────────────────────────────┤
│ id, tenant_id, item_type, code, name, unit, category_id        │
│ bom (JSON), is_active, legacy_table, legacy_id                 │
│ timestamps + soft deletes                                       │
└───────────────────────────┬─────────────────────────────────────┘
                            │ 1:1
        ┌───────────────────┼───────────────────┬─────────────────┐
        ▼                   ▼                   ▼                 │
┌───────────────┐   ┌───────────────┐   ┌───────────────┐        │
│ item_details  │   │item_attributes│   │ item_bending  │        │
├───────────────┤   ├───────────────┤   ├───────────────┤        │
│ item_id (UK)  │   │ item_id (UK)  │   │ item_id (UK)  │        │
│ is_sellable   │   │ attributes    │   │ diagram       │        │
│ is_purchasable│   │ options       │   │ details       │        │
│ is_producible │   └───────────────┘   └───────────────┘        │
│ safety_stock  │                                                 │
│ lead_time     │   ┌───────────────────────────────────┐        │
│ is_variable.. │   │       item_id_mappings            │        │
│ product_cat.. │   ├───────────────────────────────────┤        │
│ part_type     │   │ new_item_id ──────────────────────┼────────┘
│ is_inspection │   │ legacy_table, legacy_id           │
└───────────────┘   └───────────────────────────────────┘
```

---

## 사용 패턴별 쿼리

| 패턴 | 빈도 | JOIN | 쿼리 |
|------|------|------|------|
| 목록 조회 | 80%+ | ❌ | `SELECT * FROM items WHERE ...` |
| 검색 | 빈번 | ❌ | `SELECT * FROM items WHERE code LIKE ...` |
| BOM 계산 | 5% | 자기참조 | `SELECT * FROM items WHERE id IN (...)` |
| 상세 조회 | 15% | ✅ 3-4테이블 | `SELECT * FROM items JOIN item_details ...` |
| 필터 (판매가능) | 간헐 | ✅ 1테이블 | `JOIN item_details WHERE is_sellable = 1` |

---

## 일정 계획

| Phase | 작업 내용 | 상태 |
|-------|----------|------|
| Phase 1 | 테이블 생성 + 데이터 이관 | ⬜ 대기 |
| Phase 2 | 모델 + Service 생성 | ⬜ 대기 |
| Phase 3 | API 엔드포인트 전환 | ⬜ 대기 |
| Phase 4 | 참조 테이블 마이그레이션 | ⬜ 대기 |
| Phase 5 | 레거시 정리 | ⬜ 대기 |

---

## 리스크 및 대응

### 리스크 1: ID 변경으로 인한 기존 연동 깨짐
- **대응**: legacy_table + legacy_id 컬럼으로 매핑 유지
- **전환기간**: v1 API 호환 레이어 제공

### 리스크 2: 데이터 이관 중 누락
- **대응**: 이관 전후 건수 검증
- **롤백 계획**: 이관 스크립트 역순 실행

### 리스크 3: JOIN 성능
- **분석**: 1:1 JOIN + UNIQUE 인덱스로 10만건도 수 ms 이내
- **모니터링**: 쿼리 성능 측정