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 구조 예시:

{
  "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 구조 예시:

{
  "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 구조 예시:

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