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