sam-docs/dev/guides/상품관리정보.md

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 가격 계산 공식

// 가입비 = 개발비 × 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

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

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

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	상품 선택 저장

요청 본문:

{
    "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 확장

// 수당 계산 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