# 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 | 기존 폴리모픽 관계 유지 | ### 매핑 규칙 ``` item_type → source_table 자동 매핑: ├─ FG, PT → products 테이블 └─ SM, RM, CS → materials 테이블 API 흐름: 1. 클라이언트: item_type=FG 전송 2. 서버: common_codes에서 source_table 조회 3. 서버: products 또는 materials 테이블에 저장/조회 ``` --- ## 📐 문서 관계도 ``` ┌─────────────────────────────────────────────────────────────────┐ │ Item Master 문서 체계 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ 참조 ┌─────────────────────────────┐│ │ │ API 가이드 │◄──────────│ items-api-unified-plan.md ││ │ │ (front/) │ │ (plans/) ││ │ │ │ │ - API 구현 계획 ││ │ │ 프론트엔드용 │ │ - item_type 값 변경 스펙 ││ │ │ API 명세 │ │ - Swagger 스키마 정의 ││ │ └────────┬────────┘ └──────────────┬──────────────┘│ │ │ │ │ │ │ 연동 │ 구현 기반 │ │ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────────────────┐│ │ │ field-integration│ │ field-key-validation.md ││ │ │ (specs/) │◄───────────│ (specs/) ││ │ │ │ 검증 정책 │ ││ │ │ - 필드 통합 설계 │ │ - SystemFields 상수 ││ │ │ - source_table │ │ - 예약어 검증 로직 ││ │ │ 기반 분기 │ │ - 에러 메시지 정의 ││ │ └─────────────────┘ └─────────────────────────────┘│ │ │ │ ════════════════════════════════════════════════════════════ │ │ 공통 기반: common_codes 테이블 (code_group='item_type') │ │ ════════════════════════════════════════════════════════════ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 📋 문서 구조 ``` docs/ ├── front/ │ └── item-master-guide.md ✅ 최신 API 가이드 ├── specs/ │ ├── ITEM-MASTER-INDEX.md 📋 이 파일 │ ├── item-master-integration.md 🔧 연동 설계서 (개발 중) │ ├── item-master-field-integration.md 📄 필드 통합 스펙 │ └── item-master-field-key-validation.md ✅ 검증 정책 (구현 완료) ├── plans/ │ ├── items-api-unified-plan.md 📄 Items API 통합 계획 (최신) │ ├── items-api-modification-plan.md 📦 API 수정 계획 (통합됨) │ ├── items-naming-convention.md 📄 명명 규칙 │ └── flow-tests/ │ └── item-master-*.json 🧪 API 테스트 플로우 ├── guides/ │ └── item-management-migration.md 📄 마이그레이션 가이드 ├── data/analysis/ │ └── item-db-analysis.md 📊 DB 분석 └── history/2025-11/ ├── item-master-spec.md 📦 구버전 스펙 ├── item-master-gap-analysis.md 📦 갭 분석 ├── front-requests/ 📦 프론트 요청서 아카이브 └── item-master-archived/ 📦 기타 아카이브 ``` --- ## 🎯 핵심 문서 (현재 유효) | 문서 | 경로 | 역할 | 상태 | |------|------|------|------| | **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.php` - `api/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 | 문서 인덱스 생성, 중복 문서 정리 |