sam-docs/rules/pricing-policy.md

# SAM 단가 정책 (Pricing Policy)

> **작성일**: 2025-12-08
> **최종 갱신**: 2026-03-19
> **상태**: 설계 확정 + 개선방향 기획 (Depth 버전관리)

---

## 1. 개요

### 1.1 목적

SAM 시스템 내 모든 단가의 **유형 정의**, **계산 공식**, **흐름 추적**, **버전 관리**를 명확히 한다.

### 1.2 핵심 원칙

| 원칙 | 설명 |
|------|------|
| **Depth 기반 흐름** | 매입단가 → 표준원가 → 판매단가 → 견적단가 → 수주단가 → 매출단가 |
| **실제원가 우선** | 수입검사 입고단가 > 표준원가 |
| **시점 기반 유효성** | `effective_from` ~ `effective_to` 기간 내 유효 |
| **리비전 추적** | 모든 변경 사항 이력 보관 (`price_revisions`) |
| **확정 후 불변** | `finalized` 상태는 수정/삭제 불가 |
| **단가 복제 원칙** | 하위 단계(견적→수주→매출)로 복제된 단가는 원본과 독립 |

### 1.3 단가 유형 정의 (6 Depth)

```
Depth 0  매입단가     prices.purchase_price        공급업체로부터의 구매가
Depth 1  표준원가     (매입단가 + 가공비) × LOSS    제조 기준 원가
Depth 2  판매단가     prices.sales_price            표준원가 + 마진, 반올림 적용
Depth 3  견적단가     quote_items.unit_price         BOM 산출 또는 수동 입력
Depth 4  수주단가     order_items.unit_price         견적에서 복제 (확정가)
Depth 5  매출단가     sales.supply_amount            수주에서 복제 (최종가)
```

---

## 2. 단가 흐름도

### 2.1 전체 흐름

```
┌─────────────────────────────────────────────────────────────┐
│  Depth 0: 매입단가                                          │
│  prices.purchase_price + prices.processing_cost             │
│  소스: 공급업체 견적, 수입검사 입고단가                        │
└──────────────────────┬──────────────────────────────────────┘
                       ↓ × (1 + LOSS율/100)
┌──────────────────────┴──────────────────────────────────────┐
│  Depth 1: 표준원가                                          │
│  = (매입단가 + 가공비) × (1 + LOSS율/100)                   │
└──────────────────────┬──────────────────────────────────────┘
                       ↓ × (1 + 마진율/100) + 반올림
┌──────────────────────┴──────────────────────────────────────┐
│  Depth 2: 판매단가                                          │
│  prices.sales_price (고객그룹별 차등가 가능)                  │
└──────────────────────┬──────────────────────────────────────┘
                       ↓ BOM 산출 or 수동 입력
┌──────────────────────┴──────────────────────────────────────┐
│  Depth 3: 견적단가                                          │
│  quote_items.unit_price (BOM 부품별 판매단가 합산 = 완제품가) │
│  quotes.total_amount = 재료비 + 노무비 + 시공비 - 할인       │
└──────────────────────┬──────────────────────────────────────┘
                       ↓ convertToOrder() 복제
┌──────────────────────┴──────────────────────────────────────┐
│  Depth 4: 수주단가                                          │
│  order_items.unit_price (견적단가 복제)                       │
│  + supply_amount, tax_amount, total_amount 재계산            │
└──────────────────────┬──────────────────────────────────────┘
                       ↓ createFromOrder/Shipment 복제
┌──────────────────────┴──────────────────────────────────────┐
│  Depth 5: 매출단가                                          │
│  sales.supply_amount, tax_amount, total_amount (수주 복제)   │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 단가 저장 위치

| Depth | 테이블 | 단가 컬럼 | 금액 컬럼 |
|:-----:|--------|----------|----------|
| 0 | `prices` | `purchase_price`, `processing_cost` | — |
| 1 | (계산값) | — | `(purchase_price + processing_cost) × (1 + loss_rate)` |
| 2 | `prices` | `sales_price` | — |
| 3 | `quote_items` | `unit_price` | `total_price` |
| 3 | `quotes` | — | `material_cost`, `labor_cost`, `install_cost`, `total_amount` |
| 4 | `order_items` | `unit_price` | `supply_amount`, `tax_amount`, `total_amount` |
| 4 | `orders` | — | `supply_amount`, `tax_amount`, `total_amount` |
| 5 | `sales` | — | `supply_amount`, `tax_amount`, `total_amount` |

---

## 3. 단가 계산 공식

### 3.1 표준원가 (Depth 1)

```
표준원가 = (매입단가 + 가공비) × (1 + LOSS율/100)

예시: (10,000 + 2,000) × 1.05 = 12,600원
```

### 3.2 판매단가 (Depth 2)

```
판매단가 = 반올림(표준원가 × (1 + 마진율/100), 반올림단위, 반올림규칙)

예시: round(12,600 × 1.25 / 100) × 100 = 15,800원
```

| 반올림규칙 | 설명 | 15,750 (단위 100) |
|-----------|------|------------------|
| `round` | 반올림 | 15,800 |
| `ceil` | 올림 | 15,800 |
| `floor` | 버림 | 15,700 |

### 3.3 원가 조회 우선순위

| 순위 | 소스 | 조건 |
|:----:|------|------|
| 1 | `material_receipts.purchase_price_excl_vat` | 자재만, 최근 입고 기준 |
| 2 | `prices.purchase_price` | 해당 일자 유효 단가 |
| 3 | NULL | 단가 미등록 → 경고 반환 |

### 3.4 견적단가 (Depth 3) — BOM 산출

```
견적 품목 금액 = 계산수량 × 단가
견적 소계     = 재료비 + 노무비 + 시공비
견적 총액     = 소계 - 할인금액
```

BOM 자동산출 시 `EstimatePriceService`가 items + item_details + prices 조인으로 판매단가 조회.

### 3.5 수주단가 (Depth 4)

```
공급가액 = 수량 × 단가 - 할인금액
세액     = 공급가액 × 10%
총액     = 공급가액 + 세액
```

### 3.6 매출단가 (Depth 5)

수주의 `supply_amount`, `tax_amount`, `total_amount`를 그대로 복제.

---

## 4. 고객그룹 차등가

### 4.1 구조

`client_groups` 테이블:

| 필드 | 설명 |
|------|------|
| `group_code` | 그룹 코드 |
| `group_name` | 그룹명 |
| `price_rate` | 가격 배율 (1.0=기본, 0.9=10%할인, 1.1=10%인상) |

### 4.2 조회 우선순위

```
1순위: prices WHERE client_group_id = [거래처의 그룹ID]  → 그룹 전용 단가
2순위: prices WHERE client_group_id IS NULL              → 기본 단가
```

`Price::getCurrentPrice($tenantId, $itemTypeCode, $itemId, $clientGroupId)` 메서드가 이 로직을 처리한다.

---

## 5. 상태 관리

### 5.1 상태 전이

```
draft ──→ active ──→ finalized
 (초안)    (활성)      (확정, 불변)
             │
             └──→ inactive (비활성)
```

### 5.2 상태별 권한

| 상태 | 조회 | 수정 | 삭제 | 확정 |
|------|:----:|:----:|:----:|:----:|
| `draft` | ✅ | ✅ | ✅ | ✅ |
| `active` | ✅ | ✅ | ✅ | ✅ |
| `inactive` | ✅ | ✅ | ✅ | ❌ |
| `finalized` | ✅ | ❌ | ❌ | ❌ |

### 5.3 확정 규칙

- `sales_price` 또는 `purchase_price` 중 하나 이상 존재해야 확정 가능
- 확정 시: `is_final = true`, `status = 'finalized'`, `finalized_at/by` 기록
- 확정 후: 수정 필요 시 **새 단가 레코드 생성** (기존 단가의 `effective_to` 자동 설정)

---

## 6. 리비전 관리

### 6.1 리비전 생성 시점

| 이벤트 | 리비전 | 설명 |
|--------|:------:|------|
| 최초 등록 | ✅ | `revision_number = 1`, `before_snapshot = NULL` |
| 수정 | ✅ | `revision_number++`, 변경 전/후 기록 |
| 삭제 | ✅ | soft delete, 삭제 전 스냅샷 |
| 확정 | ✅ | 확정 시점 스냅샷 |

### 6.2 기간 중복 자동 처리

```
기존: 2025-01-01 ~ NULL (무기한)
신규: 2025-06-01 ~ NULL

→ 기존의 effective_to를 2025-05-31로 자동 설정
→ 신규 단가 등록
```

---

## 7. 비즈니스 규칙

| 규칙 | 설명 |
|------|------|
| **R1** | `effective_from`은 필수 |
| **R2** | `effective_from` ≤ `effective_to` |
| **R3** | 동일 품목+고객그룹+적용시작일 중복 불가 |
| **R4** | 확정된 단가는 수정/삭제 불가 |
| **R5** | 마진율: 0% 이상 (상한 없음) |
| **R6** | LOSS율: 0~100% |
| **R7** | 반올림단위: 1, 10, 100, 1000 중 택1 |
| **R8** | Soft Delete 적용 (삭제 후 리비전에서 조회 가능) |

---

## 8. API 엔드포인트

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/v1/pricing` | 단가 목록 |
| GET | `/api/v1/pricing/{id}` | 단가 상세 (리비전 10개 포함) |
| POST | `/api/v1/pricing` | 단가 등록 |
| PUT | `/api/v1/pricing/{id}` | 단가 수정 (`change_reason` 선택) |
| DELETE | `/api/v1/pricing/{id}` | 단가 삭제 |
| POST | `/api/v1/pricing/{id}/finalize` | 단가 확정 |
| POST | `/api/v1/pricing/by-items` | 품목별 단가 현황 |
| GET | `/api/v1/pricing/{id}/revisions` | 변경 이력 |
| POST | `/api/v1/pricing/cost` | 원가 조회 |
| GET | `/api/v1/pricing/stats` | 단가 통계 |
| DELETE | `/api/v1/pricing/bulk` | 일괄 삭제 |

---

## 9. 핵심 코드 위치

| 구분 | 파일 | 역할 |
|------|------|------|
| 모델 | `api/app/Models/Products/Price.php` | `getCurrentPrice()`, `calculateSalesPrice()`, `getSalesPriceByItemCode()` |
| 모델 | `api/app/Models/Products/PriceRevision.php` | 변경 이력 (Immutable) |
| 서비스 | `api/app/Services/PricingService.php` | 단가 CRUD, 리비전, 확정, 원가 조회 |
| 서비스 | `api/app/Services/Quote/EstimatePriceService.php` | BOM 자동산출 시 부품 단가 조회 |
| 서비스 | `api/app/Services/Quote/QuoteService.php` | 견적→수주 전환 (`convertToOrder`) |
| 모델 | `api/app/Models/Orders/OrderItem.php` | `createFromQuoteItem()`, 금액 재계산 |
| 모델 | `api/app/Models/Tenants/Sale.php` | `createFromOrder()`, `createFromShipment()` |

---

## 10. 개선방향: Depth 기반 단가 버전관리

> **상태**: 기획 단계
> **배경**: 현재 원자재 가격 인상 시 하위 Depth(판매단가, 견적단가)에 대한 영향 분석이 수동으로 이루어지고 있다. Depth 개념을 도입하여 단가 변경의 **상향 전파(Cascade)** 와 **영향 분석(Impact Analysis)** 을 체계화한다.

### 10.1 현재 한계

| 문제 | 설명 |
|------|------|
| **단절된 추적** | 매입단가 변경 시 어떤 판매단가/견적에 영향이 있는지 추적 불가 |
| **수동 갱신** | 원자재 인상 → 판매단가 수동 재계산 → 견적 재작성 필요 |
| **스냅샷 부재** | 견적/수주 시점의 Depth 0~2 단가를 역추적할 수 없음 |
| **일괄 변경 불가** | 특정 공급업체 자재 10% 인상 시 관련 판매단가 일괄 갱신 불가 |

### 10.2 개선 방향

#### Phase 1: 단가 연쇄 관계 추적

`prices` 테이블에 Depth 관계를 기록하여, 하위 Depth 단가가 어떤 상위 Depth 단가에서 파생되었는지 추적한다.

```
신규 필드 (prices 테이블):
  price_depth       TINYINT     — 0(매입), 2(판매) 등
  parent_price_id   BIGINT      — 이 단가의 원천 단가 ID (NULL=최상위)
  price_version     VARCHAR(20) — 단가 버전 (예: 'v2026-Q1')
```

**효과**: 매입단가(Depth 0) 변경 시 → 해당 품목의 판매단가(Depth 2) 목록을 즉시 조회 가능.

#### Phase 2: 변경 영향 분석 API

매입단가 변경 전 영향 범위를 분석하는 API를 제공한다.

```
POST /api/v1/pricing/impact-analysis
Body: { "price_id": 123, "new_purchase_price": 12000 }

Response:
{
  "affected_sales_prices": [
    { "id": 456, "item_name": "가이드레일", "current": 15800, "projected": 17400, "diff": "+10.1%" }
  ],
  "affected_quotes": [
    { "id": 789, "quote_number": "KD-SC-260301-01", "status": "draft", "impact": "+52,000원" }
  ],
  "affected_orders": [
    { "id": 101, "order_number": "ORD-260215-001", "status": "confirmed", "impact": "변경 불가 (확정)" }
  ]
}
```

#### Phase 3: 단가 버전 그룹 관리

분기/반기 단위로 단가 버전을 묶어 관리한다.

```
신규 테이블: price_versions
  id, tenant_id
  version_code      VARCHAR(20)   — 'v2026-Q1', 'v2026-H1'
  version_name      VARCHAR(100)  — '2026년 1분기 단가'
  base_version_id   BIGINT        — 이전 버전 ID (NULL=최초)
  effective_from    DATE          — 적용 시작일
  status            ENUM          — draft/active/archived
  change_summary    JSON          — { total_items: 150, avg_increase: 3.2% }
  created_by, created_at
```

**워크플로우**:

```
1. 신규 버전 생성 (draft)
   → 이전 버전의 모든 단가를 복사
2. 변경 대상 품목의 매입단가 수정
   → 판매단가 자동 재계산 (Cascade)
3. 영향 분석 리포트 생성
   → 변경 전후 비교, 마진 변화 시각화
4. 승인 → 버전 활성화 (active)
   → effective_from 일자부터 신규 단가 적용
5. 이전 버전 자동 종료 (archived)
```

#### Phase 4: 견적/수주 단가 스냅샷

견적/수주 생성 시점의 Depth 0~2 단가를 `calculation_inputs` JSON에 보존한다.

```json
{
  "price_snapshot": {
    "version": "v2026-Q1",
    "captured_at": "2026-03-15",
    "items": [
      {
        "item_id": 100,
        "item_name": "가이드레일",
        "depth_0": { "purchase_price": 10000, "processing_cost": 2000, "loss_rate": 5 },
        "depth_2": { "sales_price": 15800, "margin_rate": 25 },
        "depth_3": { "unit_price": 15800, "quantity": 2.5, "total": 39500 }
      }
    ]
  }
}
```

**효과**: 수주 완료 후 원가 변동이 발생해도, 해당 수주 시점의 원가 구조를 완전히 역추적 가능.

### 10.3 기대 효과

| 항목 | 현재 | 개선 후 |
|------|------|--------|
| 원자재 인상 반영 | 수동 (1~2일) | 자동 Cascade (즉시) |
| 영향 범위 파악 | 불가능 | Impact Analysis API |
| 단가 이력 비교 | 개별 리비전만 | 버전 간 일괄 비교 |
| 견적 원가 역추적 | 불가능 | 스냅샷 보존 |
| 분기 단가 갱신 | 품목별 수동 | 버전 복사 + 일괄 변경 |

### 10.4 구현 우선순위

| Phase | 내용 | 난이도 | 우선순위 |
|:-----:|------|:------:|:-------:|
| 1 | 단가 연쇄 관계 (parent_price_id) | 낮음 | 🔴 필수 |
| 2 | 변경 영향 분석 API | 중간 | 🟡 중요 |
| 3 | 단가 버전 그룹 관리 | 높음 | 🟢 권장 |
| 4 | 견적/수주 스냅샷 보존 | 낮음 | 🟡 중요 |

---

## 11. 관련 문서

- [품목 정책](item-policy.md) — 품목 유형 체계 (FG, PT, SM, RM, CS)
- [견적 시스템](../features/quotes/README.md) — BOM 산출, 견적 생성 흐름
- [API 개발 규칙](../dev/standards/api-rules.md) — Service-First 패턴
- [DB 스키마](../system/database/README.md) — 테이블 관계

---

**최종 업데이트**: 2026-03-19