feat: Phase 1.2 - 다건 BOM 기반 자동산출 API 구현

- QuoteBomBulkCalculateRequest 생성 (React camelCase → API 약어 변환) - QuoteCalculationService.calculateBomBulk() 메서드 추가 - POST /api/v1/quotes/calculate/bom/bulk 엔드포인트 추가 - Swagger 스키마 및 문서 업데이트 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-02 13:13:50 +09:00
parent 660300cebf
commit 4e59bbf574
6 changed files with 499 additions and 0 deletions
--- a/app/Http/Controllers/Api/V1/QuoteController.php
+++ b/app/Http/Controllers/Api/V1/QuoteController.php
@@ -4,6 +4,7 @@

 use App\Helpers\ApiResponse;
 use App\Http\Controllers\Controller;
+use App\Http\Requests\Quote\QuoteBomBulkCalculateRequest;
 use App\Http\Requests\Quote\QuoteBomCalculateRequest;
 use App\Http\Requests\Quote\QuoteBulkDeleteRequest;
 use App\Http\Requests\Quote\QuoteCalculateRequest;
@@ -162,6 +163,23 @@ public function calculateBom(QuoteBomCalculateRequest $request)
        }, __('message.quote.calculated'));
    }

+    /**
+     * 다건 BOM 기반 자동산출
+     *
+     * React 견적등록 화면에서 여러 품목의 완제품 코드와 입력 변수를 받아
+     * BOM 기반으로 일괄 계산합니다.
+     * React QuoteFormItem 필드명(camelCase)과 API 변수명(약어) 모두 지원합니다.
+     */
+    public function calculateBomBulk(QuoteBomBulkCalculateRequest $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->calculationService->calculateBomBulk(
+                $request->getInputItems(),
+                $request->boolean('debug', false)
+            );
+        }, __('message.quote.bulk_calculated'));
+    }
+
    /**
     * 자동산출 입력 스키마 조회
     */
--- a/app/Http/Requests/Quote/QuoteBomBulkCalculateRequest.php
+++ b/app/Http/Requests/Quote/QuoteBomBulkCalculateRequest.php
@@ -0,0 +1,168 @@
+<?php
+
+namespace App\Http\Requests\Quote;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+/**
+ * 다건 BOM 기반 견적 산출 요청
+ *
+ * React 견적등록 화면에서 여러 품목의 자동 견적 산출 시 사용됩니다.
+ * React QuoteFormItem 인터페이스의 필드명(camelCase)과
+ * API 입력 변수(W0, H0 등)를 모두 지원합니다.
+ */
+class QuoteBomBulkCalculateRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            // 품목 배열 (최소 1개, 최대 100개)
+            'items' => 'required|array|min:1|max:100',
+
+            // 각 품목별 필수 입력
+            'items.*.finished_goods_code' => 'required|string|max:50',
+
+            // React 필드명 (camelCase) - 우선 적용
+            'items.*.openWidth' => 'nullable|numeric|min:100|max:20000',
+            'items.*.openHeight' => 'nullable|numeric|min:100|max:20000',
+            'items.*.quantity' => 'nullable|integer|min:1',
+            'items.*.productCategory' => 'nullable|string|in:SCREEN,STEEL',
+            'items.*.guideRailType' => 'nullable|string|in:wall,ceiling,floor',
+            'items.*.motorPower' => 'nullable|string|in:single,three',
+            'items.*.controller' => 'nullable|string|in:basic,smart,premium',
+            'items.*.wingSize' => 'nullable|numeric|min:0|max:500',
+            'items.*.inspectionFee' => 'nullable|numeric|min:0',
+
+            // API 변수명 (약어) - React 필드명이 없을 때 사용
+            'items.*.W0' => 'nullable|numeric|min:100|max:20000',
+            'items.*.H0' => 'nullable|numeric|min:100|max:20000',
+            'items.*.QTY' => 'nullable|integer|min:1',
+            'items.*.PC' => 'nullable|string|in:SCREEN,STEEL',
+            'items.*.GT' => 'nullable|string|in:wall,ceiling,floor',
+            'items.*.MP' => 'nullable|string|in:single,three',
+            'items.*.CT' => 'nullable|string|in:basic,smart,premium',
+            'items.*.WS' => 'nullable|numeric|min:0|max:500',
+            'items.*.INSP' => 'nullable|numeric|min:0',
+
+            // 디버그 모드 (개발용)
+            'debug' => 'nullable|boolean',
+        ];
+    }
+
+    public function attributes(): array
+    {
+        return [
+            'items' => __('validation.attributes.items'),
+            'items.*.finished_goods_code' => __('validation.attributes.finished_goods_code'),
+            'items.*.openWidth' => __('validation.attributes.open_width'),
+            'items.*.openHeight' => __('validation.attributes.open_height'),
+            'items.*.quantity' => __('validation.attributes.quantity'),
+            'items.*.productCategory' => __('validation.attributes.product_category'),
+            'items.*.guideRailType' => __('validation.attributes.guide_rail_type'),
+            'items.*.motorPower' => __('validation.attributes.motor_power'),
+            'items.*.controller' => __('validation.attributes.controller'),
+            'items.*.wingSize' => __('validation.attributes.wing_size'),
+            'items.*.inspectionFee' => __('validation.attributes.inspection_fee'),
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'items.required' => __('error.items_required'),
+            'items.min' => __('error.items_min'),
+            'items.max' => __('error.items_max'),
+            'items.*.finished_goods_code.required' => __('error.finished_goods_code_required'),
+        ];
+    }
+
+    /**
+     * 입력 품목 배열 반환 (FormulaEvaluatorService용)
+     *
+     * React 필드명(camelCase)과 API 변수명(약어) 모두 지원
+     * React 필드명 우선, 없으면 API 변수명 사용
+     *
+     * @return array<int, array{finished_goods_code: string, inputs: array}>
+     */
+    public function getInputItems(): array
+    {
+        $validated = $this->validated();
+        $result = [];
+
+        foreach ($validated['items'] as $index => $item) {
+            $result[] = [
+                'index' => $index,
+                'finished_goods_code' => $item['finished_goods_code'],
+                'inputs' => $this->normalizeInputVariables($item),
+            ];
+        }
+
+        return $result;
+    }
+
+    /**
+     * 단일 품목의 입력 변수 정규화
+     *
+     * React 필드명 → API 변수명 매핑
+     * - openWidth → W0
+     * - openHeight → H0
+     * - quantity → QTY
+     * - productCategory → PC
+     * - guideRailType → GT
+     * - motorPower → MP
+     * - controller → CT
+     * - wingSize → WS
+     * - inspectionFee → INSP
+     */
+    private function normalizeInputVariables(array $item): array
+    {
+        return [
+            'W0' => (float) ($item['openWidth'] ?? $item['W0'] ?? 0),
+            'H0' => (float) ($item['openHeight'] ?? $item['H0'] ?? 0),
+            'QTY' => (int) ($item['quantity'] ?? $item['QTY'] ?? 1),
+            'PC' => $item['productCategory'] ?? $item['PC'] ?? 'SCREEN',
+            'GT' => $item['guideRailType'] ?? $item['GT'] ?? 'wall',
+            'MP' => $item['motorPower'] ?? $item['MP'] ?? 'single',
+            'CT' => $item['controller'] ?? $item['CT'] ?? 'basic',
+            'WS' => (float) ($item['wingSize'] ?? $item['WS'] ?? 50),
+            'INSP' => (float) ($item['inspectionFee'] ?? $item['INSP'] ?? 50000),
+        ];
+    }
+
+    /**
+     * 필수 입력 검증 (W0, H0)
+     *
+     * React 필드명이든 API 변수명이든 둘 중 하나는 있어야 함
+     */
+    public function withValidator($validator): void
+    {
+        $validator->after(function ($validator) {
+            $items = $this->input('items', []);
+
+            foreach ($items as $index => $item) {
+                // W0 (openWidth 또는 W0) 검증
+                $w0 = $item['openWidth'] ?? $item['W0'] ?? null;
+                if ($w0 === null || $w0 === '') {
+                    $validator->errors()->add(
+                        "items.{$index}.openWidth",
+                        __('error.open_width_required')
+                    );
+                }
+
+                // H0 (openHeight 또는 H0) 검증
+                $h0 = $item['openHeight'] ?? $item['H0'] ?? null;
+                if ($h0 === null || $h0 === '') {
+                    $validator->errors()->add(
+                        "items.{$index}.openHeight",
+                        __('error.open_height_required')
+                    );
+                }
+            }
+        });
+    }
+}
--- a/app/Services/Quote/QuoteCalculationService.php
+++ b/app/Services/Quote/QuoteCalculationService.php
@@ -113,6 +113,70 @@ public function calculateBom(string $finishedGoodsCode, array $inputs, bool $deb
        return $result;
    }

+    /**
+     * 다건 BOM 기반 견적 산출
+     *
+     * 여러 품목의 견적을 일괄 계산합니다.
+     * React 견적등록 화면에서 품목 목록의 자동 견적 산출 시 호출됩니다.
+     *
+     * @param  array  $inputItems  입력 품목 배열 (QuoteBomBulkCalculateRequest::getInputItems() 결과)
+     * @param  bool  $debug  디버그 모드 (기본 false)
+     * @return array 산출 결과 배열
+     */
+    public function calculateBomBulk(array $inputItems, bool $debug = false): array
+    {
+        $results = [];
+        $successCount = 0;
+        $failCount = 0;
+        $grandTotal = 0;
+
+        foreach ($inputItems as $item) {
+            $index = $item['index'];
+            $finishedGoodsCode = $item['finished_goods_code'];
+            $inputs = $item['inputs'];
+
+            try {
+                $result = $this->calculateBom($finishedGoodsCode, $inputs, $debug);
+
+                if ($result['success'] ?? false) {
+                    $successCount++;
+                    $grandTotal += $result['grand_total'] ?? 0;
+                } else {
+                    $failCount++;
+                }
+
+                $results[] = [
+                    'index' => $index,
+                    'finished_goods_code' => $finishedGoodsCode,
+                    'inputs' => $inputs,
+                    'result' => $result,
+                ];
+            } catch (\Throwable $e) {
+                $failCount++;
+                $results[] = [
+                    'index' => $index,
+                    'finished_goods_code' => $finishedGoodsCode,
+                    'inputs' => $inputs,
+                    'result' => [
+                        'success' => false,
+                        'error' => $e->getMessage(),
+                    ],
+                ];
+            }
+        }
+
+        return [
+            'success' => $failCount === 0,
+            'summary' => [
+                'total_count' => count($inputItems),
+                'success_count' => $successCount,
+                'fail_count' => $failCount,
+                'grand_total' => round($grandTotal, 2),
+            ],
+            'items' => $results,
+        ];
+    }
+
    /**
     * 견적 품목 재계산 (기존 견적 기준)
     */
--- a/app/Swagger/v1/QuoteApi.php
+++ b/app/Swagger/v1/QuoteApi.php
@@ -271,6 +271,66 @@
 * )
 *
 * @OA\Schema(
+ *   schema="QuoteBomBulkCalculateRequest",
+ *   type="object",
+ *   required={"items"},
+ *   description="다건 BOM 기반 자동산출 요청. React QuoteFormItem 필드명(camelCase)과 API 변수명(약어) 모두 지원합니다.",
+ *
+ *   @OA\Property(property="items", type="array", minItems=1, description="견적 품목 배열",
+ *     @OA\Items(ref="#/components/schemas/QuoteBomBulkItemInput")
+ *   ),
+ *   @OA\Property(property="debug", type="boolean", example=false, description="디버그 모드 (10단계 디버깅 정보 포함)")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="QuoteBomBulkItemInput",
+ *   type="object",
+ *   required={"finished_goods_code"},
+ *   description="개별 품목 입력. React QuoteFormItem 필드명(camelCase)과 API 변수명(약어) 모두 지원합니다.",
+ *
+ *   @OA\Property(property="finished_goods_code", type="string", example="SC-1000", description="완제품 코드 (items.code where item_type='FG')"),
+ *   @OA\Property(property="openWidth", type="number", format="float", example=3000, description="개구부 폭(mm) - React 필드명"),
+ *   @OA\Property(property="openHeight", type="number", format="float", example=2500, description="개구부 높이(mm) - React 필드명"),
+ *   @OA\Property(property="quantity", type="integer", example=1, description="수량 - React 필드명"),
+ *   @OA\Property(property="productCategory", type="string", example="SCREEN", description="제품 카테고리 - React 필드명"),
+ *   @OA\Property(property="guideRailType", type="string", example="wall", description="가이드레일 타입 - React 필드명"),
+ *   @OA\Property(property="motorPower", type="string", example="single", description="모터 전원 - React 필드명"),
+ *   @OA\Property(property="controller", type="string", example="basic", description="컨트롤러 - React 필드명"),
+ *   @OA\Property(property="wingSize", type="number", format="float", example=50, description="날개 크기 - React 필드명"),
+ *   @OA\Property(property="inspectionFee", type="number", format="float", example=50000, description="검사비 - React 필드명"),
+ *   @OA\Property(property="W0", type="number", format="float", example=3000, description="개구부 폭(mm) - API 변수명"),
+ *   @OA\Property(property="H0", type="number", format="float", example=2500, description="개구부 높이(mm) - API 변수명"),
+ *   @OA\Property(property="QTY", type="integer", example=1, description="수량 - API 변수명"),
+ *   @OA\Property(property="PC", type="string", example="SCREEN", description="제품 카테고리 - API 변수명"),
+ *   @OA\Property(property="GT", type="string", example="wall", description="가이드레일 타입 - API 변수명"),
+ *   @OA\Property(property="MP", type="string", example="single", description="모터 전원 - API 변수명"),
+ *   @OA\Property(property="CT", type="string", example="basic", description="컨트롤러 - API 변수명"),
+ *   @OA\Property(property="WS", type="number", format="float", example=50, description="날개 크기 - API 변수명"),
+ *   @OA\Property(property="INSP", type="number", format="float", example=50000, description="검사비 - API 변수명")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="QuoteBomBulkCalculationResult",
+ *   type="object",
+ *
+ *   @OA\Property(property="success", type="boolean", example=true, description="전체 성공 여부 (실패 건이 없으면 true)"),
+ *   @OA\Property(property="summary", type="object", description="처리 요약",
+ *     @OA\Property(property="total_count", type="integer", example=3, description="전체 품목 수"),
+ *     @OA\Property(property="success_count", type="integer", example=2, description="성공 건수"),
+ *     @OA\Property(property="fail_count", type="integer", example=1, description="실패 건수"),
+ *     @OA\Property(property="grand_total", type="number", format="float", example=1500000, description="성공한 품목 총계")
+ *   ),
+ *   @OA\Property(property="items", type="array", description="품목별 산출 결과",
+ *     @OA\Items(type="object",
+ *       @OA\Property(property="index", type="integer", example=0, description="요청 배열에서의 인덱스"),
+ *       @OA\Property(property="finished_goods_code", type="string", example="SC-1000"),
+ *       @OA\Property(property="inputs", type="object", description="정규화된 입력 변수"),
+ *       @OA\Property(property="result", ref="#/components/schemas/QuoteBomCalculationResult")
+ *     )
+ *   )
+ * )
+ *
+ * @OA\Schema(
 *   schema="QuoteBomCalculationResult",
 *   type="object",
 *
@@ -576,6 +636,39 @@ public function calculate() {}
     */
    public function calculateBom() {}

+    /**
+     * @OA\Post(
+     *   path="/api/v1/quotes/calculate/bom/bulk",
+     *   tags={"Quote"},
+     *   summary="다건 BOM 기반 자동산출",
+     *   description="여러 품목의 완제품 코드와 입력 변수를 받아 BOM 기반으로 일괄 계산합니다. React QuoteFormItem 필드명(camelCase)과 API 변수명(약어) 모두 지원합니다.",
+     *   security={{"BearerAuth":{}}},
+     *
+     *   @OA\RequestBody(
+     *     required=true,
+     *     description="품목 배열과 디버그 옵션",
+     *
+     *     @OA\JsonContent(ref="#/components/schemas/QuoteBomBulkCalculateRequest")
+     *   ),
+     *
+     *   @OA\Response(
+     *     response=200,
+     *     description="산출 성공 (부분 실패 포함 가능)",
+     *
+     *     @OA\JsonContent(
+     *
+     *       @OA\Property(property="success", type="boolean", example=true),
+     *       @OA\Property(property="message", type="string", example="견적이 일괄 산출되었습니다."),
+     *       @OA\Property(property="data", ref="#/components/schemas/QuoteBomBulkCalculationResult")
+     *     )
+     *   ),
+     *
+     *   @OA\Response(response=400, description="유효성 검증 실패 (items 배열 누락 등)"),
+     *   @OA\Response(response=401, description="인증 필요")
+     * )
+     */
+    public function calculateBomBulk() {}
+
    /**
     * @OA\Post(
     *   path="/api/v1/quotes/{id}/pdf",
--- a/docs/changes/20260102_1300_quote_bom_bulk_calculation.md
+++ b/docs/changes/20260102_1300_quote_bom_bulk_calculation.md
@@ -0,0 +1,154 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-02 13:00
+**작업명:** Phase 1.2 입력 변수 처리 - React QuoteItem 매핑
+**계획 문서:** docs/plans/quote-calculation-api-plan.md
+
+## 변경 개요
+
+React 견적등록 화면에서 여러 품목의 자동산출을 일괄 요청할 수 있는 다건 BOM 기반 자동산출 API를 구현했습니다.
+React QuoteFormItem 인터페이스의 camelCase 필드명과 API의 약어 변수명 모두 지원합니다.
+
+## 수정된 파일
+
+| 파일 | 변경 유형 | 변경 내용 |
+|------|----------|----------|
+| `app/Http/Requests/Quote/QuoteBomBulkCalculateRequest.php` | 신규 | 다건 BOM 산출 요청 FormRequest |
+| `app/Services/Quote/QuoteCalculationService.php` | 수정 | calculateBomBulk() 메서드 추가 |
+| `app/Http/Controllers/Api/V1/QuoteController.php` | 수정 | calculateBomBulk() 액션 추가 |
+| `routes/api.php` | 수정 | `/calculate/bom/bulk` 라우트 추가 |
+| `app/Swagger/v1/QuoteApi.php` | 수정 | 스키마 3개 + 엔드포인트 추가 |
+
+## 상세 변경 사항
+
+### 1. QuoteBomBulkCalculateRequest.php (신규)
+
+**목적:** 다건 BOM 산출 요청 검증 및 필드 변환
+
+**주요 기능:**
+- items 배열 검증 (각 품목의 finished_goods_code 필수)
+- React camelCase → API 약어 자동 변환
+- getInputItems() 메서드로 표준화된 입력 반환
+
+**필드 매핑:**
+| React 필드 (camelCase) | API 변수 (약어) | 설명 |
+|----------------------|----------------|------|
+| openWidth | W0 | 개구부 폭 |
+| openHeight | H0 | 개구부 높이 |
+| quantity | QTY | 수량 |
+| productCategory | PC | 제품 카테고리 |
+| guideRailType | GT | 가이드레일 타입 |
+| motorPower | MP | 모터 출력 |
+| controller | CT | 제어반 |
+| wingSize | WS | 날개 크기 |
+| inspectionFee | INSP | 검사비 |
+
+### 2. QuoteCalculationService.php (수정)
+
+**추가된 메서드:**
+```php
+public function calculateBomBulk(array $inputItems, bool $debug = false): array
+```
+
+**기능:**
+- 여러 품목을 순회하며 calculateBom() 호출
+- 성공/실패 카운트 및 총합계 집계
+- 예외 처리로 개별 품목 실패가 전체에 영향 없음
+
+**반환 구조:**
+```php
+[
+    'success' => bool,     // 실패 건이 없으면 true
+    'summary' => [
+        'total_count' => int,
+        'success_count' => int,
+        'fail_count' => int,
+        'grand_total' => float
+    ],
+    'items' => [...]       // 품목별 결과
+]
+```
+
+### 3. QuoteController.php (수정)
+
+**추가된 액션:**
+```php
+public function calculateBomBulk(QuoteBomBulkCalculateRequest $request)
+```
+
+### 4. routes/api.php (수정)
+
+**추가된 라우트:**
+```php
+Route::post('quotes/calculate/bom/bulk', [QuoteController::class, 'calculateBomBulk'])
+    ->name('quotes.calculate-bom-bulk');
+```
+
+### 5. QuoteApi.php Swagger 문서 (수정)
+
+**추가된 스키마:**
+- `QuoteBomBulkCalculateRequest` - 요청 본문
+- `QuoteBomBulkItemInput` - 개별 품목 입력 (camelCase + 약어 모두 지원)
+- `QuoteBomBulkCalculationResult` - 응답 구조
+
+**추가된 엔드포인트:**
+- `POST /api/v1/quotes/calculate/bom/bulk`
+
+## 테스트 체크리스트
+
+- [x] PHP 문법 검사 통과
+- [x] Pint 코드 스타일 적용
+- [x] 라우트 등록 확인
+- [x] Swagger 문서 생성 확인
+- [ ] API 실제 호출 테스트 (React 연동 시)
+- [ ] 다건 처리 성능 테스트
+
+## API 사용 예시
+
+**요청:**
+```json
+POST /api/v1/quotes/calculate/bom/bulk
+{
+    "items": [
+        {
+            "finished_goods_code": "SC-1000",
+            "openWidth": 3000,
+            "openHeight": 2500,
+            "quantity": 2,
+            "productCategory": "스크린",
+            "guideRailType": "일반"
+        },
+        {
+            "finished_goods_code": "SC-2000",
+            "W0": 4000,
+            "H0": 3000,
+            "QTY": 1,
+            "GT": "고하중"
+        }
+    ],
+    "debug": false
+}
+```
+
+**응답:**
+```json
+{
+    "success": true,
+    "message": "견적 일괄 산출이 완료되었습니다.",
+    "data": {
+        "success": true,
+        "summary": {
+            "total_count": 2,
+            "success_count": 2,
+            "fail_count": 0,
+            "grand_total": 2500000
+        },
+        "items": [...]
+    }
+}
+```
+
+## 관련 문서
+
+- Phase 1.1: `20251230_2339_quote_calculation_mng_logic.md` (BOM 단건 산출)
+- 계획 문서: `docs/plans/quote-calculation-api-plan.md`
--- a/routes/api.php
+++ b/routes/api.php
@@ -539,6 +539,7 @@
        Route::prefix('receivables')->group(function () {
            Route::get('', [ReceivablesController::class, 'index'])->name('v1.receivables.index');
            Route::get('/summary', [ReceivablesController::class, 'summary'])->name('v1.receivables.summary');
+            Route::put('/overdue-status', [ReceivablesController::class, 'updateOverdueStatus'])->name('v1.receivables.update-overdue-status');
        });

        // Daily Report API (일일 보고서)
@@ -930,6 +931,7 @@
            Route::get('/calculation/schema', [QuoteController::class, 'calculationSchema'])->name('v1.quotes.calculation-schema'); // 입력 스키마
            Route::post('/calculate', [QuoteController::class, 'calculate'])->name('v1.quotes.calculate');                    // 자동산출 실행
            Route::post('/calculate/bom', [QuoteController::class, 'calculateBom'])->name('v1.quotes.calculate-bom');         // BOM 기반 자동산출
+            Route::post('/calculate/bom/bulk', [QuoteController::class, 'calculateBomBulk'])->name('v1.quotes.calculate-bom-bulk'); // 다건 BOM 자동산출

            // 문서 관리
            Route::post('/{id}/pdf', [QuoteController::class, 'generatePdf'])->whereNumber('id')->name('v1.quotes.pdf');                  // PDF 생성