sam-api/claudedocs/[PLAN-2025-12-04] quote-api-development-plan.md

# 견적관리 API 개발 계획서

> **작성일**: 2025-12-04
> **요청서**: `docs/front/[API-2025-12-04] quote-api-request.md`
> **상태**: ✅ Phase 1 완료 → Phase 2 진행 중

---

## 🔧 작업 진행 현황 (2025-12-04)

### ✅ Phase 1 완료 항목

#### 1. 마이그레이션 생성 및 실행 완료
- **파일**: `database/migrations/2025_12_04_164542_create_quotes_table.php`
- **생성된 테이블**: `quotes`, `quote_items`, `quote_revisions`
- **실행 상태**: ✅ 마이그레이션 완료

#### 2. Model 생성 완료
```
app/Models/Quote/
├── Quote.php           ✅ 생성 완료
├── QuoteItem.php       ✅ 생성 완료
└── QuoteRevision.php   ✅ 생성 완료
```

**적용된 패턴:**
- `BelongsToTenant` 트레이트 적용
- `SoftDeletes` 적용 (Quote)
- 상태 상수 정의 (STATUS_DRAFT, STATUS_FINALIZED 등)
- 스코프 메서드 (draft, finalized, search, dateRange 등)
- 상태 검증 메서드 (isEditable, isDeletable, isFinalizable, isConvertible)

### 🆕 변경 요청 분석 (2025-12-04)

요청서에서 **문서 발송 API (Section 3.5)**가 신규 추가됨:

| Method | Endpoint | 설명 | 비고 |
|--------|----------|------|------|
| `POST` | `/api/v1/quotes/{id}/send/email` | 이메일 발송 | 첨부파일 포함 |
| `POST` | `/api/v1/quotes/{id}/send/fax` | 팩스 발송 | 팩스 서비스 연동 |
| `POST` | `/api/v1/quotes/{id}/send/kakao` | 카카오톡 발송 | 알림톡/친구톡 |

**영향 범위:**
- Phase 2: `QuoteDocumentService` 추가 필요
- Phase 3: 문서 발송 관련 Controller 메서드 + FormRequest 추가
- Phase 4: Swagger 문서에 발송 API 추가

**개발 우선순위 조정:**
- P1: 견적 CRUD, 자동 산출, 견적번호 생성 (기존 유지)
- P2: 상태 관리, 수정 이력 (기존 유지)
- P3: 문서 출력 + **문서 발송 API** (신규 추가)

### ⏭️ 다음 단계
- Phase 2: Service Layer 구현 (QuoteService, QuoteCalculationService, QuoteNumberService)

---

## 1. 요구사항 분석 요약

### 1.1 핵심 엔티티
| 엔티티 | 설명 | 비고 |
|--------|------|------|
| Quote | 견적 마스터 | 메인 테이블 |
| QuoteItem | 견적 품목 | BOM/수식 계산 결과 저장 |
| QuoteRevision | 수정 이력 | 버전 관리 |

### 1.2 기능 우선순위
| 우선순위 | 기능 | 설명 |
|----------|------|------|
| **P1** | 견적 CRUD | 기본 목록/등록/수정/삭제 |
| **P1** | 자동 산출 | 수식 계산 엔진 (핵심) |
| **P1** | 견적번호 생성 | 자동 채번 |
| **P2** | 상태 관리 | 확정/수주전환 |
| **P2** | 수정 이력 | 버전 관리 |
| **P3** | 문서 출력 | PDF 생성 |

### 1.3 기존 인프라 활용
- `quote_formulas` 테이블들 (수식 계산용) - **이미 존재**
- `FormulaEvaluatorService` (mng에서 사용 중) - **API로 이식 필요**
- `EstimateService` 패턴 참조 - **유사 구조**

---

## 2. 데이터베이스 설계

### 2.1 신규 테이블: quotes (견적 마스터)

```sql
CREATE TABLE quotes (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL COMMENT '테넌트 ID',

    -- 기본 정보
    quote_number VARCHAR(50) NOT NULL COMMENT '견적번호 (예: KD-SC-251204-01)',
    registration_date DATE NOT NULL COMMENT '등록일',
    receipt_date DATE NULL COMMENT '접수일',
    author VARCHAR(100) NULL COMMENT '작성자',

    -- 발주처 정보
    client_id BIGINT UNSIGNED NULL COMMENT '거래처 ID (FK)',
    client_name VARCHAR(100) NULL COMMENT '거래처명 (직접입력 대응)',
    manager VARCHAR(100) NULL COMMENT '담당자',
    contact VARCHAR(50) NULL COMMENT '연락처',

    -- 현장 정보
    site_id BIGINT UNSIGNED NULL COMMENT '현장 ID',
    site_name VARCHAR(200) NULL COMMENT '현장명',
    site_code VARCHAR(50) NULL COMMENT '현장코드',

    -- 제품 정보
    product_category ENUM('SCREEN', 'STEEL') NOT NULL COMMENT '제품 카테고리',
    product_id BIGINT UNSIGNED NULL COMMENT '선택된 제품 ID',
    product_code VARCHAR(50) NULL COMMENT '제품코드',
    product_name VARCHAR(200) NULL COMMENT '제품명',

    -- 규격 정보
    open_size_width INT UNSIGNED NULL COMMENT '오픈사이즈 폭 (mm)',
    open_size_height INT UNSIGNED NULL COMMENT '오픈사이즈 높이 (mm)',
    quantity INT UNSIGNED NOT NULL DEFAULT 1 COMMENT '수량',
    unit_symbol VARCHAR(10) NULL COMMENT '부호',
    floors VARCHAR(20) NULL COMMENT '층수',

    -- 금액 정보
    material_cost DECIMAL(15,2) NOT NULL DEFAULT 0 COMMENT '재료비 합계',
    labor_cost DECIMAL(15,2) NOT NULL DEFAULT 0 COMMENT '노무비',
    install_cost DECIMAL(15,2) NOT NULL DEFAULT 0 COMMENT '설치비',
    subtotal DECIMAL(15,2) NOT NULL DEFAULT 0 COMMENT '소계',
    discount_rate DECIMAL(5,2) NOT NULL DEFAULT 0 COMMENT '할인율 (%)',
    discount_amount DECIMAL(15,2) NOT NULL DEFAULT 0 COMMENT '할인금액',
    total_amount DECIMAL(15,2) NOT NULL DEFAULT 0 COMMENT '최종 금액',

    -- 상태 관리
    status ENUM('draft', 'sent', 'approved', 'rejected', 'finalized', 'converted') NOT NULL DEFAULT 'draft' COMMENT '상태',
    current_revision INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '현재 수정 차수',
    is_final TINYINT(1) NOT NULL DEFAULT 0 COMMENT '최종확정 여부',
    finalized_at DATETIME NULL COMMENT '확정일시',
    finalized_by BIGINT UNSIGNED NULL COMMENT '확정자 ID',

    -- 기타 정보
    completion_date DATE NULL COMMENT '납기일',
    remarks TEXT NULL COMMENT '비고',
    memo TEXT NULL COMMENT '메모',
    notes TEXT NULL COMMENT '특이사항',

    -- 자동산출 입력값 저장
    calculation_inputs JSON NULL COMMENT '자동산출에 사용된 입력값',

    -- 감사
    created_by BIGINT UNSIGNED NULL COMMENT '생성자',
    updated_by BIGINT UNSIGNED NULL COMMENT '수정자',
    deleted_by BIGINT UNSIGNED NULL COMMENT '삭제자',
    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,
    deleted_at TIMESTAMP NULL,

    -- 인덱스
    INDEX idx_tenant_id (tenant_id),
    INDEX idx_quote_number (quote_number),
    INDEX idx_status (status),
    INDEX idx_client_id (client_id),
    INDEX idx_product_category (product_category),
    INDEX idx_registration_date (registration_date),
    UNIQUE INDEX uq_tenant_quote_number (tenant_id, quote_number, deleted_at),

    FOREIGN KEY (tenant_id) REFERENCES tenants(id),
    FOREIGN KEY (client_id) REFERENCES clients(id) ON DELETE SET NULL
);
```

### 2.2 신규 테이블: quote_items (견적 품목)

```sql
CREATE TABLE quote_items (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    quote_id BIGINT UNSIGNED NOT NULL COMMENT '견적 ID',
    tenant_id BIGINT UNSIGNED NOT NULL COMMENT '테넌트 ID',

    -- 품목 정보
    item_id BIGINT UNSIGNED NULL COMMENT '품목마스터 ID',
    item_code VARCHAR(50) NOT NULL COMMENT '품목코드',
    item_name VARCHAR(200) NOT NULL COMMENT '품명',
    specification VARCHAR(100) NULL COMMENT '규격',
    unit VARCHAR(20) NOT NULL COMMENT '단위',

    -- 수량/금액
    base_quantity DECIMAL(15,4) NOT NULL DEFAULT 1 COMMENT '기본수량',
    calculated_quantity DECIMAL(15,4) NOT NULL DEFAULT 1 COMMENT '계산된 수량',
    unit_price DECIMAL(15,2) NOT NULL DEFAULT 0 COMMENT '단가',
    total_price DECIMAL(15,2) NOT NULL DEFAULT 0 COMMENT '금액 (수량 × 단가)',

    -- 수식 정보
    formula VARCHAR(500) NULL COMMENT '수식',
    formula_result VARCHAR(200) NULL COMMENT '수식 계산 결과 표시',
    formula_source VARCHAR(100) NULL COMMENT '수식 출처',
    formula_category VARCHAR(50) NULL COMMENT '수식 카테고리',
    data_source VARCHAR(200) NULL COMMENT '데이터 출처',

    -- 기타
    delivery_date DATE NULL COMMENT '품목별 납기일',
    note TEXT NULL COMMENT '비고',
    sort_order INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '정렬순서',

    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,

    -- 인덱스
    INDEX idx_quote_id (quote_id),
    INDEX idx_tenant_id (tenant_id),
    INDEX idx_item_code (item_code),
    INDEX idx_sort_order (sort_order),

    FOREIGN KEY (quote_id) REFERENCES quotes(id) ON DELETE CASCADE,
    FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);
```

### 2.3 신규 테이블: quote_revisions (수정 이력)

```sql
CREATE TABLE quote_revisions (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    quote_id BIGINT UNSIGNED NOT NULL COMMENT '견적 ID',
    tenant_id BIGINT UNSIGNED NOT NULL COMMENT '테넌트 ID',

    revision_number INT UNSIGNED NOT NULL COMMENT '수정 차수',
    revision_date DATE NOT NULL COMMENT '수정일',
    revision_by BIGINT UNSIGNED NOT NULL COMMENT '수정자 ID',
    revision_by_name VARCHAR(100) NULL COMMENT '수정자 이름',
    revision_reason TEXT NULL COMMENT '수정 사유',

    -- 이전 버전 데이터 (JSON 스냅샷)
    previous_data JSON NOT NULL COMMENT '수정 전 견적 전체 데이터',

    created_at TIMESTAMP NULL,

    -- 인덱스
    INDEX idx_quote_id (quote_id),
    INDEX idx_tenant_id (tenant_id),
    INDEX idx_revision_number (revision_number),

    FOREIGN KEY (quote_id) REFERENCES quotes(id) ON DELETE CASCADE,
    FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);
```

### 2.4 기존 테이블 활용
- `quote_formula_categories` - 수식 카테고리
- `quote_formulas` - 수식 정의
- `quote_formula_ranges` - 범위별 값
- `quote_formula_mappings` - 매핑 값
- `quote_formula_items` - 수식 품목 출력
- `clients` - 발주처
- `item_masters` - 품목 마스터 (단가 연동)

---

## 3. API 엔드포인트 설계

### 3.1 기본 CRUD

| Method | Endpoint | 설명 |
|--------|----------|------|
| `GET` | `/api/v1/quotes` | 목록 조회 (페이징, 필터, 검색) |
| `GET` | `/api/v1/quotes/{id}` | 단건 조회 (items, revisions 포함) |
| `POST` | `/api/v1/quotes` | 생성 (품목 배열 포함) |
| `PUT` | `/api/v1/quotes/{id}` | 수정 (수정이력 자동 생성) |
| `DELETE` | `/api/v1/quotes/{id}` | 삭제 (Soft Delete) |
| `DELETE` | `/api/v1/quotes` | 일괄 삭제 (`ids[]` 파라미터) |

### 3.2 상태 관리

| Method | Endpoint | 설명 |
|--------|----------|------|
| `PATCH` | `/api/v1/quotes/{id}/finalize` | 최종확정 |
| `PATCH` | `/api/v1/quotes/{id}/convert-to-order` | 수주전환 |
| `PATCH` | `/api/v1/quotes/{id}/cancel-finalize` | 확정취소 |

### 3.3 자동 산출

| Method | Endpoint | 설명 |
|--------|----------|------|
| `POST` | `/api/v1/quotes/calculate` | 자동 산출 (수식 엔진) |
| `POST` | `/api/v1/quotes/{id}/recalculate` | 기존 견적 재계산 |
| `GET` | `/api/v1/quotes/generate-number` | 견적번호 생성 |

### 3.4 문서 출력 (P3 - 후순위)

| Method | Endpoint | 설명 |
|--------|----------|------|
| `GET` | `/api/v1/quotes/{id}/document/quote` | 견적서 PDF |
| `GET` | `/api/v1/quotes/{id}/document/calculation` | 산출내역서 PDF |
| `GET` | `/api/v1/quotes/{id}/document/purchase-order` | 발주서 PDF |

### 3.5 문서 발송 (P3 - 신규 추가)

| Method | Endpoint | 설명 | 비고 |
|--------|----------|------|------|
| `POST` | `/api/v1/quotes/{id}/send/email` | 이메일 발송 | 첨부파일 포함 |
| `POST` | `/api/v1/quotes/{id}/send/fax` | 팩스 발송 | 팩스 서비스 연동 |
| `POST` | `/api/v1/quotes/{id}/send/kakao` | 카카오톡 발송 | 알림톡/친구톡 |

---

## 4. 개발 Phase 계획

### Phase 1: 기반 구축 (DB + Model)

**작업 내용:**
1. 마이그레이션 생성 (3개 테이블)
2. Model 생성 (Quote, QuoteItem, QuoteRevision)
3. Trait/Scope 적용 (BelongsToTenant, SoftDeletes, 감사 컬럼)

**파일 목록:**
```
database/migrations/
├── 2025_12_XX_XXXXXX_create_quotes_table.php
├── 2025_12_XX_XXXXXX_create_quote_items_table.php
└── 2025_12_XX_XXXXXX_create_quote_revisions_table.php

app/Models/Quote/
├── Quote.php
├── QuoteItem.php
└── QuoteRevision.php
```

### Phase 2: 핵심 서비스 (Service Layer)

**작업 내용:**
1. QuoteService - CRUD + 상태관리
2. QuoteCalculationService - 자동산출 (FormulaEvaluator 연동)
3. QuoteNumberService - 번호채번
4. FormulaEvaluatorService 이식 (mng → api)
5. QuoteDocumentService - 문서 생성 및 발송 (신규 추가)

**파일 목록:**
```
app/Services/Quote/
├── QuoteService.php
├── QuoteCalculationService.php
├── QuoteNumberService.php
├── QuoteDocumentService.php      (신규 - 문서 생성/발송)
└── FormulaEvaluatorService.php  (mng에서 이식)
```

**의존성:**
- PricingService (단가 조회)
- ClientService (발주처 연동)
- MailService (이메일 발송)
- NotificationService (카카오톡/팩스 발송)

### Phase 3: API 구현 (Controller + Routes)

**작업 내용:**
1. QuoteController 구현
2. FormRequest 생성 (검증 규칙)
3. 라우트 추가
4. 문서 발송 엔드포인트 추가 (신규)

**파일 목록:**
```
app/Http/Controllers/Api/V1/
└── QuoteController.php

app/Http/Requests/Quote/
├── QuoteIndexRequest.php
├── QuoteStoreRequest.php
├── QuoteUpdateRequest.php
├── QuoteCalculateRequest.php
├── QuoteFinalizeRequest.php
├── QuoteSendEmailRequest.php    (신규)
├── QuoteSendFaxRequest.php      (신규)
└── QuoteSendKakaoRequest.php    (신규)

routes/
└── api_v1.php  (라우트 추가)
```

### Phase 4: 문서화 (Swagger + i18n)

**작업 내용:**
1. Swagger 문서 작성
2. i18n 메시지 키 추가

**파일 목록:**
```
app/Swagger/v1/
└── QuoteApi.php

lang/ko/
├── message.php  (quote 키 추가)
└── error.php    (quote 에러 키 추가)
```

---

## 5. 자동 산출 로직 상세

### 5.1 입력값 → 수식 변수 매핑

| 입력 필드 | 수식 변수 | 설명 |
|-----------|-----------|------|
| `open_size_width` | `W0` | 오픈사이즈 폭 (mm) |
| `open_size_height` | `H0` | 오픈사이즈 높이 (mm) |
| `quantity` | `Q` | 수량 |
| `floors` | `FLOORS` | 층수 |
| `options.guide_rail_install_type` | `GUIDE_TYPE` | 가이드레일 설치 유형 |
| `options.motor_power` | `MOTOR_POWER` | 모터 용량 |
| `options.controller` | `CONTROLLER_TYPE` | 제어기 유형 |
| `options.edge_wing_size` | `EDGE_SIZE` | 마구리 날개 사이즈 |
| `options.inspection_fee` | `INSP_FEE` | 검사비 |

### 5.2 처리 흐름

```
1. 입력값 수집
   ↓
2. 수식 변수 초기화 (input 타입)
   ↓
3. 계산 수식 실행 (calculation 타입)
   - 의존성 순서대로 실행
   - FormulaEvaluatorService 활용
   ↓
4. 범위 판단 (range 타입)
   - quote_formula_ranges 조회
   ↓
5. 매핑 판단 (mapping 타입)
   - quote_formula_mappings 조회
   ↓
6. 품목 출력 생성 (quote_formula_items)
   - 수량 계산식 적용
   - 단가 조회 (품목마스터 또는 고정값)
   ↓
7. 결과 반환
   - items 배열
   - summary (재료비, 노무비, 설치비 등)
   - calculation_info (사용된 변수들)
```

### 5.3 FormulaEvaluatorService 이식 범위

mng의 `QuoteFormulaService`에서 다음 메서드 이식:
- `evaluateFormula()` - 수식 평가
- `evaluateAllFormulas()` - 전체 수식 순차 평가
- `resolveRangeValue()` - 범위 값 해석
- `resolveMappingValue()` - 매핑 값 해석

---

## 6. 예상 산출물 요약

| 구분 | 수량 | 내용 |
|------|------|------|
| 마이그레이션 | 3개 | quotes, quote_items, quote_revisions |
| Model | 3개 | Quote, QuoteItem, QuoteRevision |
| Service | 5개 | QuoteService, QuoteCalculationService, QuoteNumberService, FormulaEvaluatorService, **QuoteDocumentService** |
| Controller | 1개 | QuoteController |
| FormRequest | 8개 | Index, Store, Update, Calculate, Finalize, **SendEmail, SendFax, SendKakao** |
| Swagger | 1개 | QuoteApi.php |
| i18n | 2개 | message.php, error.php (키 추가) |

---

## 7. 질문사항 답변

### Q1. 현장(Site) 테이블
**답변:** `quotes` 테이블에 `site_*` 컬럼으로 직접 저장 (별도 테이블 불필요)
- `site_id`, `site_name`, `site_code` 컬럼 포함
- 추후 별도 테이블 필요 시 마이그레이션으로 분리 가능

### Q2. 수식 계산 BOM 템플릿 테이블 구조
**답변:** 기존 `quote_formulas` 테이블 구조 활용
- `quote_formula_categories` - 수식 카테고리
- `quote_formulas` - 수식 정의 (input/calculation/range/mapping)
- `quote_formula_ranges` - 범위별 값
- `quote_formula_mappings` - 매핑 값
- `quote_formula_items` - 품목 출력 정의

### Q3. 문서 출력 PDF 라이브러리
**답변:** P3 (후순위) 작업으로 진행
- 권장: **TCPDF** (한글 지원, Laravel 연동 용이)
- 대안: Dompdf (HTML → PDF 변환)

### Q4. 알림 (이메일/카카오톡)
**답변:** ✅ 요청서 Section 3.5에 신규 추가됨
- 이메일 발송: `POST /api/v1/quotes/{id}/send/email`
- 팩스 발송: `POST /api/v1/quotes/{id}/send/fax`
- 카카오톡 발송: `POST /api/v1/quotes/{id}/send/kakao`
- P3 우선순위로 문서 출력과 함께 개발 예정

---

## 8. 승인 요청

**개발 범위:**
- Phase 1~4 전체 구현 (P3 문서 출력 제외)
- 예상 작업량: Phase별 순차 진행

**진행 조건:**
- 이 계획서 승인 후 Phase 1부터 순차 진행
- 각 Phase 완료 시 검증 후 다음 Phase 진행
- 커밋은 각 Phase 완료 시 승인 후 진행

---

**작성자:** Claude (AI Assistant)
**검토자:** (승인 대기)