# SAM 상품관리 시스템 개발 문서

> 작성일: 2026-01-29
> 목적: SAM 솔루션 상품의 가격 구조 및 계약 관리 시스템 문서화

---

## 1. 개요

SAM 상품관리 시스템은 본사(HQ)에서 SAM 솔루션 상품을 관리하고, 영업 과정에서 고객사(테넌트)에게 상품을 선택/계약하는 기능을 제공합니다.

### 1.1 주요 기능
- **상품 카테고리 관리**: 업종별 상품 분류 (제조업체, 공사업체 등)
- **상품 관리**: 개별 솔루션 상품 CRUD
- **계약 상품 선택**: 영업 시나리오에서 고객사별 상품 선택
- **가격 커스터마이징**: 재량권 상품의 가격 조정

---

## 2. 데이터베이스 구조

### 2.1 상품 카테고리 테이블 (`sales_product_categories`)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| `id` | bigint | PK |
| `code` | varchar | 카테고리 코드 (예: `manufacturer`, `contractor`) |
| `name` | varchar | 카테고리명 (예: "제조 업체", "공사 업체") |
| `description` | text | 설명 |
| `base_storage` | varchar | 기본 저장소 경로 |
| `display_order` | int | 정렬 순서 |
| `is_active` | boolean | 활성화 여부 |
| `deleted_at` | timestamp | 소프트 삭제 |

### 2.2 상품 테이블 (`sales_products`)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| `id` | bigint | PK |
| `category_id` | bigint | FK → sales_product_categories |
| `code` | varchar | 상품 코드 |
| `name` | varchar | 상품명 |
| `description` | text | 상품 설명 |
| `development_fee` | decimal(15,2) | **개발비** (원가) |
| `registration_fee` | decimal(15,2) | **가입비** (고객 청구 금액) |
| `subscription_fee` | decimal(15,2) | **월 구독료** |
| `partner_commission_rate` | decimal(5,2) | **영업파트너 수당율** (%) |
| `manager_commission_rate` | decimal(5,2) | **매니저 수당율** (%) |
| `allow_flexible_pricing` | boolean | 재량권 허용 여부 |
| `is_required` | boolean | 필수 상품 여부 |
| `display_order` | int | 정렬 순서 |
| `is_active` | boolean | 활성화 여부 |
| `deleted_at` | timestamp | 소프트 삭제 |

### 2.3 계약 상품 테이블 (`sales_contract_products`)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| `id` | bigint | PK |
| `tenant_id` | bigint | FK → tenants (고객사) |
| `management_id` | bigint | FK → sales_tenant_managements |
| `category_id` | bigint | FK → sales_product_categories |
| `product_id` | bigint | FK → sales_products |
| `registration_fee` | decimal(15,2) | 실제 청구 가입비 (커스텀 가능) |
| `subscription_fee` | decimal(15,2) | 실제 청구 구독료 (커스텀 가능) |
| `discount_rate` | decimal(5,2) | 할인율 |
| `notes` | text | 비고 |
| `created_by` | bigint | 등록자 |

---

## 3. 가격 구조

### 3.1 가격 체계

```
┌─────────────────────────────────────────────────────────────────┐
│                        가격 구조 다이어그램                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   개발비 (Development Fee)                                       │
│   ├── 원가 개념, 내부 관리용                                      │
│   └── 예: ₩80,000,000                                           │
│                                                                 │
│   가입비 (Registration Fee)                                      │
│   ├── 고객에게 청구하는 금액                                      │
│   ├── 일반적으로 개발비의 25%                                     │
│   └── 예: ₩20,000,000 (80,000,000 × 25%)                        │
│                                                                 │
│   월 구독료 (Subscription Fee)                                   │
│   ├── 매월 청구되는 구독 비용                                     │
│   └── 예: ₩500,000/월                                           │
│                                                                 │
│   수당 (Commission)                                              │
│   ├── 영업파트너 수당: 가입비 × 20%                               │
│   ├── 매니저 수당: 가입비 × 5%                                    │
│   └── 총 수당율: 25%                                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 3.2 가격 계산 공식

```php
// 가입비 = 개발비 × 25% (기본값)
$registration_fee = $development_fee * 0.25;

// 영업파트너 수당 = 가입비 × 20%
$partner_commission = $registration_fee * 0.20;

// 매니저 수당 = 가입비 × 5%
$manager_commission = $registration_fee * 0.05;

// 총 수당
$total_commission = $partner_commission + $manager_commission;
```

### 3.3 표시 예시 (UI)

```
┌──────────────────────────────────────────┐
│  SAM 기본 솔루션                          │
│                                          │
│  가입비: ₩80,000,000 → ₩20,000,000       │
│          (취소선)      (할인가)           │
│                                          │
│  월 구독료: ₩500,000                      │
│                                          │
│  수당: 영업파트너 20% | 매니저 5%          │
└──────────────────────────────────────────┘
```

---

## 4. 상품 카테고리별 구성

### 4.1 제조 업체 (manufacturer)

| 상품명 | 개발비 | 가입비 | 월 구독료 | 파트너 수당 | 매니저 수당 | 필수 |
|--------|--------|--------|-----------|-------------|-------------|------|
| SAM 기본 솔루션 | ₩80,000,000 | ₩20,000,000 | ₩500,000 | 20% | 5% | O |
| ERP 연동 모듈 | ₩40,000,000 | ₩10,000,000 | ₩200,000 | 20% | 5% | - |
| MES 연동 모듈 | ₩60,000,000 | ₩15,000,000 | ₩300,000 | 20% | 5% | - |
| 품질관리 모듈 | ₩20,000,000 | ₩5,000,000 | ₩100,000 | 20% | 5% | - |
| 재고관리 모듈 | ₩16,000,000 | ₩4,000,000 | ₩80,000 | 20% | 5% | - |

### 4.2 공사 업체 (contractor)

| 상품명 | 개발비 | 가입비 | 월 구독료 | 파트너 수당 | 매니저 수당 | 필수 |
|--------|--------|--------|-----------|-------------|-------------|------|
| SAM 공사관리 | ₩60,000,000 | ₩15,000,000 | ₩400,000 | 20% | 5% | O |
| 현장관리 모듈 | ₩24,000,000 | ₩6,000,000 | ₩150,000 | 20% | 5% | - |
| 안전관리 모듈 | ₩20,000,000 | ₩5,000,000 | ₩100,000 | 20% | 5% | - |
| 공정관리 모듈 | ₩32,000,000 | ₩8,000,000 | ₩200,000 | 20% | 5% | - |

---

## 5. 모델 클래스

### 5.1 SalesProduct 모델

**파일 위치**: `app/Models/Sales/SalesProduct.php`

```php
class SalesProduct extends Model
{
    use SoftDeletes;

    protected $fillable = [
        'category_id', 'code', 'name', 'description',
        'development_fee', 'registration_fee', 'subscription_fee',
        'partner_commission_rate', 'manager_commission_rate',
        'allow_flexible_pricing', 'is_required',
        'display_order', 'is_active',
    ];

    // Accessors
    public function getTotalCommissionRateAttribute(): float
    {
        return $this->partner_commission_rate + $this->manager_commission_rate;
    }

    public function getCommissionAttribute(): float
    {
        return $this->development_fee * ($this->total_commission_rate / 100);
    }

    public function getFormattedDevelopmentFeeAttribute(): string
    {
        return '₩' . number_format($this->development_fee);
    }

    public function getFormattedRegistrationFeeAttribute(): string
    {
        return '₩' . number_format($this->registration_fee);
    }

    public function getFormattedSubscriptionFeeAttribute(): string
    {
        return '₩' . number_format($this->subscription_fee);
    }
}
```

### 5.2 SalesProductCategory 모델

**파일 위치**: `app/Models/Sales/SalesProductCategory.php`

```php
class SalesProductCategory extends Model
{
    use SoftDeletes;

    protected $fillable = [
        'code', 'name', 'description',
        'base_storage', 'display_order', 'is_active',
    ];

    public function products(): HasMany
    {
        return $this->hasMany(SalesProduct::class, 'category_id');
    }

    public function activeProducts(): HasMany
    {
        return $this->products()->where('is_active', true)->orderBy('display_order');
    }
}
```

### 5.3 SalesContractProduct 모델

**파일 위치**: `app/Models/Sales/SalesContractProduct.php`

```php
class SalesContractProduct extends Model
{
    protected $fillable = [
        'tenant_id', 'management_id', 'category_id', 'product_id',
        'registration_fee', 'subscription_fee',
        'discount_rate', 'notes', 'created_by',
    ];

    // 테넌트별 총 가입비
    public static function getTotalRegistrationFee(int $tenantId): float
    {
        return self::where('tenant_id', $tenantId)->sum('registration_fee') ?? 0;
    }

    // 테넌트별 총 구독료
    public static function getTotalSubscriptionFee(int $tenantId): float
    {
        return self::where('tenant_id', $tenantId)->sum('subscription_fee') ?? 0;
    }
}
```

---

## 6. API 엔드포인트

### 6.1 상품 관리 (HQ 전용)

| Method | URI | 설명 |
|--------|-----|------|
| GET | `/sales/products` | 상품 목록 페이지 |
| POST | `/sales/products` | 상품 생성 |
| PUT | `/sales/products/{id}` | 상품 수정 |
| DELETE | `/sales/products/{id}` | 상품 삭제 |
| POST | `/sales/products/categories` | 카테고리 생성 |
| PUT | `/sales/products/categories/{id}` | 카테고리 수정 |
| DELETE | `/sales/products/categories/{id}` | 카테고리 삭제 |

### 6.2 계약 상품 선택 (영업 시나리오)

| Method | URI | 설명 |
|--------|-----|------|
| POST | `/sales/contracts/products` | 상품 선택 저장 |

**요청 본문**:
```json
{
    "tenant_id": 123,
    "category_id": 1,
    "products": [
        {
            "product_id": 1,
            "category_id": 1,
            "registration_fee": 20000000,
            "subscription_fee": 500000
        }
    ]
}
```

---

## 7. 영업 시나리오 연동

### 7.1 계약 체결 단계 (Step 6)

영업 시나리오의 6단계 "계약 체결"에서 상품 선택 UI가 표시됩니다.

**파일 위치**: `resources/views/sales/modals/partials/product-selection.blade.php`

### 7.2 상품 선택 흐름

```
1. 영업 시나리오 모달 열기
   ↓
2. "계약 체결" 탭 선택
   ↓
3. 카테고리 탭 선택 (제조업체/공사업체)
   ↓
4. 상품 체크박스 선택/해제
   ↓
5. 합계 자동 계산 (선택된 카테고리 기준)
   ↓
6. "상품 선택 저장" 버튼 클릭
   ↓
7. sales_contract_products 테이블에 저장
```

### 7.3 내 계약 현황 표시

**파일 위치**: `resources/views/sales/dashboard/partials/tenant-list.blade.php`

각 테넌트 행에 계약 금액 정보가 표시됩니다:
- 총 가입비: `SalesContractProduct::getTotalRegistrationFee($tenantId)`
- 총 구독료: `SalesContractProduct::getTotalSubscriptionFee($tenantId)`

---

## 8. 주요 속성 설명

### 8.1 `is_required` (필수 상품)

- `true`: 해제 불가, 항상 선택된 상태
- 예: "SAM 기본 솔루션"은 필수

### 8.2 `allow_flexible_pricing` (재량권)

- `true`: 영업 담당자가 가격 조정 가능
- UI에서 "재량권" 뱃지로 표시

### 8.3 개발비 vs 가입비

| 구분 | 개발비 (development_fee) | 가입비 (registration_fee) |
|------|-------------------------|--------------------------|
| 용도 | 내부 원가 관리 | 고객 청구 금액 |
| 표시 | 취소선으로 표시 | 실제 금액으로 표시 |
| 비율 | 100% (기준) | 25% (기본) |
| 수당 계산 | 기준 금액 | - |

---

## 9. 수당 계산 예시

### 9.1 단일 상품 계약

```
상품: SAM 기본 솔루션
개발비: ₩80,000,000
가입비: ₩20,000,000

영업파트너 수당 = ₩20,000,000 × 20% = ₩4,000,000
매니저 수당 = ₩20,000,000 × 5% = ₩1,000,000
총 수당 = ₩5,000,000
```

### 9.2 복수 상품 계약

```
상품1: SAM 기본 솔루션 (가입비 ₩20,000,000)
상품2: ERP 연동 모듈 (가입비 ₩10,000,000)
상품3: 품질관리 모듈 (가입비 ₩5,000,000)

총 가입비 = ₩35,000,000

영업파트너 수당 = ₩35,000,000 × 20% = ₩7,000,000
매니저 수당 = ₩35,000,000 × 5% = ₩1,750,000
총 수당 = ₩8,750,000
```

---

## 10. 확장 가능성

### 10.1 추가 개발 가능 기능

1. **수당 정산 시스템**: 월별 수당 정산 및 지급 관리
2. **가격 이력 관리**: 상품 가격 변경 이력 추적
3. **할인 정책**: 다양한 할인 유형 (볼륨, 기간, 특별)
4. **번들 상품**: 여러 상품을 묶은 패키지 상품
5. **구독 관리**: 구독 갱신, 해지, 업그레이드 관리

### 10.2 API 확장

```php
// 수당 계산 API
GET /api/sales/commissions/calculate?tenant_id={id}

// 가격 이력 조회
GET /api/sales/products/{id}/price-history

// 할인 적용
POST /api/sales/contracts/{id}/apply-discount
```

---

## 11. 관련 파일 목록

### 11.1 모델
- `app/Models/Sales/SalesProduct.php`
- `app/Models/Sales/SalesProductCategory.php`
- `app/Models/Sales/SalesContractProduct.php`

### 11.2 컨트롤러
- `app/Http/Controllers/Sales/SalesProductController.php`
- `app/Http/Controllers/Sales/SalesContractController.php`

### 11.3 뷰
- `resources/views/sales/products/index.blade.php` (상품관리 페이지)
- `resources/views/sales/products/partials/product-list.blade.php` (상품 목록)
- `resources/views/sales/modals/partials/product-selection.blade.php` (상품 선택)
- `resources/views/sales/dashboard/partials/tenant-list.blade.php` (계약 현황)

### 11.4 마이그레이션 (API 프로젝트)
- `database/migrations/xxxx_create_sales_product_categories_table.php`
- `database/migrations/xxxx_create_sales_products_table.php`
- `database/migrations/xxxx_create_sales_contract_products_table.php`
- `database/migrations/xxxx_add_registration_fee_to_sales_products_table.php`
- `database/migrations/xxxx_add_partner_manager_commission_to_sales_products_table.php`

---

## 12. 변경 이력

| 날짜 | 변경 내용 | 작성자 |
|------|----------|--------|
| 2026-01-29 | 최초 문서 작성 | Claude |
| 2026-01-29 | 가입비/개발비 분리, 수당율 분리 (파트너/매니저) | Claude |