sam-docs/changes/20260102_quote_bom_calculation_api.md

# 변경 내용 요약

**날짜:** 2026-01-02
**작업자:** Claude Code
**작업명:** 견적 산출 API 개발 - Phase 1.1 API 계산 로직 구현

## 📋 변경 개요
MNG FormulaEvaluatorService의 BOM 기반 견적 계산 로직을 API에서 호출할 수 있는 엔드포인트를 구현했습니다. 완제품 코드와 입력 변수를 받아 품목/단가/금액을 자동 계산하며, 10단계 디버깅 정보를 제공합니다.

## 📁 수정된 파일

### 신규 파일
- `api/app/Http/Requests/Quote/QuoteBomCalculateRequest.php` - BOM 계산용 FormRequest

### 수정된 파일
- `api/app/Services/Quote/QuoteCalculationService.php` - calculateBom 메서드 추가
- `api/app/Http/Controllers/Api/V1/QuoteController.php` - calculateBom 액션 추가
- `api/routes/api.php` - /calculate/bom 라우트 추가
- `api/app/Swagger/v1/QuoteApi.php` - 스키마 및 엔드포인트 문서 추가

## 🔧 상세 변경 사항

### 1. QuoteBomCalculateRequest.php (신규)
**목적:** BOM 기반 견적 계산 요청 검증

**주요 기능:**
- 필수 입력: `finished_goods_code`, `W0`, `H0`
- 선택 입력: `QTY`, `PC`, `GT`, `MP`, `CT`, `WS`, `INSP`, `debug`
- `getInputVariables()`: 서비스용 입력 변수 배열 반환

### 2. QuoteCalculationService.php
**변경 전:** BOM 계산 메서드 없음

**변경 후:**
```php
public function calculateBom(string $finishedGoodsCode, array $inputs, bool $debug = false): array
{
    $tenantId = $this->tenantId();
    $result = $this->formulaEvaluator->calculateBomWithDebug(
        $finishedGoodsCode,
        $inputs,
        $tenantId
    );
    if (! $debug && isset($result['debug_steps'])) {
        unset($result['debug_steps']);
    }
    return $result;
}
```

**이유:** API에서 MNG FormulaEvaluatorService의 calculateBomWithDebug를 호출할 수 있도록 브릿지 메서드 추가

### 3. QuoteController.php
**변경 후:**
```php
public function calculateBom(QuoteBomCalculateRequest $request)
{
    return ApiResponse::handle(function () use ($request) {
        return $this->calculationService->calculateBom(
            $request->finished_goods_code,
            $request->getInputVariables(),
            $request->boolean('debug', false)
        );
    }, __('message.quote.calculated'));
}
```

**이유:** REST API 엔드포인트 제공

### 4. routes/api.php
**추가된 라우트:**
```php
Route::post('/calculate/bom', [QuoteController::class, 'calculateBom'])->name('v1.quotes.calculate-bom');
```

### 5. QuoteApi.php (Swagger)
**추가된 스키마:**
- `QuoteBomCalculateRequest` - 요청 스키마
- `QuoteBomCalculationResult` - 응답 스키마

**추가된 엔드포인트:**
- `POST /api/v1/quotes/calculate/bom` - BOM 기반 자동산출 (10단계 디버깅)

## ✅ 테스트 체크리스트
- [x] PHP 문법 검사 통과
- [x] Pint 코드 스타일 검사 통과
- [x] 라우트 등록 확인
- [x] 서비스 로직 검증 (tinker)
- [x] Swagger 문서 생성 확인
- [ ] 실제 API 호출 테스트 (Docker 환경 필요)

## ⚠️ 배포 시 주의사항
- 특이사항 없음
- 기존 API에 영향 없음 (신규 엔드포인트 추가)

## 🔗 관련 문서
- 계획 문서: `docs/plans/quote-calculation-api-plan.md`
- FormulaEvaluatorService: `api/app/Services/Quote/FormulaEvaluatorService.php`

## 📊 API 사용 예시

### 요청
```bash
curl -X POST "http://api.sam.kr/api/v1/quotes/calculate/bom" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "finished_goods_code": "SC-1000",
    "W0": 3000,
    "H0": 2500,
    "QTY": 1,
    "PC": "SCREEN",
    "GT": "wall",
    "MP": "single",
    "CT": "basic",
    "debug": true
  }'
```

### 응답
```json
{
  "success": true,
  "message": "견적이 산출되었습니다.",
  "data": {
    "success": true,
    "finished_goods": {"code": "SC-1000", "name": "전동스크린 1000형"},
    "variables": {"W0": 3000, "H0": 2500, "W1": 3100, "H1": 2650, "M": 8.215, "K": 12.5},
    "items": [...],
    "grouped_items": {...},
    "subtotals": {"material": 500000, "labor": 100000, "install": 50000},
    "grand_total": 650000,
    "debug_steps": [...]
  }
}
```