# 매개변수 기반 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 해석 및 제품 생성

각 엔드포인트는 상세한 요청/응답 스키마와 예시를 포함하고 있습니다.