# SAM 사용법 설명 영상 자동 생성 시스템 계획서

> 목적: 고객에게 SAM 사이트의 사용법을 설명하는 영상을 AI 기반으로 자동 생성

---

## 1. 핵심 아이디어

```
SAM 화면 스크린샷 → AI 분석 → 설명 대본 생성 → 주석 슬라이드 생성 → 나레이션 + 영상 합성
```

고객이 SAM의 특정 메뉴/화면을 선택하면, AI가 해당 화면을 분석하여 "사용법 설명 영상"을 자동으로 만들어주는 시스템.

---

## 2. 기술 가능성 분석

| 기술 | 활용 | 현재 보유 여부 |
|------|------|---------------|
| **Gemini API** (스크린샷 분석) | 화면 캡처 → UI 요소 인식 + 설명 대본 생성 | ✅ API Key 보유 |
| **Google Cloud TTS** | 대본 → 한국어 나레이션 음성 생성 | ✅ 이미 Veo3에서 사용 중 |
| **FFmpeg** | 이미지 시퀀스 + 나레이션 + BGM → MP4 합성 | ✅ Docker에 설치됨 |
| **LibreOffice** | PPTX → 슬라이드 이미지 변환 | ⬜ Docker에 설치 필요 |
| **python-pptx** | 주석/하이라이트가 포함된 PPTX 생성 | ⬜ composer/pip 설치 필요 |
| **GD/Imagick (PHP)** | 스크린샷에 하이라이트/화살표/번호 오버레이 | ✅ PHP 확장 사용 가능 |

### 불가능한 것 (제외)
- ❌ python-pptx의 애니메이션 기능 → **미지원** (대안: 단계별 슬라이드 분리)
- ❌ Veo로 PPTX 직접 변환 → **미지원** (대안: 이미지 시퀀스 + FFmpeg)
- ❌ LibreOffice의 애니메이션/전환 효과 보존 → **손실됨** (대안: FFmpeg 전환 효과)

---

## 3. 생성 파이프라인

### Phase 1: 입력 & AI 분석

```
[사용자]
    │
    ├── SAM 메뉴 선택 (예: "견적서 관리")
    │
    └── 시스템이 해당 화면의 스크린샷을 자동 캡처
         또는 사용자가 스크린샷 업로드
```

**Gemini 분석 (핵심)**
```
입력: SAM 화면 스크린샷 이미지
출력 (JSON):
{
  "page_title": "견적서 관리",
  "page_description": "견적서를 생성, 조회, 수정할 수 있는 화면입니다.",
  "ui_elements": [
    {
      "name": "검색 필터",
      "type": "form",
      "position": {"x": 100, "y": 200, "w": 800, "h": 60},
      "description": "날짜, 거래처, 상태 등으로 견적서를 검색합니다.",
      "how_to_use": "원하는 조건을 선택한 후 검색 버튼을 클릭하세요."
    },
    {
      "name": "신규 작성 버튼",
      "type": "button",
      "position": {"x": 900, "y": 150, "w": 120, "h": 40},
      "description": "새 견적서를 작성합니다.",
      "how_to_use": "버튼을 클릭하면 견적서 작성 화면으로 이동합니다."
    }
  ],
  "step_by_step": [
    {"step": 1, "action": "검색 필터에서 조건을 설정합니다", "focus_element": "검색 필터"},
    {"step": 2, "action": "검색 버튼을 클릭합니다", "focus_element": "검색 버튼"},
    {"step": 3, "action": "목록에서 원하는 견적서를 클릭합니다", "focus_element": "견적서 목록"},
    {"step": 4, "action": "상세 화면에서 내용을 확인합니다", "focus_element": "상세 영역"}
  ],
  "narration_script": "이 화면은 견적서 관리 화면입니다. 상단의 검색 필터로..."
}
```

### Phase 2: 주석 슬라이드 생성

각 step마다 스크린샷에 시각적 주석을 오버레이하여 슬라이드 이미지 생성:

```
원본 스크린샷
    │
    ├── Step 1 이미지: 검색 필터 영역에 빨간 테두리 + ① 번호 + 화살표
    ├── Step 2 이미지: 검색 버튼에 빨간 테두리 + ② 번호 + "클릭" 텍스트
    ├── Step 3 이미지: 목록 행에 하이라이트 + ③ 번호
    └── Step 4 이미지: 상세 영역에 하이라이트 + ④ 번호
```

**주석 스타일:**
- 빨간색/파란색 테두리 박스 (해당 UI 요소 강조)
- 번호 원형 배지 (①②③④)
- 화살표 (클릭/입력 방향 지시)
- 반투명 딤 처리 (강조 외 영역 어둡게)
- 하단 캡션 바 (현재 설명 텍스트)

**구현 방식 2가지:**

| 방식 | 장점 | 단점 |
|------|------|------|
| **A. PHP GD/Imagick** | 추가 설치 없음, Laravel 통합 용이 | 복잡한 그래픽 한계 |
| **B. PPTX 생성 → 이미지 변환** | 풍부한 레이아웃, 다운로드 가능 | LibreOffice 설치 필요 |

**권장: 두 방식 병행**
- 영상용: PHP GD로 직접 이미지 생성 (빠름)
- 다운로드용: PPTX도 함께 생성 (고객이 편집 가능)

### Phase 3: 나레이션 생성

```
Gemini가 생성한 step별 대본
    │
    └── Google Cloud TTS (ko-KR-Neural2-A, 여성, 1.2x)
         │
         ├── step_1_narration.mp3 (3초)
         ├── step_2_narration.mp3 (2초)
         ├── step_3_narration.mp3 (4초)
         └── step_4_narration.mp3 (3초)
```

### Phase 4: 영상 합성 (FFmpeg)

```
슬라이드 이미지 + 나레이션 + 전환효과 + BGM → 최종 MP4

ffmpeg 처리:
1. 각 슬라이드를 나레이션 길이 + 1초 여유만큼 표시
2. 슬라이드 전환: crossfade 0.5초 (부드러운 전환)
3. 나레이션 오디오 합성
4. 배경음악 (볼륨 낮게) 합성
5. 인트로/아웃트로 슬라이드 추가
```

**FFmpeg 전환 효과 (애니메이션 대체):**
```bash
# 크로스페이드 전환
-filter_complex "xfade=transition=fade:duration=0.5:offset=4"

# 줌인 효과 (요소 강조 시)
-filter_complex "zoompan=z='min(zoom+0.001,1.3)':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=75"

# 슬라이드 와이프 전환
-filter_complex "xfade=transition=wipeleft:duration=0.5:offset=4"
```

---

## 4. 화면 구성 (MNG 관리자 UI)

```
┌─────────────────────────────────────────────────────┐
│  SAM 사용법 영상 생성기                               │
├─────────────────────────────────────────────────────┤
│                                                      │
│  [Step 1] 화면 선택                                   │
│  ┌──────────────────────────────────────────┐        │
│  │ 메뉴 트리에서 선택  또는  스크린샷 업로드    │        │
│  │                                          │        │
│  │  📁 견적 관리                             │        │
│  │    ├── 견적서 목록                        │        │
│  │    ├── 견적서 작성                        │        │
│  │    └── 견적서 상세                        │        │
│  │  📁 주문 관리                             │        │
│  │    ├── ...                               │        │
│  │                                          │        │
│  │  [스크린샷 직접 업로드] [URL로 캡처]       │        │
│  └──────────────────────────────────────────┘        │
│                                                      │
│  [Step 2] AI 분석 결과 확인/편집                      │
│  ┌──────────────────────────────────────────┐        │
│  │ 🤖 AI가 분석한 UI 요소:                   │        │
│  │                                          │        │
│  │  ① 검색 필터 [수정]                       │        │
│  │    설명: 날짜, 거래처 등으로 검색...       │        │
│  │  ② 신규 작성 버튼 [수정]                   │        │
│  │    설명: 새 견적서를 작성합니다...          │        │
│  │  ③ 견적서 목록 [수정]                      │        │
│  │    설명: 조회된 견적서 목록...              │        │
│  │                                          │        │
│  │  나레이션 대본: [편집 가능한 텍스트]       │        │
│  │  음성: [여성 ▼] 속도: [1.2x ▼]           │        │
│  └──────────────────────────────────────────┘        │
│                                                      │
│  [Step 3] 미리보기 & 생성                             │
│  ┌──────────────────────────────────────────┐        │
│  │  [미리보기: 주석 슬라이드 캐러셀]          │        │
│  │  ◀ [슬라이드 1/4] ▶                       │        │
│  │                                          │        │
│  │  [🎬 영상 생성]  [📄 PPTX 다운로드]      │        │
│  └──────────────────────────────────────────┘        │
│                                                      │
└─────────────────────────────────────────────────────┘
```

---

## 5. 영상 구성 템플릿

### 기본 영상 구조 (1개 화면당)

| 구간 | 시간 | 내용 |
|------|------|------|
| **인트로** | 3초 | SAM 로고 + "견적서 관리 사용법" 타이틀 |
| **전체 화면 소개** | 5초 | 원본 스크린샷 + "이 화면은 ~입니다" 나레이션 |
| **Step 1** | 나레이션 길이 + 1초 | 요소 ① 하이라이트 + 설명 나레이션 |
| **Step 2** | 나레이션 길이 + 1초 | 요소 ② 하이라이트 + 설명 나레이션 |
| **Step N** | ... | ... |
| **아웃트로** | 3초 | "문의: support@juil.co.kr" + 로고 |

### 예상 영상 길이
- 단순 화면 (3~4개 요소): 30~45초
- 복잡한 화면 (6~8개 요소): 60~90초
- 워크플로우 (여러 화면 연결): 2~3분

---

## 6. 구현 단계별 로드맵

### Stage 1: 핵심 파이프라인 (MVP) — 2주

**목표: 스크린샷 1장 → 설명 영상 1개 생성**

```
구현 항목:
├── [백엔드] TutorialVideoController (CRUD + 생성 Job)
├── [백엔드] ScreenAnalysisService (Gemini 스크린샷 분석)
├── [백엔드] SlideImageService (PHP GD로 주석 이미지 생성)
├── [백엔드] TutorialAssemblyService (FFmpeg 영상 합성)
├── [백엔드] TutorialVideoJob (Queue Job)
├── [프론트] 스크린샷 업로드 + AI 분석 결과 UI
├── [프론트] 영상 생성/미리보기/다운로드
└── [인프라] Docker에 LibreOffice 설치 (PPTX→이미지 변환용)
```

**사용하는 API:**
- Gemini 3.0 Flash → 스크린샷 분석 + 대본 생성
- Google Cloud TTS → 나레이션 음성
- FFmpeg → 최종 영상 합성

**비용 (영상 1개당):**
- Gemini: ~$0.001 (이미지 분석)
- TTS: ~$0.01 (60초 나레이션)
- **총 약 $0.01/영상** (Veo 미사용)

### Stage 2: PPTX 생성 + 편집 기능 — 1주

```
추가 구현:
├── [백엔드] PptxGeneratorService (python-pptx 기반 PPTX 생성)
│   ├── 인트로 슬라이드 (SAM 로고 + 제목)
│   ├── Step별 주석 슬라이드
│   └── 아웃트로 슬라이드
├── [프론트] AI 분석 결과 편집 (요소 추가/삭제/순서 변경)
├── [프론트] 나레이션 대본 직접 편집
└── [프론트] PPTX 다운로드 버튼
```

### Stage 3: 고급 기능 — 2주

```
추가 구현:
├── SAM 메뉴 트리 연동 (메뉴 선택 → 해당 화면 자동 캡처)
├── 다중 화면 워크플로우 (화면 A → B → C 연결 영상)
├── FFmpeg 줌/팬 애니메이션 (요소별 줌인 효과)
├── 영상 템플릿 시스템 (인트로/아웃트로 커스터마이징)
├── Lyria BGM 자동 생성 (기존 BgmService 재사용)
└── 생성된 영상 관리 (목록, 삭제, 재생성)
```

### Stage 4: 자동화 & 배포 — 1주

```
추가 구현:
├── 고객 포털에 영상 임베드 (공개 URL)
├── SAM 화면 변경 시 영상 자동 재생성 알림
├── 다국어 지원 (영어/일본어 나레이션)
└── GCS 업로드 + CDN 배포
```

---

## 7. 기술 아키텍처

```
┌─────────────────────────────────────────────────────────────┐
│                        MNG (Laravel)                         │
│                                                              │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐ │
│  │ Tutorial      │   │ Screen       │   │ SlideImage       │ │
│  │ Video         │──▶│ Analysis     │──▶│ Service          │ │
│  │ Controller    │   │ Service      │   │ (PHP GD)         │ │
│  └──────┬───────┘   │ (Gemini)     │   └────────┬─────────┘ │
│         │            └──────────────┘            │            │
│         ▼                                        ▼            │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐ │
│  │ Tutorial      │   │ TTS          │   │ Tutorial         │ │
│  │ Video Job     │──▶│ Service      │──▶│ Assembly Service  │ │
│  │ (Queue)       │   │ (기존 재사용) │   │ (FFmpeg 합성)    │ │
│  └──────────────┘   └──────────────┘   └──────────────────┘ │
│                                                              │
│  ┌──────────────┐   ┌──────────────┐                        │
│  │ Pptx         │   │ BGM          │                        │
│  │ Generator    │   │ Service      │                        │
│  │ (python-pptx)│   │ (기존 재사용) │                        │
│  └──────────────┘   └──────────────┘                        │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
              ┌───────────────────────┐
              │   Google Cloud APIs    │
              │                       │
              │  • Gemini 3.0 Flash   │
              │    (스크린샷 분석)      │
              │  • Cloud TTS          │
              │    (나레이션 생성)      │
              │  • Lyria (BGM, 선택)  │
              │  • GCS (영상 저장)     │
              └───────────────────────┘
```

---

## 8. 기존 코드 재사용

| 기존 서비스 | 재사용 내용 |
|------------|-----------|
| `TtsService` | 나레이션 음성 생성 (ko-KR-Neural2-A) |
| `BgmService` | 배경음악 생성 (Lyria or 프리셋) |
| `VideoAssemblyService` | FFmpeg 합성 로직 참고 (새 서비스로 분리) |
| `GeminiScriptService.callGemini()` | Gemini API 호출 공통 로직 |
| `GoogleCloudStorageService` | GCS 업로드/서명 URL |
| `GoogleCloudService` | OAuth 토큰 관리 |

---

## 9. DB 스키마 (신규 테이블)

```sql
CREATE TABLE tutorial_videos (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id INT UNSIGNED NOT NULL,
    user_id INT UNSIGNED NOT NULL,

    -- 입력
    title VARCHAR(255) NOT NULL COMMENT '영상 제목 (예: 견적서 관리 사용법)',
    menu_id INT UNSIGNED NULL COMMENT 'SAM 메뉴 ID (선택)',
    screenshot_path TEXT NULL COMMENT '원본 스크린샷 경로',

    -- AI 분석 결과
    analysis JSON NULL COMMENT 'Gemini 분석 결과 (UI 요소, 대본 등)',

    -- 생성 설정
    voice_name VARCHAR(50) DEFAULT 'ko-KR-Neural2-A',
    speaking_rate DECIMAL(3,1) DEFAULT 1.2,
    bgm_mood VARCHAR(50) DEFAULT 'calm',

    -- 출력
    status VARCHAR(30) DEFAULT 'pending',
    progress TINYINT UNSIGNED DEFAULT 0,
    current_step VARCHAR(100) NULL,
    slides_data JSON NULL COMMENT '생성된 슬라이드 이미지 경로들',
    pptx_path TEXT NULL COMMENT 'PPTX 파일 경로',
    output_path TEXT NULL COMMENT '최종 MP4 경로',
    gcs_path VARCHAR(500) NULL,
    cost_usd DECIMAL(8,4) DEFAULT 0,
    error_message TEXT NULL,

    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,

    INDEX idx_tenant_user (tenant_id, user_id),
    INDEX idx_status (status)
);
```

---

## 10. 비용 분석

### 영상 1개 생성 비용

| 항목 | 비용 | 비고 |
|------|------|------|
| Gemini (스크린샷 분석) | ~$0.001 | Flash 모델, 이미지 1장 |
| Google Cloud TTS | ~$0.01 | 60초 분량 나레이션 |
| Lyria BGM (선택) | ~$0.06 | 30초 BGM 생성 |
| FFmpeg | $0 | 로컬 처리 |
| GCS 저장 | ~$0.001 | 50MB 영상 기준 |
| **합계** | **~$0.07** | Veo 미사용으로 저렴 |

### Veo3 Shorts 영상 대비

| | 튜토리얼 영상 | Veo3 Shorts |
|--|-------------|------------|
| 영상당 비용 | ~$0.07 | ~$7.00 |
| 생성 시간 | 1~2분 | 15~25분 |
| 용도 | 화면 설명 | 창작 콘텐츠 |

---

## 11. 기대 효과

1. **고객 문의 감소**: 반복되는 "이 기능 어떻게 쓰나요?" 문의를 영상으로 대체
2. **빠른 온보딩**: 신규 고객이 SAM 주요 기능을 영상으로 빠르게 학습
3. **유지보수 용이**: 화면 변경 시 스크린샷만 다시 업로드하면 영상 재생성
4. **PPTX 병행**: 영상뿐 아니라 인쇄용 매뉴얼(PPTX)도 동시 제공
5. **저비용**: Veo 없이 이미지+TTS+FFmpeg만으로 영상당 $0.07

---

## 12. 우선순위 제안

| 순위 | 항목 | 이유 |
|------|------|------|
| 1 | Stage 1 (MVP) | 핵심 가치 검증 — 스크린샷 1장으로 영상 생성 가능 여부 확인 |
| 2 | Stage 2 (PPTX) | 고객이 직접 편집 가능한 산출물 제공 |
| 3 | Stage 3 (고급) | 줌 애니메이션, 다중 화면 워크플로우로 품질 향상 |
| 4 | Stage 4 (배포) | 고객 포털 연동, 자동화 |
