SamProject/sam-docs
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c2784e1fe79b6078b3e062c711021fff062da950
sam-docs/rules/item-policy.md
hskwon aee6d12fd9 Revert "docs: items 테이블 통합 완료 내용 반영" 
This reverts commit e863d3762a.
2025-12-16 10:08:07 +09:00

8.4 KiB
Raw Blame History

품목(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)