# TheRoad Scene Lab — 프로젝트 개발 요약

**최종 업데이트**: 2026-03-16
**GitHub**: https://github.com/jedikim/theroad-i1 (private)
**커밋**: 104개 | **테스트**: 205개 | **백엔드**: 70 파일 | **프론트엔드**: 32 파일

---

## 1. 프로젝트 목적

영화/드라마 시나리오 PDF를 분석하여 **인물/배경/소품의 시각적 일관성을 유지**하면서 장면 이미지를 생성하고, 소설형 웹북(PDF)으로 출력하는 내부 제작 시스템.

```
시나리오 PDF → 엔티티 추출 → 씬 스틸 추출 → 참조 이미지 → 씬 이미지 → 웹북 → PDF
```

---

## 2. 기술 스택

| 레이어 | 기술 |
|--------|------|
| 백엔드 | Python 3.12, FastAPI, SQLAlchemy |
| DB | PostgreSQL 17 (Docker) |
| 프론트엔드 | React 18, Vite, TypeScript, Three.js |
| LLM (텍스트) | OpenAI GPT-5.5 |
| T2I (이미지 생성) | Google Gemini 3.1 Flash Image Preview |
| I2I (이미지 편집) | Gemini i2i (앵글/색감), fal.ai (앵글) |
| PDF | fpdf2 |
| 배포 | Docker Compose |

---

## 3. 핵심 파이프라인

### 3.1 시나리오 분석

```
PDF 업로드 → 텍스트 추출 (pypdf, NUL 바이트 제거)
  → GPT-5.5 엔티티 추출 (프롬프트 v7)
    - 주요 인물 5~15명, 배경 3~8곳, 핵심 소품 2~5개
    - 시각적 관계만: identity, transformation, possession
    - 이전 에피소드 메모리 축약 전달
  → GPT-5.5 씬 스틸 추출
    - 카메라: angle만 / 조명: mood만 (간소화)
    - 청킹 금지 — 전문 1회 전달
```

### 3.2 참조 이미지 생성

```
엔티티 시각적 의존성 그래프 구축
  → 배치 1: 독립 엔티티 (최대 5개 동시 — ThreadPoolExecutor)
  → 배치 2: 의존 엔티티 (선행 이미지를 참조로 포함)

스타일 규칙 (v2 프롬프트):
  - 인물: 흰 배경, 프로필 사진, 상반신, 실사
  - 배경: 인물 없는 설정샷 (씬 참조에는 미사용)
  - 소품: 흰 배경 제품 사진

의존성 규칙:
  - 인물↔인물 (혈연/외모): 선행 이미지 참조
  - 인물↔소품 (착용): 선행 이미지 참조
  - 배경↔배경 (같은 장소 시간대): 선행 이미지 참조
  - 인물↔배경: 무관 (참조 불필요)
```

### 3.3 씬 이미지 생성

```
1단계: T2I 프롬프트 변환 (GPT-5.5)
  - 한국어 씬 설명 → 영어 T2I 프롬프트
  - 앵글/색감 없이 순수 시각 묘사만

2단계: 원본 이미지 생성 (Gemini T2I)
  - Gemini API에 구조화된 parts 전달:
    [SCENE DESCRIPTION] → [WORLD CONTEXT] →
    [CHARACTER: 이름] + 이미지 → [PREVIOUS SCENE] + 이미지
  - 배경 참조 이미지는 넣지 않음
  - 같은 배경의 이전 씬 이미지를 연속성 참조로 사용

3단계: 변형 A/B 생성 (Gemini i2i)
  - LLM이 씬에 적합한 변형 자동 추천 (앵글/색감/없음)
  - 앵글: PIL 카메라 다이어그램 + 프롬프트 → i2i
  - 색감: 프롬프트만 → i2i
  - 둘 다 필요하면: 앵글 먼저 → 결과에 색감 적용

동시 생성:
  - 같은 배경 씬 → 순차 (이전 씬 참조 필요)
  - 독립 씬 → 동시 (max_concurrent_image_gen 스레드)
```

### 3.4 Content Moderation 처리

```
Gemini 거절 시 3단계 재시도:
  1차: 영화 프리비즈 (촬영 전 컨셉아트로 프레이밍)
  2차: 영화 포스터 (감정/분위기 중심 키 비주얼)
  3차: 직후 정적 장면 (액션 직후 정적 순간)

- GPT-5.5로 프롬프트 재작성 → 재시도
- 테스트 결과: 15/15 (100%) 성공
- 사용된 전략이 ImageAsset에 기록됨
```

### 3.5 웹북 + PDF 출력

```
GPT-5.5 웹북 패키지 생성
  → 시나리오 1편 → 웹북 4~5편 × 섹션 8~10개
  → 각 섹션: 제목 + 오프닝 텍스트 + 이미지 + 캡션 + 클로징 텍스트

fpdf2 PDF 렌더링
  → 399.685pt 폭, long-page 포맷
  → 한글 폰트 (AppleSDGothicNeo)
  → 텍스트 + 이미지 인터리빙
```

---

## 4. 품질 검증

| 검증 | 방법 |
|------|------|
| 이미지 품질 | GPT-5.5 Vision (score 0-100, 60 미만 자동 needs_fix) |
| PDF 품질 | GPT-5.5 Vision (텍스트 가독성, 이미지 배치, 레이아웃) |
| 코드 품질 | Codex 자동 리뷰 (git commit 후 hook) |

---

## 5. 추적 시스템 (Opik 호환)

### GenerationTrace — T2I 호출별
- 시도 번호, 사용된 프롬프트/버전, 모델명
- 성공/거절/에러, 거절 사유, 카테고리
- 수정 전략 (film_previs/movie_poster/aftermath)

### OperationLog — 모든 파이프라인 작업
- 모듈명 + 버전, 프롬프트 이름 + 해시
- 입출력 요약, 소요 시간, 토큰 사용량

### PipelineProgress — 실시간 진행률
- UI에서 3초 폴링으로 표시
- 단계별: 분석 → 이미지 → 웹북 → PDF

---

## 6. 사용자 기능

### 인증/권한
- admin: 시스템 전체 + 모든 프로젝트
- creator: 자신의 프로젝트만
- 세션 기반 쿠키 (bcrypt, 24시간 TTL)

### 프로젝트 관리
- CRUD + 멤버 관리 (owner/member)
- JSON export/import (UUID 재매핑)
- 활동 로그 (모든 변화 기록)

### 편집 기능
- 엔티티: 이름, 설명, 시각 특성 편집
- 씬 스틸: 원본 설명 + T2I 프롬프트 각각 편집
- 참조 이미지: 다중 생성, 업로드, 대표 선택
- 씬 이미지: 다중 생성, 원본/A/B 대표 선택
- 앵글 편집: Three.js 3D 에디터 (수평/수직/줌)
- 색감 편집: 프리셋 (석양/야간/네온/안개) + 커스텀
- 프로젝트별 T2I 변환 프롬프트 오버라이드

### 이미지 선택
- 원본 이미지 선택 (여러 장 중)
- PDF 대표 이미지 선택 (원본/A/B 중)
- 초기 기본값: LLM 추천 = 대표

---

## 7. 모듈 버전 현황

| 모듈 | 버전 | 프롬프트 |
|------|------|---------|
| entity_extractor | 1.2.0 | entity_extraction/v7 |
| scene_still_extractor | 1.0.0 | scene_stills/v2 |
| t2i_prompt_composer | 1.0.0 | t2i_composer/v1 |
| reference_image_generator | 1.2.0 | reference_image/v2 |
| scene_image_generator | 1.3.0 | — |
| gemini_image_client | 1.1.0 | — |
| gemini_i2i_editor | 1.0.0 | — |
| prompt_sanitizer | 1.1.0 | prompt_sanitizer/v1 |
| variation_recommender | 1.0.0 | variation_recommender/v1 |
| image_validator | 1.0.0 | image_validation/v1 |
| webbook_generator | 1.1.0 | prototype_prompts/v5 |
| pdf_renderer | 1.1.0 | — |
| pdf_validator | 1.0.0 | pdf_validation/v1 |
| entity_dependency | 1.0.0 | — |
| generation_tracker | 1.0.0 | — |
| provenance | 1.0.0 | — |
| progress_tracker | 1.0.0 | — |
| image_service | 1.7.0 | — |

---

## 8. 프론트엔드 페이지

| 페이지 | 경로 | 기능 |
|--------|------|------|
| 로그인 | /login | 다크 테마 중앙 카드 |
| 대시보드 | / | 프로젝트 카드 그리드 + 생성 |
| 프로젝트 상세 | /projects/:id | 개요/멤버/활동 탭 |
| 에피소드 목록 | /projects/:id/episodes | PDF 업로드, 분석 시작, 진행률 |
| 에피소드 상세 | /projects/:id/episodes/:eid | 씬 스틸 + 엔티티 + 변형 카드 뷰 |
| 엔티티 | /projects/:id/entities | 카드 그리드, 관계, 이미지 갤러리 |
| 이미지 리뷰 | /projects/:id/images | 필터, 리뷰, 대표 설정, 일괄 재생성 |
| 내보내기 | /projects/:id/export | 웹북 생성, PDF 렌더링, 다운로드 |
| Admin 사용자 | /admin/users | 사용자 CRUD |
| Admin 로그 | /admin/activity | 전체 활동 로그 |

---

## 9. 실행 방법

```bash
# PostgreSQL
docker compose up -d

# 백엔드
cd backend && .venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

# 프론트엔드
cd frontend && npm run dev -- --host 0.0.0.0

# 로그인: admin / admin123
```

---

## 10. 핵심 설계 원칙

1. **모든 프롬프트 외부 파일** — 코드에 하드코딩 없음, 버전별 관리
2. **모든 문자열 i18n** — 한국어 우선, 영어 준비
3. **코드-프롬프트 추적** — 이미지마다 생성 시 코드 버전 + 프롬프트 버전 기록
4. **모듈 교체 가능** — LLM 클라이언트, 이미지 생성기 모두 인터페이스 분리
5. **DB 절대 삭제 금지** — 테스트는 임시 DB 사용 (conftest.py)
6. **시각적 관계만** — 서사적 관계는 추출/참조하지 않음
7. **동시 생성** — 의존성 없는 엔티티/씬은 병렬 (env 설정 가능)