# Phase 3 설계 스펙: 이미지 생성 + 리뷰 워크플로 + PDF 출력

**작성일**: 2026-03-15
**상태**: 승인됨
**범위**: Phase 3a/3b/3c 통합

---

## 1. 개요

Phase 3는 엔티티 참조 이미지와 씬 장면 이미지를 생성하고, 검수 워크플로를 통해 승인/재생성하며, 최종 웹북 PDF를 렌더링한다.

## 2. Phase 3a: 이미지 생성 모듈

### 2.1 Gemini 이미지 생성 클라이언트

```
backend/app/modules/llm/gemini_image_client.py
```

- Gemini `gemini-3.1-flash-image-preview` 모델 사용
- urllib 기반 API 호출 (기존 패턴)
- 텍스트 프롬프트 → 이미지 생성
- 참조 이미지 포함 요청 (base64 인코딩)
- 환경변수: `GEMINI_API_KEY`

### 2.2 참조 이미지 생성 모듈

```
backend/app/modules/reference_image_generator.py
```

- 엔티티별 참조 이미지 생성 (캐릭터: 3:4, 배경: 16:9, 소품: 1:1)
- 프롬프트: `prompts/_base/prototype_prompts/v5/entity_reference_ko.md`
- 세계관 가이드 + 엔티티 정보 기반 프롬프트 조합
- 생성된 이미지를 `projects/{id}/assets/references/{entity_id}.png`에 저장

### 2.3 씬 이미지 생성 모듈

```
backend/app/modules/scene_image_generator.py
```

- 씬 스틸별 장면 이미지 생성 (16:9)
- 프롬프트: `prompts/_base/prototype_prompts/v5/scene_image_ko.md`
- 가시 엔티티의 참조 이미지를 context로 포함
- 이전 씬 이미지를 연속성 context로 포함
- 특수 캐릭터 가드레일 적용 (DR.NEX, 한치호 등)
- `projects/{id}/assets/generated/{still_id}.png`에 저장

### 2.4 세계관 가이드 생성

```
backend/app/modules/world_guide_generator.py
```

- 에피소드 fulltext → 세계관/시대/의상/장비 가이드 추출
- 프롬프트: `prompts/_base/prototype_prompts/v5/world_guide_system.md`
- 이미지 생성 시 일관성 유지용

### 2.5 프로젝트 DB 스키마 추가

```sql
-- 이미지 에셋
image_asset (
    id              TEXT PRIMARY KEY,
    asset_type      TEXT NOT NULL,      -- 'reference' | 'scene'
    entity_id       TEXT,               -- 참조 이미지일 때
    still_id        TEXT,               -- 씬 이미지일 때
    episode_id      TEXT,
    file_path       TEXT NOT NULL,
    prompt_used     TEXT,
    generation_model TEXT,
    width           INTEGER,
    height          INTEGER,
    status          TEXT DEFAULT 'generated',  -- generated|approved|needs_fix|regenerating
    review_notes    TEXT DEFAULT '',
    created_at      TEXT NOT NULL
)

-- 세계관 가이드
world_guide (
    id              TEXT PRIMARY KEY,
    episode_id      TEXT REFERENCES episode(id),
    guide_json      TEXT NOT NULL,       -- 세계관 가이드 전체 JSON
    created_at      TEXT NOT NULL
)

-- 웹북 패키지
webbook_package (
    id              TEXT PRIMARY KEY,
    episode_id      TEXT REFERENCES episode(id),
    package_json    TEXT NOT NULL,       -- 에피소드 분할/텍스트 구조 JSON
    prompt_version  TEXT,
    created_at      TEXT NOT NULL
)
```

### 2.6 API

| 메서드 | 경로 | 설명 |
|--------|------|------|
| POST | `/api/v1/projects/{id}/episodes/{ep_id}/generate-images` | 이미지 생성 시작 |
| GET | `/api/v1/projects/{id}/images` | 프로젝트 이미지 목록 |
| GET | `/api/v1/projects/{id}/images/{img_id}` | 이미지 상세 |
| GET | `/api/v1/projects/{id}/images/{img_id}/file` | 이미지 파일 서빙 |

### 2.7 설정 추가

```
GEMINI_API_KEY=xxx
GEMINI_IMAGE_MODEL=gemini-3.1-flash-image-preview
```

## 3. Phase 3b: 리뷰 워크플로

### 3.1 API

| 메서드 | 경로 | 설명 |
|--------|------|------|
| PATCH | `/api/v1/projects/{id}/images/{img_id}/review` | 리뷰 상태 변경 (approved/needs_fix) |
| POST | `/api/v1/projects/{id}/images/{img_id}/regenerate` | 단일 이미지 재생성 |
| POST | `/api/v1/projects/{id}/episodes/{ep_id}/regenerate-needs-fix` | needs_fix 일괄 재생성 |

### 3.2 리뷰 상태 흐름

```
generated → approved (검수 통과)
generated → needs_fix (수정 필요, 메모 포함)
needs_fix → regenerating → generated (재생성)
```

## 4. Phase 3c: 웹북 PDF 렌더링

### 4.1 웹북 패키지 생성 모듈

```
backend/app/modules/webbook_generator.py
```

- 에피소드 fulltext + 엔티티 + 씬 스틸 → 웹북 에피소드 분할
- 프롬프트: `prompts/_base/prototype_prompts/v5/webbook_package_system.md`
- 에피소드당 여러 웹북 에피소드 (기본 4개, 섹션 10개씩)

### 4.2 PDF 렌더링 모듈

```
backend/app/modules/pdf_renderer.py
```

- fpdf2 기반 long-page PDF 렌더링
- 텍스트 + 이미지 인터리빙
- 한글 폰트 지원 (AppleSDGothicNeo)
- `projects/{id}/assets/exports/` 에 저장

### 4.3 API

| 메서드 | 경로 | 설명 |
|--------|------|------|
| POST | `/api/v1/projects/{id}/episodes/{ep_id}/generate-webbook` | 웹북 패키지 생성 |
| POST | `/api/v1/projects/{id}/episodes/{ep_id}/render-pdf` | PDF 렌더링 |
| GET | `/api/v1/projects/{id}/exports` | 내보내기 파일 목록 |
| GET | `/api/v1/projects/{id}/exports/{filename}` | PDF 파일 다운로드 |

### 4.4 프론트엔드

- 이미지 리뷰 보드 (그리드 뷰, 상태 필터, 리뷰 폼)
- 이미지 줌 모달
- 참조 이미지 갤러리
- 웹북 생성 + PDF 렌더링 버튼
- PDF 다운로드 링크

## 5. 모듈 버전

| 모듈 | 버전 | 프롬프트 의존성 |
|------|------|----------------|
| gemini_image_client | 1.0.0 | 없음 |
| reference_image_generator | 1.0.0 | prototype_prompts/v5 (entity_reference) |
| scene_image_generator | 1.0.0 | prototype_prompts/v5 (scene_image) |
| world_guide_generator | 1.0.0 | prototype_prompts/v5 (world_guide) |
| webbook_generator | 1.0.0 | prototype_prompts/v5 (webbook_package) |
| pdf_renderer | 1.0.0 | 없음 |