docs: ItemMaster 연동 설계서 v1.1 - 소스 매핑 컬럼 및 헬퍼 메서드 문서화

- item_pages.source_table 컬럼 추가 (products, materials 매핑)
- item_fields 내부용 매핑 컬럼 4개 (source_table, source_column, storage_type, json_path)
- 모델 헬퍼 메서드 섹션 추가 (ItemPage, ItemField)
- 저장 방식 판단 로직 다이어그램 추가

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 매핑 컬럼 추가, 모델 헬퍼 메서드 문서화 | - |