feat: DB 연결 오버라이딩 및 대시보드 통계 위젯 추가

- DB 연결: 로컬/Docker 환경 오버라이딩 설정 (.env)
- 테넌트 위젯: redirect 버그 수정 (TenantSelectorWidget)
- 통계 위젯: 사용자/제품/자재/주문 카드 추가 (StatsOverviewWidget)
- 리소스 한국어화: Product, Material 모델 레이블 추가
- 대시보드: 위젯 등록 및 캐시 최적화

🤖 Generated with [Claude Code](https://claude.ai/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/parameter-based-bom-api.md

@@ -0,0 +1,651 @@
+# 매개변수 기반 BOM 시스템 API 문서
+
+## 개요
+
+SAM 프로젝트의 매개변수 기반 BOM 시스템은 입력 매개변수를 통해 동적으로 제품 사양과 BOM을 계산하여 자동으로 제품을 생성하는 시스템입니다.
+
+## 시스템 구조
+
+```
+Model (KSS01)
+├── Parameters (W0, H0, installation_type, ...)
+├── Formulas (W1 = W0 + margin, area = W1 * H1, ...)
+└── BOM Template
+    └── Condition Rules (브라켓, 모터, 가이드, ...)
+```
+
+## KSS01 모델 시나리오
+
+### 모델 정의
+- **모델명**: KSS01 (전동 스크린 시스템)
+- **제품군**: 전동 스크린
+- **특징**: 크기와 설치 타입에 따른 다양한 구성
+
+### 입력 매개변수
+
+| 매개변수 | 타입 | 설명 | 단위 | 범위 | 기본값 |
+|---------|------|------|------|------|--------|
+| W0 | DECIMAL | 원본 가로 크기 | mm | 500-2000 | 1000 |
+| H0 | DECIMAL | 원본 세로 크기 | mm | 400-1500 | 800 |
+| installation_type | STRING | 설치 타입 | - | A, B, C | A |
+| power_source | STRING | 전원 타입 | - | 220V, 110V | 220V |
+| color | STRING | 색상 | - | WHITE, BLACK, GRAY | WHITE |
+
+### 계산 공식
+
+| 출력 매개변수 | 공식 | 설명 |
+|-------------|------|------|
+| W1 | `W0 + (installation_type == "A" ? 50 : 30)` | 최종 가로 크기 |
+| H1 | `H0 + (installation_type == "A" ? 50 : 30)` | 최종 세로 크기 |
+| area | `W1 * H1` | 전체 면적 |
+| weight | `area * 0.000025 + 5` | 예상 무게 (kg) |
+| motor_power | `weight > 20 ? 150 : 120` | 모터 파워 (W) |
+
+### BOM 조건 규칙
+
+| 규칙명 | 조건 | 자재/제품 | 수량 공식 | 설명 |
+|--------|------|-----------|----------|------|
+| 표준 브라켓 | `installation_type == "A"` | BR-001 (브라켓) | `ceiling(W1 / 500)` | A타입은 표준 브라켓 |
+| 경량 브라켓 | `installation_type != "A"` | BR-002 (경량 브라켓) | `ceiling(W1 / 600)` | B/C타입은 경량 브라켓 |
+| 고출력 모터 | `motor_power >= 150` | MT-002 (고출력 모터) | `1` | 150W 이상시 고출력 |
+| 표준 모터 | `motor_power < 150` | MT-001 (표준 모터) | `1` | 150W 미만시 표준 |
+| 가이드 레일 | `true` | GD-001 (가이드 레일) | `ceiling(H1 / 1000) * 2` | 항상 필요 |
+| 컨트롤러 | `power_source == "220V"` | CT-001 (220V 컨트롤러) | `1` | 220V 전용 |
+| 컨트롤러 | `power_source == "110V"` | CT-002 (110V 컨트롤러) | `1` | 110V 전용 |
+
+## API 사용 예시
+
+### 1. 모델 매개변수 설정
+
+#### 매개변수 목록 조회
+```http
+GET /v1/design/models/1/parameters
+Authorization: Bearer {token}
+X-API-KEY: {api-key}
+```
+
+#### 매개변수 생성
+```http
+POST /v1/design/models/1/parameters
+Authorization: Bearer {token}
+X-API-KEY: {api-key}
+Content-Type: application/json
+
+{
+  "name": "W0",
+  "label": "원본 가로 크기",
+  "type": "INPUT",
+  "data_type": "DECIMAL",
+  "unit": "mm",
+  "default_value": "1000",
+  "min_value": 500,
+  "max_value": 2000,
+  "description": "제품의 원본 가로 크기를 입력하세요",
+  "is_required": true,
+  "display_order": 1
+}
+```
+
+### 2. 공식 설정
+
+#### 공식 생성
+```http
+POST /v1/design/models/1/formulas
+Authorization: Bearer {token}
+X-API-KEY: {api-key}
+Content-Type: application/json
+
+{
+  "name": "최종 가로 크기 계산",
+  "target_parameter": "W1",
+  "expression": "W0 + (installation_type == \"A\" ? 50 : 30)",
+  "description": "설치 타입에 따른 최종 가로 크기 계산",
+  "is_active": true,
+  "execution_order": 1
+}
+```
+
+#### 공식 검증
+```http
+POST /v1/design/models/1/formulas/1/validate
+Authorization: Bearer {token}
+X-API-KEY: {api-key}
+Content-Type: application/json
+
+{
+  "test_values": {
+    "W0": 1000,
+    "installation_type": "A"
+  }
+}
+```
+
+**응답:**
+```json
+{
+  "success": true,
+  "message": "formula.validated",
+  "data": {
+    "is_valid": true,
+    "result": 1050,
+    "error_message": null
+  }
+}
+```
+
+### 3. BOM 조건 규칙 설정
+
+#### 조건 규칙 생성
+```http
+POST /v1/design/bom-templates/1/condition-rules
+Authorization: Bearer {token}
+X-API-KEY: {api-key}
+Content-Type: application/json
+
+{
+  "name": "표준 브라켓 선택",
+  "ref_type": "MATERIAL",
+  "ref_id": 101,
+  "condition_expression": "installation_type == \"A\"",
+  "quantity_expression": "ceiling(W1 / 500)",
+  "waste_rate_expression": "0.05",
+  "description": "A타입 설치시 표준 브라켓 적용",
+  "priority": 1,
+  "is_active": true
+}
+```
+
+### 4. BOM 미리보기 생성
+
+#### 실시간 BOM 해석
+```http
+POST /v1/products/models/1/resolve-preview
+Authorization: Bearer {token}
+X-API-KEY: {api-key}
+Content-Type: application/json
+
+{
+  "input_parameters": {
+    "W0": 1000,
+    "H0": 800,
+    "installation_type": "A",
+    "power_source": "220V",
+    "color": "WHITE"
+  },
+  "include_calculated_values": true,
+  "include_bom_items": true
+}
+```
+
+**응답:**
+```json
+{
+  "success": true,
+  "message": "bom.preview_generated",
+  "data": {
+    "input_parameters": {
+      "W0": 1000,
+      "H0": 800,
+      "installation_type": "A",
+      "power_source": "220V",
+      "color": "WHITE"
+    },
+    "calculated_values": {
+      "W1": 1050,
+      "H1": 850,
+      "area": 892500,
+      "weight": 27.31,
+      "motor_power": 150
+    },
+    "bom_items": [
+      {
+        "ref_type": "MATERIAL",
+        "ref_id": 101,
+        "ref_code": "BR-001",
+        "ref_name": "표준 브라켓",
+        "quantity": 3.0,
+        "waste_rate": 0.05,
+        "total_quantity": 3.15,
+        "unit": "EA",
+        "unit_cost": 5000.0,
+        "total_cost": 15750.0,
+        "applied_rule": "표준 브라켓 선택",
+        "calculation_details": {
+          "condition_matched": true,
+          "quantity_expression": "ceiling(W1 / 500)",
+          "quantity_calculation": "ceiling(1050 / 500) = 3"
+        }
+      },
+      {
+        "ref_type": "MATERIAL",
+        "ref_id": 202,
+        "ref_code": "MT-002",
+        "ref_name": "고출력 모터",
+        "quantity": 1.0,
+        "waste_rate": 0.0,
+        "total_quantity": 1.0,
+        "unit": "EA",
+        "unit_cost": 45000.0,
+        "total_cost": 45000.0,
+        "applied_rule": "고출력 모터",
+        "calculation_details": {
+          "condition_matched": true,
+          "quantity_expression": "1",
+          "quantity_calculation": "1"
+        }
+      },
+      {
+        "ref_type": "MATERIAL",
+        "ref_id": 301,
+        "ref_code": "GD-001",
+        "ref_name": "가이드 레일",
+        "quantity": 2.0,
+        "waste_rate": 0.03,
+        "total_quantity": 2.06,
+        "unit": "EA",
+        "unit_cost": 12000.0,
+        "total_cost": 24720.0,
+        "applied_rule": "가이드 레일",
+        "calculation_details": {
+          "condition_matched": true,
+          "quantity_expression": "ceiling(H1 / 1000) * 2",
+          "quantity_calculation": "ceiling(850 / 1000) * 2 = 2"
+        }
+      },
+      {
+        "ref_type": "MATERIAL",
+        "ref_id": 401,
+        "ref_code": "CT-001",
+        "ref_name": "220V 컨트롤러",
+        "quantity": 1.0,
+        "waste_rate": 0.0,
+        "total_quantity": 1.0,
+        "unit": "EA",
+        "unit_cost": 25000.0,
+        "total_cost": 25000.0,
+        "applied_rule": "220V 컨트롤러",
+        "calculation_details": {
+          "condition_matched": true,
+          "quantity_expression": "1",
+          "quantity_calculation": "1"
+        }
+      }
+    ],
+    "summary": {
+      "total_materials": 4,
+      "total_cost": 110470.0,
+      "estimated_weight": 27.31
+    },
+    "validation_warnings": []
+  }
+}
+```
+
+### 5. 실제 제품 생성
+
+#### 매개변수 기반 제품 생성
+```http
+POST /v1/products/create-from-model
+Authorization: Bearer {token}
+X-API-KEY: {api-key}
+Content-Type: application/json
+
+{
+  "model_id": 1,
+  "input_parameters": {
+    "W0": 1000,
+    "H0": 800,
+    "installation_type": "A",
+    "power_source": "220V",
+    "color": "WHITE"
+  },
+  "product_code": "KSS01-1000x800-A",
+  "product_name": "KSS01 스크린 1000x800 A타입",
+  "category_id": 1,
+  "description": "매개변수 기반으로 생성된 맞춤형 전동 스크린",
+  "unit": "EA",
+  "min_order_qty": 1,
+  "lead_time_days": 7,
+  "is_active": true,
+  "create_bom_items": true,
+  "validate_bom": true
+}
+```
+
+**응답:**
+```json
+{
+  "success": true,
+  "message": "product.created_from_model",
+  "data": {
+    "product": {
+      "id": 123,
+      "code": "KSS01-1000x800-A",
+      "name": "KSS01 스크린 1000x800 A타입",
+      "type": "PRODUCT",
+      "category_id": 1,
+      "description": "매개변수 기반으로 생성된 맞춤형 전동 스크린",
+      "unit": "EA",
+      "min_order_qty": 1,
+      "lead_time_days": 7,
+      "is_active": true,
+      "created_at": "2024-01-01T00:00:00Z"
+    },
+    "input_parameters": {
+      "W0": 1000,
+      "H0": 800,
+      "installation_type": "A",
+      "power_source": "220V",
+      "color": "WHITE"
+    },
+    "calculated_values": {
+      "W1": 1050,
+      "H1": 850,
+      "area": 892500,
+      "weight": 27.31,
+      "motor_power": 150
+    },
+    "bom_items": [
+      {
+        "id": 1,
+        "ref_type": "MATERIAL",
+        "ref_id": 101,
+        "ref_code": "BR-001",
+        "ref_name": "표준 브라켓",
+        "quantity": 3.0,
+        "waste_rate": 0.05,
+        "unit": "EA"
+      },
+      {
+        "id": 2,
+        "ref_type": "MATERIAL",
+        "ref_id": 202,
+        "ref_code": "MT-002",
+        "ref_name": "고출력 모터",
+        "quantity": 1.0,
+        "waste_rate": 0.0,
+        "unit": "EA"
+      },
+      {
+        "id": 3,
+        "ref_type": "MATERIAL",
+        "ref_id": 301,
+        "ref_code": "GD-001",
+        "ref_name": "가이드 레일",
+        "quantity": 2.0,
+        "waste_rate": 0.03,
+        "unit": "EA"
+      },
+      {
+        "id": 4,
+        "ref_type": "MATERIAL",
+        "ref_id": 401,
+        "ref_code": "CT-001",
+        "ref_name": "220V 컨트롤러",
+        "quantity": 1.0,
+        "waste_rate": 0.0,
+        "unit": "EA"
+      }
+    ],
+    "summary": {
+      "total_bom_items": 4,
+      "model_id": 1,
+      "bom_template_id": 1
+    }
+  }
+}
+```
+
+### 6. 제품 매개변수 조회
+
+#### 생성된 제품의 매개변수 확인
+```http
+GET /v1/products/123/parameters
+Authorization: Bearer {token}
+X-API-KEY: {api-key}
+```
+
+**응답:**
+```json
+{
+  "success": true,
+  "message": "fetched",
+  "data": {
+    "product_id": 123,
+    "model_id": 1,
+    "input_parameters": {
+      "W0": 1000,
+      "H0": 800,
+      "installation_type": "A",
+      "power_source": "220V",
+      "color": "WHITE"
+    },
+    "parameter_definitions": [
+      {
+        "id": 1,
+        "name": "W0",
+        "label": "원본 가로 크기",
+        "type": "INPUT",
+        "data_type": "DECIMAL",
+        "unit": "mm",
+        "default_value": "1000",
+        "min_value": 500,
+        "max_value": 2000,
+        "description": "제품의 원본 가로 크기를 입력하세요"
+      }
+    ]
+  }
+}
+```
+
+### 7. 계산된 값 조회
+
+#### 생성된 제품의 계산값 확인
+```http
+GET /v1/products/123/calculated-values
+Authorization: Bearer {token}
+X-API-KEY: {api-key}
+```
+
+**응답:**
+```json
+{
+  "success": true,
+  "message": "fetched",
+  "data": {
+    "product_id": 123,
+    "model_id": 1,
+    "calculated_values": {
+      "W1": 1050,
+      "H1": 850,
+      "area": 892500,
+      "weight": 27.31,
+      "motor_power": 150
+    },
+    "formula_applications": [
+      {
+        "formula_name": "최종 가로 크기 계산",
+        "target_parameter": "W1",
+        "expression": "W0 + (installation_type == \"A\" ? 50 : 30)",
+        "calculated_value": 1050,
+        "execution_order": 1
+      },
+      {
+        "formula_name": "최종 세로 크기 계산",
+        "target_parameter": "H1",
+        "expression": "H0 + (installation_type == \"A\" ? 50 : 30)",
+        "calculated_value": 850,
+        "execution_order": 2
+      },
+      {
+        "formula_name": "면적 계산",
+        "target_parameter": "area",
+        "expression": "W1 * H1",
+        "calculated_value": 892500,
+        "execution_order": 3
+      },
+      {
+        "formula_name": "무게 계산",
+        "target_parameter": "weight",
+        "expression": "area * 0.000025 + 5",
+        "calculated_value": 27.31,
+        "execution_order": 4
+      },
+      {
+        "formula_name": "모터 파워 계산",
+        "target_parameter": "motor_power",
+        "expression": "weight > 20 ? 150 : 120",
+        "calculated_value": 150,
+        "execution_order": 5
+      }
+    ]
+  }
+}
+```
+
+## 시나리오별 테스트 케이스
+
+### 시나리오 1: 소형 B타입 스크린
+
+**입력 매개변수:**
+```json
+{
+  "W0": 600,
+  "H0": 500,
+  "installation_type": "B",
+  "power_source": "110V",
+  "color": "BLACK"
+}
+```
+
+**예상 결과:**
+- W1: 630 (600 + 30)
+- H1: 530 (500 + 30)
+- area: 333900
+- weight: 13.35 kg
+- motor_power: 120W (경량이므로 표준 모터)
+- 브라켓: 경량 브라켓 2개 (ceiling(630/600) = 2)
+- 컨트롤러: 110V 컨트롤러
+
+### 시나리오 2: 대형 A타입 스크린
+
+**입력 매개변수:**
+```json
+{
+  "W0": 1800,
+  "H0": 1200,
+  "installation_type": "A",
+  "power_source": "220V",
+  "color": "GRAY"
+}
+```
+
+**예상 결과:**
+- W1: 1850 (1800 + 50)
+- H1: 1250 (1200 + 50)
+- area: 2312500
+- weight: 62.81 kg
+- motor_power: 150W (중량이므로 고출력 모터)
+- 브라켓: 표준 브라켓 4개 (ceiling(1850/500) = 4)
+- 가이드 레일: 4개 (ceiling(1250/1000) * 2 = 4)
+
+### 시나리오 3: 경계값 테스트
+
+**입력 매개변수:**
+```json
+{
+  "W0": 500,
+  "H0": 400,
+  "installation_type": "C",
+  "power_source": "220V",
+  "color": "WHITE"
+}
+```
+
+**예상 결과:**
+- W1: 530 (500 + 30)
+- H1: 430 (400 + 30)
+- area: 227900
+- weight: 10.70 kg
+- motor_power: 120W
+- 브라켓: 경량 브라켓 1개 (ceiling(530/600) = 1)
+- 가이드 레일: 2개 (ceiling(430/1000) * 2 = 2)
+
+## 에러 처리
+
+### 매개변수 검증 실패
+```http
+POST /v1/design/models/1/validate-parameters
+Content-Type: application/json
+
+{
+  "input_parameters": {
+    "W0": 3000,  // 범위 초과
+    "H0": 200,   // 범위 미달
+    "installation_type": "D"  // 잘못된 값
+  }
+}
+```
+
+**응답:**
+```json
+{
+  "success": true,
+  "message": "parameters.validated",
+  "data": {
+    "is_valid": false,
+    "validation_errors": [
+      {
+        "parameter": "W0",
+        "error": "Value must be between 500 and 2000"
+      },
+      {
+        "parameter": "H0",
+        "error": "Value must be between 400 and 1500"
+      },
+      {
+        "parameter": "installation_type",
+        "error": "Value must be one of: A, B, C"
+      }
+    ],
+    "warnings": []
+  }
+}
+```
+
+### 공식 계산 오류
+```json
+{
+  "success": false,
+  "message": "error.formula.calculation_failed",
+  "errors": {
+    "code": "FORMULA_ERROR",
+    "message": "Division by zero in formula 'area_calculation'",
+    "details": {
+      "formula_id": 3,
+      "expression": "W1 * H1 / 0",
+      "input_values": {"W1": 1050, "H1": 850}
+    }
+  }
+}
+```
+
+## 성능 고려사항
+
+### 캐싱 전략
+- 모델별 매개변수 정의: Redis 캐시 (TTL: 1시간)
+- 공식 표현식: 메모리 캐시 (세션 기반)
+- BOM 템플릿: Redis 캐시 (TTL: 30분)
+
+### 최적화
+- 공식 실행 순서 최적화 (의존성 그래프)
+- BOM 규칙 우선순위 기반 조기 종료
+- 대량 생성시 배치 처리 지원
+
+### 제한사항
+- 동시 요청 제한: 테넌트당 100 req/min
+- 매개변수 개수 제한: 모델당 최대 50개
+- 공식 복잡도 제한: 중첩 깊이 최대 10단계
+- BOM 항목 제한: 템플릿당 최대 200개
+
+이 API 문서는 KSS01 모델을 예시로 한 완전한 매개변수 기반 BOM 시스템의 사용법을 제공합니다. 실제 구현시에는 각 비즈니스 요구사항에 맞게 매개변수와 규칙을 조정하여 사용할 수 있습니다.

docs/parameter-based-bom-endpoints.md

@@ -0,0 +1,264 @@
+# 매개변수 기반 BOM 시스템 API 엔드포인트
+
+## 엔드포인트 개요
+
+이 문서는 SAM 프로젝트의 매개변수 기반 BOM 시스템을 위한 모든 RESTful API 엔드포인트를 요약합니다.
+
+## 인증 및 권한
+
+- **API Key**: 모든 요청에 `X-API-KEY` 헤더 필요
+- **Bearer Token**: 사용자 컨텍스트가 필요한 요청에 `Authorization: Bearer {token}` 헤더 필요
+- **미들웨어**: `auth.apikey` + `auth:sanctum`
+
+## 매개변수 관리 API
+
+### 모델 매개변수
+
+| 메서드 | 엔드포인트 | 설명 | 권한 |
+|-------|-----------|------|------|
+| `GET` | `/v1/design/models/{modelId}/parameters` | 매개변수 목록 조회 | READ |
+| `POST` | `/v1/design/models/{modelId}/parameters` | 매개변수 생성 | CREATE |
+| `PUT` | `/v1/design/models/{modelId}/parameters/{parameterId}` | 매개변수 수정 | UPDATE |
+| `DELETE` | `/v1/design/models/{modelId}/parameters/{parameterId}` | 매개변수 삭제 | DELETE |
+
+**쿼리 파라미터 (GET):**
+- `page`: 페이지 번호 (기본값: 1)
+- `per_page`: 페이지당 항목 수 (기본값: 20)
+- `search`: 매개변수명/라벨 검색
+- `type`: 매개변수 타입 필터 (`INPUT`, `OUTPUT`)
+
+## 공식 관리 API
+
+### 모델 공식
+
+| 메서드 | 엔드포인트 | 설명 | 권한 |
+|-------|-----------|------|------|
+| `GET` | `/v1/design/models/{modelId}/formulas` | 공식 목록 조회 | READ |
+| `POST` | `/v1/design/models/{modelId}/formulas` | 공식 생성 | CREATE |
+| `PUT` | `/v1/design/models/{modelId}/formulas/{formulaId}` | 공식 수정 | UPDATE |
+| `DELETE` | `/v1/design/models/{modelId}/formulas/{formulaId}` | 공식 삭제 | DELETE |
+| `POST` | `/v1/design/models/{modelId}/formulas/{formulaId}/validate` | 공식 검증 | READ |
+
+**쿼리 파라미터 (GET):**
+- `page`: 페이지 번호
+- `per_page`: 페이지당 항목 수
+- `search`: 공식명/대상 매개변수 검색
+- `target_parameter`: 대상 매개변수 필터
+
+## 조건 규칙 관리 API
+
+### BOM 조건 규칙
+
+| 메서드 | 엔드포인트 | 설명 | 권한 |
+|-------|-----------|------|------|
+| `GET` | `/v1/design/bom-templates/{bomTemplateId}/condition-rules` | 조건 규칙 목록 조회 | READ |
+| `POST` | `/v1/design/bom-templates/{bomTemplateId}/condition-rules` | 조건 규칙 생성 | CREATE |
+| `PUT` | `/v1/design/bom-templates/{bomTemplateId}/condition-rules/{ruleId}` | 조건 규칙 수정 | UPDATE |
+| `DELETE` | `/v1/design/bom-templates/{bomTemplateId}/condition-rules/{ruleId}` | 조건 규칙 삭제 | DELETE |
+| `POST` | `/v1/design/bom-templates/{bomTemplateId}/condition-rules/{ruleId}/toggle` | 규칙 활성/비활성 토글 | UPDATE |
+
+**쿼리 파라미터 (GET):**
+- `page`: 페이지 번호
+- `per_page`: 페이지당 항목 수
+- `search`: 규칙명/대상 컴포넌트 검색
+- `ref_type`: 참조 타입 필터 (`MATERIAL`, `PRODUCT`)
+- `is_active`: 활성 상태 필터
+
+## 핵심 BOM 해석 API
+
+### BOM 해석 및 제품 생성
+
+| 메서드 | 엔드포인트 | 설명 | 권한 |
+|-------|-----------|------|------|
+| `POST` | `/v1/products/models/{modelId}/resolve-preview` | **실시간 BOM 미리보기** | READ |
+| `POST` | `/v1/products/create-from-model` | **제품 생성 + BOM 적용** | CREATE |
+| `POST` | `/v1/design/models/{modelId}/validate-parameters` | 매개변수 검증 | READ |
+
+### 제품 조회 API
+
+| 메서드 | 엔드포인트 | 설명 | 권한 |
+|-------|-----------|------|------|
+| `GET` | `/v1/products/{productId}/parameters` | 제품별 매개변수 조회 | READ |
+| `GET` | `/v1/products/{productId}/calculated-values` | 제품별 산출값 조회 | READ |
+
+## 주요 요청/응답 스키마
+
+### 실시간 BOM 미리보기 요청
+
+```json
+{
+  "input_parameters": {
+    "W0": 1000,
+    "H0": 800,
+    "installation_type": "A",
+    "power_source": "220V"
+  },
+  "include_calculated_values": true,
+  "include_bom_items": true
+}
+```
+
+### BOM 미리보기 응답
+
+```json
+{
+  "success": true,
+  "message": "bom.preview_generated",
+  "data": {
+    "input_parameters": { ... },
+    "calculated_values": {
+      "W1": 1050,
+      "H1": 850,
+      "area": 892500,
+      "weight": 27.31,
+      "motor_power": 150
+    },
+    "bom_items": [
+      {
+        "ref_type": "MATERIAL",
+        "ref_code": "BR-001",
+        "ref_name": "표준 브라켓",
+        "quantity": 3.0,
+        "waste_rate": 0.05,
+        "total_quantity": 3.15,
+        "unit_cost": 5000.0,
+        "total_cost": 15750.0,
+        "applied_rule": "표준 브라켓 선택"
+      }
+    ],
+    "summary": {
+      "total_materials": 4,
+      "total_cost": 110470.0,
+      "estimated_weight": 27.31
+    }
+  }
+}
+```
+
+### 제품 생성 요청
+
+```json
+{
+  "model_id": 1,
+  "input_parameters": {
+    "W0": 1000,
+    "H0": 800,
+    "installation_type": "A",
+    "power_source": "220V"
+  },
+  "product_code": "KSS01-1000x800-A",
+  "product_name": "KSS01 스크린 1000x800 A타입",
+  "category_id": 1,
+  "description": "매개변수 기반으로 생성된 맞춤형 스크린",
+  "create_bom_items": true,
+  "validate_bom": true
+}
+```
+
+### 제품 생성 응답
+
+```json
+{
+  "success": true,
+  "message": "product.created_from_model",
+  "data": {
+    "product": {
+      "id": 123,
+      "code": "KSS01-1000x800-A",
+      "name": "KSS01 스크린 1000x800 A타입",
+      "type": "PRODUCT"
+    },
+    "input_parameters": { ... },
+    "calculated_values": { ... },
+    "bom_items": [ ... ],
+    "summary": {
+      "total_bom_items": 4,
+      "model_id": 1,
+      "bom_template_id": 1
+    }
+  }
+}
+```
+
+## 매개변수 데이터 타입
+
+### 입력 매개변수 타입
+
+| 타입 | 설명 | 예시 |
+|------|------|------|
+| `INTEGER` | 정수 | `1000` |
+| `DECIMAL` | 소수 | `1000.5` |
+| `STRING` | 문자열 | `"A"` |
+| `BOOLEAN` | 불린 | `true` |
+
+### 공식 표현식 예시
+
+| 표현식 | 설명 |
+|--------|------|
+| `W0 + 50` | 단순 산술 연산 |
+| `W0 * H0` | 곱셈 연산 |
+| `installation_type == "A" ? 50 : 30` | 조건부 연산 |
+| `ceiling(W1 / 500)` | 수학 함수 |
+| `W0 > 1000 && H0 > 800` | 논리 연산 |
+
+### BOM 조건 규칙 예시
+
+| 조건 | 수량 공식 | 설명 |
+|------|-----------|------|
+| `installation_type == "A"` | `ceiling(W1 / 500)` | A타입일 때 너비 기반 수량 |
+| `motor_power >= 150` | `1` | 고출력 모터 조건 |
+| `true` | `ceiling(H1 / 1000) * 2` | 항상 적용되는 가이드 레일 |
+
+## 에러 코드
+
+### 일반 에러
+
+| 코드 | 메시지 | 설명 |
+|------|--------|------|
+| `400` | `Bad Request` | 잘못된 요청 |
+| `401` | `Unauthorized` | 인증 실패 |
+| `403` | `Forbidden` | 권한 없음 |
+| `404` | `Not Found` | 리소스 없음 |
+| `422` | `Validation Error` | 입력 검증 실패 |
+
+### 비즈니스 로직 에러
+
+| 코드 | 메시지 키 | 설명 |
+|------|-----------|------|
+| `400` | `error.model.not_found` | 모델을 찾을 수 없음 |
+| `400` | `error.parameter.invalid_type` | 잘못된 매개변수 타입 |
+| `400` | `error.formula.syntax_error` | 공식 구문 오류 |
+| `400` | `error.bom.resolution_failed` | BOM 해석 실패 |
+| `400` | `error.product.duplicate_code` | 제품 코드 중복 |
+
+## 제한사항
+
+### Rate Limiting
+- **일반 요청**: 테넌트당 1000 req/hour
+- **BOM 해석**: 테넌트당 100 req/hour
+- **제품 생성**: 테넌트당 50 req/hour
+
+### 데이터 제한
+- **매개변수**: 모델당 최대 50개
+- **공식**: 모델당 최대 100개
+- **조건 규칙**: BOM 템플릿당 최대 200개
+- **BOM 항목**: 제품당 최대 500개
+
+### 성능 고려사항
+- **복잡한 공식**: 중첩 깊이 최대 10단계
+- **대용량 BOM**: 1000개 이상 항목시 배치 처리 권장
+- **동시 생성**: 동일 모델 기반 제품 동시 생성시 순차 처리
+
+## Swagger 문서
+
+전체 API 스펙은 Swagger UI에서 확인할 수 있습니다:
+- **Swagger UI**: `/api-docs/index.html`
+- **JSON Spec**: `/docs/api-docs.json`
+
+### 주요 태그
+- `Model Parameters`: 모델 매개변수 관리
+- `Model Formulas`: 모델 공식 관리
+- `BOM Condition Rules`: BOM 조건 규칙 관리
+- `BOM Resolver`: BOM 해석 및 제품 생성
+
+각 엔드포인트는 상세한 요청/응답 스키마와 예시를 포함하고 있습니다.

docs/parametric_bom_schema.md

@@ -0,0 +1,250 @@
+# KSS01 매개변수 기반 BOM 시스템 데이터베이스 스키마
+
+## 개요
+
+KSS01 모델을 위한 매개변수 기반 BOM 시스템의 데이터베이스 스키마입니다.
+기존 SAM 프로젝트의 models, model_versions, bom_templates, bom_template_items 구조를 확장하여
+동적 매개변수 입력과 공식 기반 BOM 생성을 지원합니다.
+
+## 테이블 구조
+
+### 1. bom_template_groups
+BOM 아이템들의 그룹핑을 지원하는 테이블입니다.
+
+**주요 기능:**
+- 계층적 그룹 구조 지원 (parent_group_id를 통한 self-referencing)
+- 본체, 절곡물, 가이드레일 등의 논리적 그룹핑
+- 표시 순서 관리
+
+**핵심 컬럼:**
+- `group_name`: 그룹명 (본체, 절곡물, 가이드레일 등)
+- `parent_group_id`: 상위 그룹 ID (계층 구조)
+- `display_order`: 표시 순서
+
+### 2. model_parameters
+모델별 입력 매개변수 정의를 관리하는 테이블입니다.
+
+**주요 기능:**
+- 매개변수 타입별 유효성 검사 (INTEGER, DECIMAL, STRING, BOOLEAN)
+- 숫자형 매개변수의 범위 제한 (min_value, max_value)
+- 선택형 매개변수의 허용값 정의 (allowed_values JSON)
+- 단위 및 설명 관리
+
+**핵심 컬럼:**
+- `parameter_name`: 매개변수명 (W0, H0, screen_type 등)
+- `parameter_type`: 매개변수 타입
+- `allowed_values`: 허용값 목록 (JSON)
+- `min_value/max_value`: 숫자형 범위 제한
+
+**JSON 구조 예시:**
+```json
+{
+  "allowed_values": ["SCREEN", "STEEL", "ALUMINUM"]
+}
+```
+
+### 3. model_formulas
+매개변수를 기반으로 한 계산 공식 정의를 관리하는 테이블입니다.
+
+**주요 기능:**
+- 수학적 공식 표현식 저장
+- 계산 순서 관리 (의존성 해결)
+- 결과 타입 및 소수점 자릿수 제어
+- 의존 변수 추적
+
+**핵심 컬럼:**
+- `formula_name`: 공식명 (W1, H1, area, weight 등)
+- `formula_expression`: 공식 표현식 ("W0 + 100", "W0 * H0 / 1000000")
+- `calculation_order`: 계산 순서
+- `dependencies`: 의존 변수 목록 (JSON)
+
+**공식 예시:**
+```
+W1 = W0 + 100
+H1 = H0 + 50
+area = W1 * H1 / 1000000
+weight = area * thickness * density
+```
+
+### 4. bom_condition_rules
+조건부 BOM 구성 규칙을 관리하는 테이블입니다.
+
+**주요 기능:**
+- 조건식 기반 제품 포함/제외
+- 수량 계산 공식 적용
+- 우선순위 기반 규칙 실행
+- 그룹 또는 개별 제품 대상 지정
+
+**핵심 컬럼:**
+- `condition_expression`: 조건 표현식 ("screen_type == 'SCREEN'")
+- `action_type`: 액션 타입 (INCLUDE_PRODUCT, EXCLUDE_PRODUCT, SET_QUANTITY)
+- `quantity_formula`: 수량 계산 공식
+- `priority`: 실행 우선순위
+
+**조건 규칙 예시:**
+```
+IF screen_type == "SCREEN" THEN INCLUDE_PRODUCT 실리카겔
+IF W0 > 1000 THEN SET_QUANTITY 가이드레일 = ceiling(W0/1000)
+```
+
+### 5. product_parameters
+실제 제품별 매개변수 값을 저장하는 테이블입니다.
+
+**주요 기능:**
+- 견적/주문별 매개변수 값 저장
+- 상태 관리 (DRAFT, CALCULATED, APPROVED)
+- 제품 코드 연결
+- 버전 관리 지원
+
+**핵심 컬럼:**
+- `parameter_values`: 매개변수 값들 (JSON)
+- `status`: 상태 관리
+- `product_code`: 제품 코드 참조
+
+**JSON 구조 예시:**
+```json
+{
+  "W0": 1200,
+  "H0": 800,
+  "screen_type": "SCREEN",
+  "power_source": "AC220V",
+  "installation_type": "WALL_MOUNT"
+}
+```
+
+### 6. product_calculated_values
+매개변수 기반 계산 결과를 저장하는 테이블입니다.
+
+**주요 기능:**
+- 공식 계산 결과 캐싱
+- BOM 스냅샷 저장
+- 계산 유효성 관리
+- 비용/중량 집계
+
+**핵심 컬럼:**
+- `calculated_values`: 계산된 값들 (JSON)
+- `bom_snapshot`: BOM 결과 스냅샷 (JSON)
+- `is_valid`: 계산 유효성
+- `total_cost/total_weight`: 집계 정보
+
+**JSON 구조 예시:**
+```json
+{
+  "calculated_values": {
+    "W1": 1300,
+    "H1": 850,
+    "area": 1.105,
+    "weight": 45.2
+  },
+  "bom_snapshot": [
+    {
+      "product_id": 1001,
+      "product_name": "스크린 프레임",
+      "quantity": 1,
+      "group_name": "본체"
+    },
+    {
+      "product_id": 2001,
+      "product_name": "가이드레일",
+      "quantity": 2,
+      "group_name": "가이드"
+    }
+  ]
+}
+```
+
+## 기존 테이블 수정사항
+
+### bom_template_items 테이블 확장
+- `group_id`: BOM 그룹 연결
+- `is_conditional`: 조건부 아이템 여부
+- `condition_expression`: 조건 표현식
+- `quantity_formula`: 수량 계산 공식
+
+### products 테이블 확장
+- `is_parametric`: 매개변수 기반 제품 여부
+- `base_model_id`: 기반 모델 연결
+- `parameter_values`: 매개변수 값 (JSON)
+- `calculated_values`: 계산값 (JSON)
+
+## 데이터 플로우
+
+### 1. 설계 단계
+```
+models → model_parameters (매개변수 정의)
+      → model_formulas (공식 정의)
+      → bom_template_groups (그룹 정의)
+      → bom_condition_rules (조건 규칙)
+      → bom_template_items (기본 BOM + 그룹 연결)
+```
+
+### 2. 견적/주문 단계
+```
+견적 요청 → product_parameters (매개변수 입력)
+         → 공식 계산 엔진 실행
+         → product_calculated_values (결과 저장)
+         → BOM 생성 및 스냅샷 저장
+```
+
+### 3. 계산 엔진 프로세스
+1. **매개변수 검증**: model_parameters 기반 유효성 검사
+2. **공식 계산**: model_formulas의 calculation_order 순서로 실행
+3. **조건 평가**: bom_condition_rules의 priority 순서로 평가
+4. **BOM 구성**: 조건 결과에 따른 제품 포함/제외 및 수량 계산
+5. **결과 저장**: product_calculated_values에 스냅샷 저장
+
+## 성능 최적화
+
+### 인덱스 전략
+- **복합 인덱스**: (tenant_id, model_id) 기반 조회 최적화
+- **정렬 인덱스**: display_order, priority, calculation_order
+- **유니크 인덱스**: 논리적 중복 방지
+
+### 캐싱 전략
+- **계산 결과 캐싱**: product_calculated_values로 반복 계산 방지
+- **BOM 스냅샷**: 조건부 계산 결과 캐싱
+- **유효성 플래그**: is_valid로 재계산 필요 여부 판단
+
+### JSON 컬럼 활용
+- **스키마 유연성**: 매개변수/계산값의 동적 구조 지원
+- **성능 고려**: 필요시 가상 컬럼으로 자주 조회되는 값 추출 가능
+
+## 보안 및 제약사항
+
+### 공식 표현식 보안
+- **안전한 연산만 허용**: 수학 연산자, 함수명 화이트리스트
+- **코드 실행 방지**: eval() 등 동적 코드 실행 금지
+- **입력 검증**: 공식 구문 분석 및 검증
+
+### 다중 테넌트 지원
+- **테넌트 격리**: 모든 테이블에 tenant_id 적용
+- **글로벌 스코프**: BelongsToTenant 자동 적용
+- **권한 관리**: 테넌트별 접근 제어
+
+## 확장성 고려사항
+
+### 모델 타입 확장
+- **다른 제품군**: 현재 스키마로 다양한 제품 모델 지원 가능
+- **공식 엔진**: 모델별 독립적인 공식 정의
+- **조건 규칙**: 제품군별 특화된 비즈니스 로직 구현
+
+### 계산 엔진 확장
+- **외부 API**: 복잡한 계산을 위한 외부 서비스 연동 가능
+- **배치 처리**: 대량 계산 요청 처리 지원
+- **이력 관리**: 계산 과정 및 결과 이력 추적 가능
+
+## 예상 API 엔드포인트
+
+### 설계용 API
+- `GET /v1/models/{id}/parameters` - 모델 매개변수 목록
+- `POST /v1/models/{id}/parameters` - 매개변수 정의 추가
+- `GET /v1/models/{id}/formulas` - 공식 목록
+- `POST /v1/models/{id}/formulas` - 공식 정의 추가
+- `GET /v1/models/{id}/bom-rules` - 조건 규칙 목록
+- `POST /v1/models/{id}/bom-rules` - 조건 규칙 추가
+
+### 계산용 API
+- `POST /v1/models/{id}/calculate` - 매개변수 기반 BOM 계산
+- `GET /v1/product-parameters/{id}/calculated` - 계산 결과 조회
+- `POST /v1/product-parameters/{id}/recalculate` - 재계산 요청
+- `GET /v1/models/{id}/bom-preview` - BOM 미리보기 (매개변수별)