sam-docs/rules/item-policy.md

품목(Items) 비즈니스 정책

품목 관리 시스템의 핵심 비즈니스 규칙 정의

최종 업데이트: 2025-12-16

---

1. 품목 유형 체계 (item_type)

1.1 품목 유형 코드 정의

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

통합 완료 (2025-12-15): 기존 products/materials 테이블이 items 테이블로 통합되었습니다.

1.2 저장 위치

items 테이블 (통합)
├─ item_type = 'FG' | 'PT' | 'SM' | 'RM' | 'CS'
├─ code, name, unit, category_id
├─ bom (JSON)
└─ is_active

1.3 관련 테이블 구조

items (통합 테이블)
├─ id, tenant_id, item_type
├─ code, name, unit, category_id
├─ bom (JSON)
├─ is_active
└─ timestamps + soft deletes

item_details (확장 필드 - 1:1)
├─ is_sellable, is_purchasable, is_producible
├─ safety_stock, lead_time
└─ is_inspection 등

item_attributes (동적 속성 - 1:1)
├─ attributes (JSON)
└─ options (JSON)

1.4 테넌트별 확장

• 품목 유형은 테넌트별로 커스터마이징 가능
• common_codes.attributes JSON 필드 활용 (스키마 변경 없음)

---

2. 용어 정의 및 구분

2.1 핵심 용어

용어	필드명	값	용도
품목 유형	item_type	FG, PT, SM, RM, CS	API 파라미터, UI 필터링, 비즈니스 분류

⚠️ Deprecated: source_table, ref_type 개념은 items 테이블 통합으로 더 이상 사용되지 않습니다.

2.2 사용 규칙

• API 레벨: item_type 파라미터 사용
• 서비스 레벨: items 테이블 단일 조회 (item_type으로 필터링)

2.3 API 흐름 예시

1. 클라이언트 요청: GET /api/v1/items?item_type=FG
                    ↓
2. 서버 처리: items 테이블에서 item_type='FG' 조회
                    ↓
3. 응답 반환: item_type='FG' 포함하여 응답

---

3. 필드 키 예약어 정책

3.1 items 테이블 예약어 (통합)

// 사용 불가 field_key 목록
'code', 'name', 'unit', 'category_id', 'item_type', 'bom', 'is_active',
'attributes', 'options'

3.2 item_details 테이블 예약어

// 사용 불가 field_key 목록 (확장 필드)
'is_sellable', 'is_purchasable', 'is_producible', 'is_variable_size',
'safety_stock', 'lead_time', 'product_category', 'part_type',
'is_inspection'

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

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

3.4 검증 규칙

1. field_key 저장: 입력값 그대로 저장 (id 접두사 없음)

2. 예약어 검증 흐름:

   field_key 입력
        ↓
   items 테이블 예약어 체크
        ↓
   기존 필드 중복 체크
        ↓
   저장
   

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 등 내부 필드 숨김

// 응답 예시
{
  "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)
• ✅ field_key 예약어 검증 (SystemFields)
• ✅ ItemMaster CRUD API (Pages, Sections, Fields)
• ✅ 독립 엔티티 아키텍처 (entity_relationships)
• ✅ items 테이블 통합 (2025-12-15)
  • products/materials 테이블 삭제
  • items + item_details + item_attributes 구조
  • 전체 item_type (FG, PT, SM, RM, CS) 지원

8.2 API 현황 (통합 완료)

API	상태	설명
GET /api/v1/items	✅	전체 품목 조회 (item_type 필터)
POST /api/v1/items	✅	품목 생성
GET /api/v1/items/{id}	✅	품목 상세 조회
PUT /api/v1/items/{id}	✅	품목 수정
DELETE /api/v1/items/{id}	✅	품목 삭제
DELETE /api/v1/items/batch	✅	품목 일괄 삭제

---

변경 이력

날짜	내용
2025-12-16	items 테이블 통합 완료 반영 (products/materials → items)
2025-12-09	문서 생성 - 4개 문서 통합 (items-api-unified-plan, field-integration, field-key-validation, INDEX)