sam-api/docs/parametric_bom_schema.md

# 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 미리보기 (매개변수별)