sam-api/docs/changes/20260102_1300_quote_bom_bulk_calculation.md

# 변경 내용 요약

**날짜:** 2026-01-02 13:00
**작업명:** Phase 1.2 입력 변수 처리 - React QuoteItem 매핑
**계획 문서:** docs/dev/dev_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/dev/dev_plans/quote-calculation-api-plan.md`