From 19e85e4b024650dfff83d6e228fabab7a1f6343a Mon Sep 17 00:00:00 2001 From: pro Date: Thu, 29 Jan 2026 17:32:21 +0900 Subject: [PATCH] =?UTF-8?q?docs:=EC=83=81=ED=92=88=EA=B4=80=EB=A6=AC=20?= =?UTF-8?q?=EC=8B=9C=EC=8A=A4=ED=85=9C=20=EA=B0=9C=EB=B0=9C=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=EC=9E=91=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 데이터베이스 구조 (카테고리, 상품, 계약상품) - 가격 구조 (개발비, 가입비, 구독료, 수당) - 가격 계산 공식 및 예시 - 모델 클래스 설명 - API 엔드포인트 - 영업 시나리오 연동 흐름 - 확장 가능성 Co-Authored-By: Claude Opus 4.5 --- claudedocs/상품관리정보.md | 443 +++++++++++++++++++++++++++++++++++++ 1 file changed, 443 insertions(+) create mode 100644 claudedocs/상품관리정보.md diff --git a/claudedocs/상품관리정보.md b/claudedocs/상품관리정보.md new file mode 100644 index 00000000..027c404e --- /dev/null +++ b/claudedocs/상품관리정보.md @@ -0,0 +1,443 @@ +# 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 |