From a1a5ce3faaac3c2a40c0eb93ac932b0bc0c1819a Mon Sep 17 00:00:00 2001
From: hskwon <shine1324@gmail.com>
Date: Mon, 8 Dec 2025 20:35:51 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20ItemMaster=20=EC=97=B0=EB=8F=99=20?=
 =?UTF-8?q?=EC=84=A4=EA=B3=84=EC=84=9C=20v1.1=20-=20=EC=86=8C=EC=8A=A4=20?=
 =?UTF-8?q?=EB=A7=A4=ED=95=91=20=EC=BB=AC=EB=9F=BC=20=EB=B0=8F=20=ED=97=AC?=
 =?UTF-8?q?=ED=8D=BC=20=EB=A9=94=EC=84=9C=EB=93=9C=20=EB=AC=B8=EC=84=9C?=
 =?UTF-8?q?=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- item_pages.source_table 컬럼 추가 (products, materials 매핑)
- item_fields 내부용 매핑 컬럼 4개 (source_table, source_column, storage_type, json_path)
- 모델 헬퍼 메서드 섹션 추가 (ItemPage, ItemField)
- 저장 방식 판단 로직 다이어그램 추가
---
 specs/item-master-integration.md | 114 +++++++++++++++++++++++++++++--
 1 file changed, 110 insertions(+), 4 deletions(-)

diff --git a/specs/item-master-integration.md b/specs/item-master-integration.md
index 60ab2cf..5caf1e9 100644
--- a/specs/item-master-integration.md
+++ b/specs/item-master-integration.md
@@ -1,7 +1,8 @@
 # ItemMaster 연동 설계서
 
 **작성일**: 2025-12-05
-**버전**: 1.0
+**최종 수정**: 2025-12-08
+**버전**: 1.1
 **상태**: Draft
 
 ---
@@ -27,10 +28,15 @@
 ┌─────────────────────────────────────────────────────────────┐
 │  item_pages (페이지 정의)                                    │
 ├─────────────────────────────────────────────────────────────┤
-│  id, tenant_id, page_name, item_type, is_active             │
+│  id, tenant_id, page_name, item_type, source_table,         │
+│  is_active                                                   │
 │                                                              │
 │  item_type: FG(완제품), PT(반제품), SM(부자재),              │
 │             RM(원자재), CS(소모품)                           │
+│                                                              │
+│  source_table: 실제 저장 테이블명                            │
+│    - 'products'  (FG, PT)                                   │
+│    - 'materials' (SM, RM, CS)                               │
 └─────────────────────────────────────────────────────────────┘
                               │
                               │ 1:N
@@ -61,6 +67,12 @@
 │  category         ← 필드 카테고리                           │
 │  is_common        ← 공통 필드 여부                          │
 │  is_active        ← 활성 여부                                │
+│                                                              │
+│  [내부용 매핑 컬럼 - API 응답에서 hidden]                    │
+│  source_table     ← 원본 테이블명 (products, materials 등)  │
+│  source_column    ← 원본 컬럼명 (code, name 등)             │
+│  storage_type     ← 저장방식 (column=DB컬럼, json=JSON)     │
+│  json_path        ← JSON 저장 경로 (예: attributes.size)    │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -531,7 +543,100 @@ VALUES (1, 3, 'urgency', '긴급도', 'dropdown', ...);
 
 ---
 
-## 8. 구현 계획
+## 8. 모델 헬퍼 메서드
+
+### 8.1 ItemPage 모델
+
+```php
+class ItemPage extends Model
+{
+    /**
+     * source_table에 해당하는 모델 클래스명 반환
+     */
+    public function getTargetModelClass(): ?string
+    {
+        $mapping = [
+            'products' => \App\Models\Product::class,
+            'materials' => \App\Models\Material::class,
+        ];
+        return $mapping[$this->source_table] ?? null;
+    }
+
+    /**
+     * 제품 페이지인지 확인
+     */
+    public function isProductPage(): bool
+    {
+        return $this->source_table === 'products';
+    }
+
+    /**
+     * 자재 페이지인지 확인
+     */
+    public function isMaterialPage(): bool
+    {
+        return $this->source_table === 'materials';
+    }
+}
+```
+
+### 8.2 ItemField 모델
+
+```php
+class ItemField extends Model
+{
+    /**
+     * 시스템 필드 여부 확인 (DB 컬럼과 매핑된 필드)
+     */
+    public function isSystemField(): bool
+    {
+        return !is_null($this->source_table) && !is_null($this->source_column);
+    }
+
+    /**
+     * 컬럼 저장 방식 여부 확인
+     */
+    public function isColumnStorage(): bool
+    {
+        return $this->storage_type === 'column';
+    }
+
+    /**
+     * JSON 저장 방식 여부 확인
+     */
+    public function isJsonStorage(): bool
+    {
+        return $this->storage_type === 'json';
+    }
+}
+```
+
+### 8.3 필드 저장 방식 판단
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  storage_type 판단 로직                                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  if (source_table && source_column) {                       │
+│      // 시스템 필드 (기존 DB 컬럼과 매핑)                    │
+│      if (storage_type === 'column') {                       │
+│          → products.{source_column} 또는                    │
+│            materials.{source_column} 에서 직접 읽기/쓰기    │
+│      } else if (storage_type === 'json') {                  │
+│          → {json_path} 경로로 JSON 내 읽기/쓰기             │
+│      }                                                       │
+│  } else {                                                    │
+│      // 커스텀 필드 (동적 정의)                              │
+│      → attributes.{field_key} 에 저장                       │
+│  }                                                           │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 9. 구현 계획
 
 | 순서 | 작업 | 담당 | 예상 공수 |
 |------|------|------|----------|
@@ -548,8 +653,9 @@ VALUES (1, 3, 'urgency', '긴급도', 'dropdown', ...);
 
 ---
 
-## 9. 변경 이력
+## 10. 변경 이력
 
 | 날짜 | 버전 | 변경 내용 | 작성자 |
 |------|------|----------|--------|
 | 2025-12-05 | 1.0 | 최초 작성 | - |
+| 2025-12-08 | 1.1 | source_table/source_column 매핑 컬럼 추가, 모델 헬퍼 메서드 문서화 | - |