From b2ddb9bae17e6589726ae43547596040e3467d64 Mon Sep 17 00:00:00 2001
From: kent <shine1324@gmail.com>
Date: Fri, 2 Jan 2026 11:27:44 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20BOM=20=EA=B8=B0=EB=B0=98=20=EA=B2=AC?=
 =?UTF-8?q?=EC=A0=81=20=EA=B3=84=EC=82=B0=20API=20=EB=B3=80=EA=B2=BD=20?=
 =?UTF-8?q?=EB=82=B4=EC=9A=A9=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Phase 1.1 API 계산 로직 구현 변경사항 문서화
- POST /api/v1/quotes/calculate/bom 엔드포인트 사용법

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 changes/20260102_quote_bom_calculation_api.md | 136 ++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 changes/20260102_quote_bom_calculation_api.md

diff --git a/changes/20260102_quote_bom_calculation_api.md b/changes/20260102_quote_bom_calculation_api.md
new file mode 100644
index 0000000..7b1c632
--- /dev/null
+++ b/changes/20260102_quote_bom_calculation_api.md
@@ -0,0 +1,136 @@
+# 변경 내용 요약
+
+**날짜:** 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": [...]
+  }
+}
+```
\ No newline at end of file