# 데모 테넌트 사용 가이드

> **작성일**: 2026-03-13
> **상태**: 운영 중
> **대상**: 영업파트너, 관리자

---

## 1. 개요

### 1.1 목적

영업파트너가 고객에게 SAM 시스템을 직접 체험할 수 있는 데모 환경을 제공하고 관리하는 방법을 안내한다.

### 1.2 데모 유형 (3-Tier)

| 티어 | 유형 | 대상 | 기간 | 특징 |
|------|------|------|------|------|
| Tier 1 | 쇼케이스 | 전체 공유 | 무제한 | 읽기 전용, 매일 자동 리셋 |
| Tier 2 | 파트너 데모 | 파트너별 1개 | 파트너 활동 중 | 전체 기능 체험 가능 |
| Tier 3 | 고객 체험 | 영업건별 생성 | 30일 (연장 가능) | 고객 직접 로그인, 정식 전환 가능 |

> **Tier 3 (고객 체험)**이 가장 자주 사용하는 기능이다. 이 문서는 Tier 3 중심으로 설명한다.

---

## 2. 고객 체험 테넌트 생성

### 2.1 Sales 앱에서 생성

Sales 앱의 데모 관리 화면에서 다음 정보를 입력하여 생성한다:

| 항목 | 필수 | 설명 |
|------|:----:|------|
| 회사명 | O | 고객사 이름 (예: "테스트블라인드") |
| 이메일 | O | 고객 담당자 이메일 |
| 체험 기간 | - | 7~60일, 기본 30일 |
| 프리셋 | - | `manufacturing` 선택 시 샘플 데이터 자동 생성 |

### 2.2 프리셋 데이터 (manufacturing)

프리셋을 선택하면 고객이 빈 화면이 아닌 실제 데이터가 입력된 상태에서 체험을 시작한다:

| 데이터 | 건수 | 내용 |
|--------|------|------|
| 부서 | 6개 | 경영지원, 영업, 생산, 품질, 구매, 물류 |
| 거래처 | 10개 | 다양한 업종의 샘플 거래처 |
| 품목 | 20개 | 제품 10 + 자재 10 |
| 견적 | 5건 | 다양한 상태의 견적서 |
| 수주 | 8건 | 확정/진행 중/완료 수주 |
| 대시보드 통계 | 90일 | 매출/생산 차트용 일간 통계 |

### 2.3 API 직접 호출 (개발자용)

```
POST /api/v1/demo-tenants
```

```json
{
  "company_name": "테스트블라인드",
  "email": "customer@example.com",
  "duration_days": 30,
  "preset": "manufacturing"
}
```

**응답 예시:**

```json
{
  "success": true,
  "message": "데모 테넌트가 생성되었습니다.",
  "data": {
    "tenant_id": 292,
    "company_name": "테스트블라인드",
    "tenant_type": "DEMO_TRIAL",
    "demo_expires_at": "2026-04-12",
    "admin_email": "customer@example.com"
  }
}
```

---

## 3. 데모 테넌트 관리

### 3.1 목록 조회

내가 생성한 데모 테넌트 목록을 확인한다.

```
GET /api/v1/demo-tenants
```

### 3.2 상세 조회

특정 데모 테넌트의 상세 정보를 확인한다.

```
GET /api/v1/demo-tenants/{id}
```

### 3.3 데이터 리셋

고객이 데이터를 지저분하게 만들었을 때 초기 상태로 복원한다. 프리셋 데이터가 다시 생성된다.

```
POST /api/v1/demo-tenants/{id}/reset
```

> 리셋은 기존 데이터를 모두 삭제하고 프리셋을 다시 시딩한다. 고객이 직접 입력한 데이터도 삭제된다.

### 3.4 체험 기간 연장

고객이 추가 체험을 원할 때 기간을 연장한다.

```
POST /api/v1/demo-tenants/{id}/extend
```

```json
{
  "days": 14
}
```

> 기본 14일 연장. 연장은 1회만 가능하다.

### 3.5 정식 전환

고객이 계약을 결정하면 데모 테넌트를 정식 테넌트로 전환한다.

```
POST /api/v1/demo-tenants/{id}/convert
```

**전환 시 변경 사항:**

| 항목 | 전환 전 | 전환 후 |
|------|---------|---------|
| 테넌트 유형 | `DEMO_TRIAL` | `STD` (정식) |
| 만료일 | 30일 제한 | 제한 없음 |
| 기능 제한 | 바로빌 등 외부 연동 차단 | 전체 기능 사용 |
| 데이터 | 그대로 유지 | 그대로 유지 |

> 고객이 체험 중 입력한 데이터가 정식 환경에 그대로 이어진다. 데이터 재입력이 불필요하다.

---

## 4. 현황 분석 (관리자용)

### 4.1 대시보드 요약

전체 데모 현황을 한눈에 확인한다.

```
GET /api/v1/demo-analytics/summary
```

**제공 정보:**

- 전환율 퍼널 (체험 → 활성 → 만료 → 전환)
- 전체 전환율 (%)
- 평균 전환 기간 (일)
- 비활성 테넌트 수 (7일 이상 활동 없음)
- 유형별 데모 수 (쇼케이스/파트너/체험)

### 4.2 전환율 퍼널

전체 또는 파트너별 전환율을 분석한다.

```
GET /api/v1/demo-analytics/conversion-funnel
GET /api/v1/demo-analytics/conversion-funnel?partner_id=5
```

**응답 예시:**

```json
{
  "funnel": {
    "total_trials": 15,
    "active_trials": 8,
    "expired_trials": 3,
    "converted": 4
  },
  "conversion_rate": 26.7,
  "avg_conversion_days": 18
}
```

### 4.3 파트너별 성과

각 파트너의 데모 생성 수, 전환 수, 전환율을 비교한다.

```
GET /api/v1/demo-analytics/partner-performance
```

> 전환율 내림차순으로 정렬되어 우수 파트너를 빠르게 파악할 수 있다.

### 4.4 활동 현황 리포트

각 데모 테넌트의 실제 사용 현황을 확인한다.

```
GET /api/v1/demo-analytics/activity-report
GET /api/v1/demo-analytics/activity-report?partner_id=5
```

**활동 상태 분류:**

| 상태 | 기준 | 의미 |
|------|------|------|
| `active` | 1일 이내 활동 | 적극 사용 중 |
| `normal` | 3일 이내 활동 | 정상 사용 중 |
| `low` | 7일 이내 활동 | 관심 저하, 후속 조치 필요 |
| `inactive` | 7일 초과 | 비활성, 즉시 연락 필요 |
| `no_data` | 데이터 없음 | 아직 사용하지 않음 |

---

## 5. 자동 스케줄

시스템이 자동으로 처리하는 작업이다. 별도 조치 불필요.

| 시간 | 작업 | 설명 |
|------|------|------|
| 매일 00:00 | 쇼케이스 리셋 | Tier 1 데모 데이터를 매일 초기화 |
| 매일 04:20 | 만료 체크 | 만료 테넌트 비활성 처리 + D-7 경고 로그 |
| 매일 09:30 | 비활성 알림 | 7일 이상 활동 없는 테넌트 경고 로그 |

---

## 6. Artisan 커맨드 (서버 관리자용)

### 6.1 쇼케이스 리셋

```bash
# 쇼케이스 데이터 삭제 + 샘플 재시딩
php artisan demo:reset-showcase --seed

# 데이터 삭제만 (재시딩 없이)
php artisan demo:reset-showcase
```

### 6.2 만료 테넌트 체크

```bash
# 만료 처리 실행
php artisan demo:check-expired

# 대상만 확인 (변경 없음)
php artisan demo:check-expired --dry-run
```

### 6.3 비활성 테넌트 탐지

```bash
# 기본 7일 기준
php artisan demo:check-inactive

# 기준일 변경 (예: 3일)
php artisan demo:check-inactive --days=3
```

---

## 7. 영업 시나리오별 가이드

### 7.1 고객 방문 영업

```
1. 방문 전: 데모 테넌트 생성 (preset: manufacturing)
2. 방문 시: 고객에게 로그인 정보 전달, 함께 화면 시연
3. 방문 후: 고객이 직접 사용해보도록 안내 (30일 체험)
```

### 7.2 관심 고객 후속 조치

```
1. 활동 리포트 확인 → active/normal이면 전환 제안
2. low/inactive이면 전화 또는 방문하여 추가 시연
3. 데이터가 지저분하면 리셋 후 재시연
```

### 7.3 계약 결정 시

```
1. POST /{id}/convert 로 정식 전환
2. 고객 데이터는 그대로 유지됨 (재입력 불필요)
3. 바로빌 등 외부 연동 기능 활성화
```

### 7.4 체험 기간 부족 시

```
1. POST /{id}/extend 로 14일 연장 (1회 제한)
2. 추가 연장 필요 시 관리자에게 요청
```

---

## 8. API 전체 엔드포인트

### 8.1 데모 관리

| Method | Path | 설명 |
|--------|------|------|
| `GET` | `/api/v1/demo-tenants` | 내 데모 목록 |
| `POST` | `/api/v1/demo-tenants` | 체험 테넌트 생성 |
| `GET` | `/api/v1/demo-tenants/stats` | 간단 통계 |
| `GET` | `/api/v1/demo-tenants/{id}` | 상세 조회 |
| `POST` | `/api/v1/demo-tenants/{id}/reset` | 데이터 리셋 |
| `POST` | `/api/v1/demo-tenants/{id}/extend` | 기간 연장 |
| `POST` | `/api/v1/demo-tenants/{id}/convert` | 정식 전환 |

### 8.2 분석

| Method | Path | 설명 |
|--------|------|------|
| `GET` | `/api/v1/demo-analytics/summary` | 대시보드 요약 |
| `GET` | `/api/v1/demo-analytics/conversion-funnel` | 전환율 퍼널 |
| `GET` | `/api/v1/demo-analytics/partner-performance` | 파트너별 성과 |
| `GET` | `/api/v1/demo-analytics/activity-report` | 활동 현황 |

---

## 관련 문서

| 문서 | 설명 |
|------|------|
| [demo-tenant-policy.md](demo-tenant-policy.md) | 3-Tier 데모 전략 설계 문서 |
| [partners.md](partners.md) | 영업파트너 관리 |
| [README.md](README.md) | 영업 관리 기능 개요 |

---

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