sam-docs/rules/item-policy.md

# 품목(Items) 비즈니스 정책

> 품목 관리 시스템의 핵심 비즈니스 규칙 정의
>
> **최종 업데이트**: 2025-12-09

---

## 1. 품목 유형 체계 (item_type)

### 1.1 품목 유형 코드 정의

| 코드 | 한글명 | 영문명 | source_table | 설명 |
|------|--------|--------|--------------|------|
| `FG` | 완제품 | Finished Goods | products | 판매 가능한 최종 제품 |
| `PT` | 부품 | Parts | products | 제품 구성에 사용되는 부품 |
| `SM` | 부자재 | Sub-Materials | materials | 생산에 사용되는 보조 자재 |
| `RM` | 원자재 | Raw Materials | materials | 생산의 주요 원료 |
| `CS` | 소모품 | Consumables | materials | 일회성 소모 자재 |

### 1.2 저장 위치

```
common_codes 테이블
├─ code_group = 'item_type'
├─ code = 'FG' | 'PT' | 'SM' | 'RM' | 'CS'
└─ attributes.source_table = 'products' | 'materials'
```

### 1.3 source_table 매핑 규칙

```
item_type → source_table 자동 매핑:

FG (완제품)  ─┐
PT (부품)    ─┴─→ products 테이블

SM (부자재)  ─┐
RM (원자재)  ─┼─→ materials 테이블
CS (소모품)  ─┘
```

### 1.4 테넌트별 확장

- 품목 유형은 테넌트별로 커스터마이징 가능
- `common_codes.attributes` JSON 필드 활용 (스키마 변경 없음)
- 새 품목 유형 추가 시 source_table 매핑 필수

---

## 2. 용어 정의 및 구분

### 2.1 핵심 용어

| 용어 | 필드명 | 값 | 용도 |
|------|--------|-----|------|
| **품목 유형** | `item_type` | FG, PT, SM, RM, CS | API 파라미터, UI 필터링, 비즈니스 분류 |
| **저장 테이블** | `source_table` | products, materials | 내부 DB 분기, 서비스 로직 |
| **참조 타입** | `ref_type` | PRODUCT, MATERIAL | 폴리모픽 관계 (BOM, Prices 등) |

### 2.2 사용 규칙

- **API 레벨**: `item_type` 파라미터 사용
- **서비스 레벨**: `source_table`로 테이블 분기
- **폴리모픽 관계**: `ref_type`으로 참조 (기존 호환성 유지)

### 2.3 API 흐름 예시

```
1. 클라이언트 요청: GET /api/v1/items?item_type=FG
                    ↓
2. 서버 처리: item_type='FG' → common_codes 조회
                    ↓
3. 테이블 분기: source_table='products' 확인
                    ↓
4. 데이터 조회: products 테이블에서 조회
                    ↓
5. 응답 반환: item_type='FG' 포함하여 응답
```

---

## 3. 필드 키 예약어 정책

### 3.1 products 테이블 예약어

```php
// 사용 불가 field_key 목록
'code', 'name', 'unit', 'category_id', 'product_type', 'description',
'is_sellable', 'is_purchasable', 'is_producible', 'is_variable_size', 'is_active',
'safety_stock', 'lead_time', 'product_category', 'part_type',
'bending_diagram', 'bending_details',
'specification_file', 'specification_file_name',
'certification_file', 'certification_file_name',
'certification_number', 'certification_start_date', 'certification_end_date',
'attributes', 'attributes_archive'
```

### 3.2 materials 테이블 예약어

```php
// 사용 불가 field_key 목록
'name', 'item_name', 'specification', 'material_code', 'material_type',
'unit', 'category_id', 'is_inspection', 'is_active',
'search_tag', 'remarks', 'attributes', 'options'
```

### 3.3 공통 시스템 컬럼 (모든 테이블)

```php
// 절대 사용 불가
'id', 'tenant_id', 'created_by', 'updated_by', 'deleted_by',
'created_at', 'updated_at', 'deleted_at'
```

### 3.4 검증 규칙

1. **field_key 저장**: 입력값 그대로 저장 (id 접두사 없음)
2. **예약어 검증 흐름**:
   ```
   field_key 입력
        ↓
   source_table 확인 (products / materials)
        ↓
   해당 테이블 예약어 체크
        ↓
   기존 필드 중복 체크
        ↓
   저장
   ```

3. **에러 메시지**:
   - 예약어 충돌: `"{field_key}"은(는) 시스템 예약어로 사용할 수 없습니다.`
   - 중복: `field_key은(는) 이미 사용 중입니다.`

---

## 4. API 파라미터 규칙

### 4.1 목록 조회 (GET /api/v1/items)

| 파라미터 | 필수 | 값 | 설명 |
|---------|:----:|-----|------|
| `type` | ❌ | FG,PT,SM,RM,CS | 품목 유형 필터 (쉼표 구분) |
| `search` | ❌ | string | 코드/명칭 검색 |
| `page` | ❌ | int | 페이지 번호 |
| `size` | ❌ | int | 페이지 크기 |

### 4.2 단건 조회 (GET /api/v1/items/{id})

| 파라미터 | 필수 | 값 | 설명 |
|---------|:----:|-----|------|
| `item_type` | ✅ | FG/PT/SM/RM/CS | 품목 유형 (테이블 분기용) |
| `include_price` | ❌ | boolean | 단가 정보 포함 |

### 4.3 생성 (POST /api/v1/items)

| 파라미터 | 필수 | 값 | 설명 |
|---------|:----:|-----|------|
| `product_type` | ✅ | FG/PT/SM/RM/CS | 품목 유형 |
| `code` | ✅ | string | 품목 코드 |
| `name` | ✅ | string | 품목명 |
| `unit` | ✅ | string | 단위 |

### 4.4 수정 (PUT /api/v1/items/{id})

| 파라미터 | 필수 | 값 | 설명 |
|---------|:----:|-----|------|
| `item_type` | ✅ | FG/PT/SM/RM/CS | 품목 유형 (테이블 분기용) |

### 4.5 삭제 (DELETE /api/v1/items/{id})

| 파라미터 | 필수 | 값 | 설명 |
|---------|:----:|-----|------|
| `item_type` | ✅ | FG/PT/SM/RM/CS | 품목 유형 (테이블 분기용) |

### 4.6 일괄 삭제 (DELETE /api/v1/items/batch)

| 파라미터 | 필수 | 값 | 설명 |
|---------|:----:|-----|------|
| `item_type` | ✅ | FG/PT/SM/RM/CS | 품목 유형 |
| `ids` | ✅ | array | 삭제할 ID 목록 |

---

## 5. 데이터 저장 규칙

### 5.1 저장 방식 구분

| 저장 방식 | 대상 | 설명 |
|----------|------|------|
| **column** | 고정 컬럼 | DB 테이블 컬럼에 직접 저장 |
| **json** | 동적 속성 | `attributes` JSON 필드에 저장 |

### 5.2 고정 컬럼 (column)

- DB 스키마에 정의된 컬럼
- 필드 매핑: `item_fields.source_column` 사용
- 예: code, name, unit, category_id 등

### 5.3 동적 속성 (json)

- `attributes` JSON 필드에 저장
- 필드 매핑: `item_fields.json_path` 사용
- 예: `attributes.custom_size`, `attributes.color` 등

### 5.4 API 응답 규칙

- **플랫 구조**: attributes 내부 값을 최상위로 전개
- **매핑 정보 미노출**: source_table, source_column 등 내부 필드 숨김

```json
// 응답 예시
{
  "id": 1,
  "item_type": "FG",
  "code": "P-001",
  "name": "스크린 제품",
  "color": "white",      // attributes.color → 플랫 전개
  "size": "100x200"      // attributes.size → 플랫 전개
}
```

---

## 6. 삭제 규칙

### 6.1 BOM 사용 체크

- 품목이 다른 BOM의 구성품으로 사용 중이면 삭제 불가
- 에러 메시지: `다른 BOM의 구성품으로 사용 중입니다. (N건)`

### 6.2 Soft Delete

- 모든 품목은 soft delete 방식 사용
- `deleted_at` 타임스탬프로 삭제 표시
- 복구 가능

---

## 7. 관련 파일

### 7.1 API 파일

| 파일 | 경로 | 역할 |
|------|------|------|
| ItemsController | `api/app/Http/Controllers/Api/V1/ItemsController.php` | API 컨트롤러 |
| ItemsService | `api/app/Services/ItemsService.php` | 비즈니스 로직 |
| ItemTypeHelper | `api/app/Helpers/ItemTypeHelper.php` | item_type 헬퍼 |
| SystemFields | `api/app/Constants/SystemFields.php` | 예약어 상수 |

### 7.2 Seeder 파일

| 파일 | 경로 | 역할 |
|------|------|------|
| ItemTypeSeeder | `api/database/seeders/ItemTypeSeeder.php` | item_type 코드 시딩 |

### 7.3 Request 파일

| 파일 | 경로 |
|------|------|
| ItemStoreRequest | `api/app/Http/Requests/Item/ItemStoreRequest.php` |
| ItemUpdateRequest | `api/app/Http/Requests/Item/ItemUpdateRequest.php` |
| ItemBatchDeleteRequest | `api/app/Http/Requests/Item/ItemBatchDeleteRequest.php` |

---

## 8. 구현 현황

### 8.1 완료 항목

- ✅ item_type 코드 시딩 (ItemTypeSeeder)
- ✅ common_codes에 attributes.source_table 매핑
- ✅ field_key 예약어 검증 (SystemFields)
- ✅ ItemMaster CRUD API (Pages, Sections, Fields)
- ✅ 독립 엔티티 아키텍처 (entity_relationships)

### 8.2 개발 필요 항목

| API | Product | Material | 작업 내용 |
|-----|:-------:|:--------:|----------|
| `PUT /items/{id}` | ✅ | ❌ | Material 수정 지원 추가 |
| `DELETE /items/{id}` | ✅ | ❌ | Material 삭제 지원 추가 |
| `DELETE /items/batch` | ✅ | ❌ | Material 일괄삭제 지원 |
| `GET /items/code/{code}` | ✅ | ❌ | Material 코드 조회 지원 |

---

## 변경 이력

| 날짜 | 내용 |
|------|------|
| 2025-12-09 | 문서 생성 - 4개 문서 통합 (items-api-unified-plan, field-integration, field-key-validation, INDEX) |