# TheRoad Scene Lab

영화/드라마 시나리오를 분석하여 일러스트가 포함된 웹북(PDF)으로 변환하는 내부용 제작 시스템.

## 필요 사항

- Python 3.12+
- Node.js 18+
- Docker (PostgreSQL용)

## 시작하기

### 1. PostgreSQL 시작

```bash
docker compose up -d
```

PostgreSQL이 `localhost:5432`에서 실행됩니다.

### 2. 백엔드 설정

```bash
cd backend
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
# .env 파일에 API 키 설정
```

### 3. 백엔드 실행

```bash
cd backend
.venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```

- API 문서: http://localhost:8000/api/docs
- LAN 접근: `http://<LAN IP>:8000` (외부 기기에서 접속 시)
- 파이프라인 설명 페이지: `/pipeline_explained.html` (프론트 dev 서버)

### 4. 프론트엔드 실행

```bash
cd frontend
npm install
npm run dev
```

- UI: http://localhost:3000

### 5. 로그인

| 사용자명 | 비밀번호 | 역할 |
|----------|----------|------|
| admin | admin123 | 관리자 |
| creator | creator123 | 크리에이터 |

## 환경 변수

`.env` 파일에 설정:

```env
DATABASE_URL=postgresql://theroad:theroad_dev_2026@localhost:5432/theroad
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-5.4
GEMINI_API_KEY=AIza...
GEMINI_IMAGE_MODEL=gemini-3.1-flash-image-preview
```

## 파이프라인 흐름 (v4: beat→shot 기반)

```
시나리오 PDF 업로드
  → 텍스트 정리 (Gemini/GPT)
  → 씬 세그먼테이션 (정규식 + Gemini 분할)
  → 에피소드 요약 + 시각적 세계관 규칙
  → beat 추출 (씬별 상태 변화 단위)
  → shot 추출 → shot_validator → shot_selection (씬별 N개)
  → 인물/배경/소품 추출 → 요소 병합 → 요소 상세 → T2I 프롬프트
  → 씬 감독 (Gemini Pro) → 촬영 기법 (카메라/의상)
  → scene_consistency (씬 내 교차 샷 시각 일관성)
  → shot별 상세 (scene_detail) + 교차 검증
  → 참조 이미지 생성 (ref_image_gen, Gemini)
  → 씬 이미지 생성 (scene_image_pipeline, Gemini + fal.ai)
  → 이미지 품질 검증 (t2i_review, GPT Vision)
  → 웹북 PDF 렌더링 (fpdf2)
```

> 비전문가용 시각화: 백엔드 실행 후 `http://localhost:3000/pipeline_explained.html` 참조.

**자세한 아키텍처**: `docs/architecture/00-overview.md` ~ `07-prompt-versioning-policy.md`

## 프로젝트 구조

```
backend/          # FastAPI 백엔드
  app/
    api/v1/       # REST API 엔드포인트
    core/         # 설정, DB, 보안
    models/       # SQLAlchemy 모델
    modules/      # LLM 클라이언트, 이미지 생성, 분석 모듈
    services/     # 비즈니스 로직
    i18n/         # 한국어/영어 문자열
frontend/         # React + Vite + TypeScript
prompts/          # 외부 프롬프트 파일 (버전 관리)
projects/         # 프로젝트 에셋 (이미지, PDF)
docs/             # 설계 문서, 개발 로그
```

## 프로젝트 Export/Import

프로젝트 전체를 JSON으로 내보내고 가져올 수 있습니다:

```bash
# Export
GET /api/v1/projects/{id}/export  → project_bundle.json + assets.zip

# Import
POST /api/v1/projects/import  ← project_bundle.json + assets.zip
```

## 기술 스택

| 레이어 | 기술 |
|--------|------|
| 백엔드 | Python, FastAPI, SQLAlchemy |
| DB | PostgreSQL 17 |
| 프론트엔드 | React, Vite, TypeScript |
| LLM | OpenAI GPT-5.4, Google Gemini |
| 이미지 | Gemini 3.1 Flash Image Preview |
| PDF | fpdf2 |
| 배포 | Docker Compose |