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 테이블 예약어

// 사용 불가 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 테이블 예약어

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

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

// 응답 예시
{
  "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)