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 계산 메서드 없음

변경 후:

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

변경 후:

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

추가된 라우트:

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단계 디버깅)

✅ 테스트 체크리스트

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

⚠️ 배포 시 주의사항

• 특이사항 없음
• 기존 API에 영향 없음 (신규 엔드포인트 추가)

🔗 관련 문서

• 계획 문서: docs/plans/quote-calculation-api-plan.md
• FormulaEvaluatorService: api/app/Services/Quote/FormulaEvaluatorService.php

📊 API 사용 예시

요청

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
  }'

응답

{
  "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": [...]
  }
}