Item Master 문서 인덱스
품목기준관리(ItemMaster) 관련 문서 현황 및 개발 상태
최종 업데이트: 2025-12-09
🔑 핵심 개념 정의
item_type (품목 유형 코드)
| 코드 |
한글명 |
영문명 |
source_table |
FG |
제품 |
Finished Goods |
products |
PT |
부품 |
Parts |
products |
SM |
부자재 |
Sub-Materials |
materials |
RM |
원자재 |
Raw Materials |
materials |
CS |
소모품 |
Consumables |
materials |
저장 위치: common_codes 테이블 (code_group = 'item_type')
소스 테이블 매핑: attributes.source_table JSON 필드
시딩 상태: ✅ 구현 완료 (ItemTypeSeeder.php)
관련 용어 구분
| 용어 |
역할 |
값 |
사용처 |
item_type |
품목 유형 코드 |
FG/PT/SM/RM/CS |
API 파라미터, 필터링, UI 표시 |
source_table |
물리적 저장 테이블 |
products/materials |
DB 조회, 서비스 로직 분기 |
ref_type |
폴리모픽 참조 타입 |
PRODUCT/MATERIAL |
기존 폴리모픽 관계 유지 |
매핑 규칙
📐 문서 관계도
📋 문서 구조
🎯 핵심 문서 (현재 유효)
| 문서 |
경로 |
역할 |
상태 |
| API 가이드 |
front/item-master-guide.md |
프론트엔드용 API 명세 |
✅ 최신 |
| API 통합 계획 |
plans/items-api-unified-plan.md |
Items API 통합 구현 계획 |
📄 최신 |
| 필드 통합 스펙 |
specs/item-master-field-integration.md |
source_table 기반 필드 설계 |
🔧 v1.3 구현 중 |
| 검증 정책 |
specs/item-master-field-key-validation.md |
field_key 검증 로직 |
✅ 구현 완료 |
| 연동 설계서 |
specs/item-master-integration.md |
BE-FE 연동 아키텍처 |
🔧 개발 중 |
🔴 개발 필요 항목
1. Items API Material 지원 (items-api-modification-plan.md)
| API |
Product |
Material |
작업 내용 |
PUT /items/{id} |
✅ |
❌ |
Material 수정 지원 추가 |
DELETE /items/{id} |
✅ |
❌ |
Material 삭제 지원 추가 |
DELETE /items/batch |
✅ |
❌ |
Material 일괄삭제 지원 |
GET /items/code/{code} |
✅ |
❌ |
Material 코드 조회 지원 |
관련 파일:
api/app/Services/ItemsService.phpapi/app/Http/Controllers/Api/V1/ItemsController.php
2. 연동 설계 구현 (item-master-integration.md)
| 항목 |
상태 |
설명 |
| ItemFieldValidationService |
🔧 개발 중 |
attributes 값 검증 서비스 |
| Products/Materials 수정 |
⏳ 대기 |
검증 연동 적용 |
| field_meta 응답 옵션 |
⏳ 대기 |
?include_field_meta=true |
✅ 구현 완료 항목
1. field_key 검증 정책 (item-master-field-key-validation.md)
- ✅
SystemFields 상수 클래스 생성
- ✅ 시스템 예약어 검증 로직
- ✅ source_table 기반 분기 처리
- ✅ 에러 메시지 (
error.field_key_reserved)
2. ItemMaster CRUD API
- ✅ Pages, Sections, Fields, BomItems CRUD
- ✅ 독립 엔티티 아키텍처
- ✅ entity_relationships 링크 테이블
- ✅ Lock 기능 (연결 잠금)
3. item_type 코드 시딩 (ItemTypeSeeder)
- ✅ common_codes 테이블에 item_type 그룹 데이터 시딩
- ✅ attributes.source_table JSON 매핑 (products/materials)
- ✅ 5개 코드: FG(완제품), PT(부품), SM(부자재), RM(원자재), CS(소모품)
4. DB 구조 확정 (item_pages, item_sections, item_fields)
- ✅ item_pages 테이블 (페이지 설정) - 이미 존재, source_table 컬럼 포함
- ✅ item_sections 테이블 (섹션 설정) - 이미 존재
- ✅ item_fields 테이블 (필드 설정) - 이미 존재
- ✅ entity_relationships 링크 테이블로 page→section→field 연결
중요: item_pages는 common_codes로 대체 불가
- common_codes: item_type 마스터 코드 정의 (FG/PT/SM/RM/CS)
- item_pages: UI 페이지 설정 (같은 item_type에 여러 페이지 가능)
- 두 테이블은 역할이 다르며 공존해야 함
📦 아카이브 (History)
구버전 문서는 docs/history/2025-11/에 보관됨:
| 폴더 |
내용 |
front-requests/ |
11월 프론트엔드 API 요청서 |
item-master-archived/ |
분석, 구현, 디자인 문서 |
item-master-spec.md |
초기 API 명세 (11-20) |
item-master-gap-analysis.md |
갭 분석 문서 |
📊 관련 테스트
| 파일 |
위치 |
용도 |
item-master-init-api-flow.json |
docs/plans/flow-tests/ |
초기화 API 테스트 |
item-master-page-api-flow.json |
docs/plans/flow-tests/ |
페이지 CRUD 테스트 |
item-master-field-api-flow.json |
docs/plans/flow-tests/ |
필드 CRUD 테스트 |
item-fields-is-active-test.json |
api/docs/api-flows/ |
활성 필터 테스트 |
🔗 참고 문서
- 명명 규칙:
docs/plans/items-naming-convention.md
- 마이그레이션:
docs/guides/item-management-migration.md
- DB 분석:
docs/data/analysis/item-db-analysis.md
- MES 분석:
docs/projects/mes/00_baseline/docs_breakdown/api_item_analysis_summary.md
변경 이력
| 날짜 |
내용 |
| 2025-12-09 |
ItemTypeSeeder 구현 완료 (attributes.source_table 추가), DB 구조 확정 기록 추가, field-integration.md v1.3 반영 |
| 2025-12-09 |
핵심 개념 정의 (item_type/source_table/ref_type) 추가, 문서 관계도 추가 |
| 2025-12-09 |
items-api-unified-plan.md 추가, 핵심 문서 테이블 갱신 |
| 2025-12-09 |
문서 인덱스 생성, 중복 문서 정리 |
hskwon
182c2d1b57