hskwon
182c2d1b57
- ITEM-MASTER-INDEX.md: 문서 인덱스 및 핵심 개념 정의 - item-master-field-integration.md: 범용 메타 필드 시스템 구현 계획 (v1.3) - item-master-field-key-validation.md: field_key 검증 정책
226 lines
10 KiB
Markdown
226 lines
10 KiB
Markdown
# 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 | 문서 인덱스 생성, 중복 문서 정리 |
|