# TheRoad Scene 프로젝트 대화 히스토리 및 현재 진행 상태

작성일: 2026-03-14  
정리 범위: 현재 대화에서 확정된 기획, 실험, 구현, 프로토타입 상태

## 1. 프로젝트 목표 요약

이 프로젝트의 목적은 영화/드라마 스크린플레이를 분석해서 다음 흐름을 만드는 것이다.

1. 원본 시나리오 PDF를 분석한다.
2. 인물, 배경, 중요 물체, 관계, 씬 스틸 후보를 추출한다.
3. 추출된 요소와 관계를 기반으로 연속성이 유지되는 장면 이미지를 생성한다.
4. 시나리오를 바로 옮긴 것이 아니라, 웹북/웹소설 형태의 장문 텍스트로 재구성한다.
5. 생성된 텍스트와 이미지를 적절한 위치에 배치해 PDF/EPUB 같은 결과물을 만든다.

핵심 요구는 다음이었다.

- 인물/배경/물체의 일관성 유지
- 시리즈 연속성 유지
- 사람이 중간에 프롬프트, 카메라 앵글, 조도, 색감 등을 수정 가능
- LLM/T2I/I2I/LoRA 모듈을 교체 가능한 구조
- 프롬프트/코드/DB/결과물 버전 관리
- export/import 쉬운 구조
- 내부용이지만 실제 제작 흐름에 쓸 수 있는 수준의 운영 프로토타입

## 2. 초기 기획 단계에서 확정된 큰 방향

### 2.1 시스템 구조 문서화

초기에는 기획서를 Markdown + Mermaid 형태로 정리했다.

주요 문서:

- [the-road-scene-internal-plan.md](/Users/jedi/Documents/TheRoad-Scene/docs/the-road-scene-internal-plan.md)

이 문서에는 다음 내용이 계속 보강되었다.

- 모듈형 파이프라인 구조
- Admin / Creator 역할 분리
- 시나리오 분석, 씬 분석, 이미지 생성, 출력 렌더링 흐름
- Opik / LiteLLM / 자체 버전 관리 전략
- SQLite 중심의 프로젝트 단위 저장 구조

### 2.2 continuity 모델

대화 중 반복적으로 확정된 설계 원칙은 아래와 같다.

- 인물만이 아니라 배경(location), 중요 물체(prop)도 모두 variant를 가져야 한다.
- 저장 구조는 공통적으로 `canon -> variant -> snapshot` 모델로 간다.
- 관계는 단순 2항 링크가 아니라 별도 관계 레이어를 둔다.
- 시리즈 연계 시 이전 에피소드의 승인 이미지/승인 상태를 다음 분석에 메모리처럼 주입한다.

이 방향에 따라 기획서에는 다음 개념이 반영되었다.

- `entity_canon`
- `entity_variant`
- `scene_entity_snapshot`
- `entity_reference_image`
- `relation_fact`
- `relation_participant`
- `scene_relation_snapshot`

### 2.3 역할 모델

역할은 다음 둘로 확정되었다.

- `admin`
  - 시스템 설정
  - LLM 키 / 모델 선택
  - 중요 프롬프트 관리
- `creator`
  - 프로젝트 생성
  - 시나리오 업로드
  - 중간 수동 조정
  - PDF/EPUB 생성

## 3. 모델/서비스 관련 의사결정

### 3.1 텍스트 처리

현재 텍스트 처리 기본 모델은 `GPT-5.4`이다.

적용 대상:

- 엔티티 추출
- 씬 스틸 추출
- 세계관/시대 가이드 생성
- 웹북/소설형 패키지 생성

### 3.2 이미지 처리

대화 중 이미지 생성 쪽은 여러 방향이 논의되었다.

- 카메라 각도 변경: `fal-ai/qwen-image-edit-2511-multiple-angles`
- 화풍 LoRA 학습/적용:
  - `fal-ai/flux-kontext-trainer`
  - `fal-ai/flux-kontext-lora`

다만 현재 **실제 구현 프로토타입**에서는 화풍 LoRA 단계는 제외했고, 이미지 생성은 아래 모델로 통일했다.

- `gemini-3.1-flash-image-preview`

즉, 현재 코드 구현 기준은:

- 텍스트: `GPT-5.4`
- 이미지: `Gemini 3.1 Flash Image Preview`

## 4. 중간 실험 및 벤치마크에서 나온 결론

### 4.1 엔티티/씬 추출

처음에는 chunking과 fulltext를 비교했지만, 현재는 `fulltext-only`가 더 적합하다고 결론 내렸다.

주요 실험 스크립트/결과:

- [extract_entities.py](/Users/jedi/Documents/TheRoad-Scene/screenplay/extract_entities.py)
- [extract_scene_stills.py](/Users/jedi/Documents/TheRoad-Scene/screenplay/extract_scene_stills.py)
- [benchmark_series_entities.py](/Users/jedi/Documents/TheRoad-Scene/screenplay/benchmark_series_entities.py)
- [comparison_report.md](/Users/jedi/Documents/TheRoad-Scene/screenplay/benchmark_results_full/comparison_report.md)
- [comparison_report.md](/Users/jedi/Documents/TheRoad-Scene/screenplay/scene_still_results_full_v2/comparison_report.md)

결론:

- 에피소드별 fulltext 처리 + prior memory 주입이 현재 구조상 가장 실용적
- chunked 방식은 이름/장소 분절과 canon 중복 가능성이 커서 제외
- GPT-5.4가 현재 기준 가장 안정적으로 구조화 추출됨

### 4.2 언어 유지

원본 스크린플레이 언어와 동일한 언어로 결과를 내도록 수정되었다.

예:

- 한국어 시나리오 -> 한국어 엔티티/씬/웹북 텍스트
- 일본어 시나리오 -> 일본어
- 영어 시나리오 -> 영어

## 5. 구현된 코드 흐름

### 5.1 엔티티 추출

스크립트:

- [extract_entities.py](/Users/jedi/Documents/TheRoad-Scene/screenplay/extract_entities.py)

특징:

- 구조화 JSON 출력
- relation fact 추출 포함
- SQLite 적재 옵션 포함
- 프롬프트 외부 분리 및 버전 관리

프롬프트 디렉터리:

- [manifest.json](/Users/jedi/Documents/TheRoad-Scene/screenplay/prompts/manifest.json)
- [versions](/Users/jedi/Documents/TheRoad-Scene/screenplay/prompts)

### 5.2 씬 스틸 추출

스크립트:

- [extract_scene_stills.py](/Users/jedi/Documents/TheRoad-Scene/screenplay/extract_scene_stills.py)

특징:

- fulltext 기반
- `still_frame_prompt`
- `camera`
- `lighting`
- `visible_entity_ids`
- 씬 헤딩 카탈로그 기반 스틸 배치

프롬프트 디렉터리:

- [manifest.json](/Users/jedi/Documents/TheRoad-Scene/screenplay/scene_still_prompts/manifest.json)
- [versions](/Users/jedi/Documents/TheRoad-Scene/screenplay/scene_still_prompts)

### 5.3 웹북 생성 프로토타입

주요 스크립트:

- [prototype_episode_novel.py](/Users/jedi/Documents/TheRoad-Scene/screenplay/prototype_episode_novel.py)

이 스크립트는 다음 순서로 동작한다.

1. 원본 시나리오 읽기
2. 엔티티/씬 추출 결과 사용
3. 세계관/시대 가이드 생성
4. 웹북 패키지 생성
5. 엔티티 참조 이미지 생성
6. 장면 이미지 생성
7. PDF 렌더링

프롬프트 디렉터리:

- [manifest.json](/Users/jedi/Documents/TheRoad-Scene/screenplay/prototype_prompts/manifest.json)
- 현재 활성 버전: `v5`

버전별 방향:

- `v2`: 1개 screenplay -> 여러 webbook episode
- `v3`: 중립 reference, 세계관 guardrail 강화
- `v4`: 텍스트 오버레이/모델시트 느낌 억제
- `v5`: 긴 웹북 분량, 이미지 밀도 증가, 모바일형 long-page PDF, 시대 일관성 강화

## 6. 프로토타입 진화 과정

### 6.1 초기 compact prototype

초기에는 `스크린플레이 1편 -> 짧은 mini novel` 형태였다.

관련 산출:

- [Soulride_episode1_prototype.pdf](/Users/jedi/Documents/TheRoad-Scene/prototype/episode_01/rendered/Soulride_episode1_prototype.pdf)

이 버전은 이후 폐기 방향이 확정되었다.

문제:

- 예제 웹북보다 너무 짧음
- 이미지 수 부족
- 결과물이 "연재형 웹북"보다는 "짧은 요약 소설"에 가까움

### 6.2 v4 단계

`webbook_episode_01_v4`는 다음 개선을 포함했다.

- 4개 웹북 에피소드 분할
- 12개 장면 이미지
- 좁지 않은 일반 PDF에서 long-form 쪽으로 이동 전 단계

관련 결과:

- [prototype_summary.json](/Users/jedi/Documents/TheRoad-Scene/prototype/webbook_episode_01_v4/metadata/prototype_summary.json)

### 6.3 v5 단계

사용자 피드백 후 현재 메인 프로토타입은 `v5`가 되었다.

사용자 피드백 핵심:

- 예제 `novelwithimage` PDF와 너무 다름
- 글이 너무 짧음
- 이미지가 적음
- 모두 랜드스케이프여야 함
- 시대/배경 일관성이 부족함

v5에서 바뀐 점:

- 웹북 한 편을 `폭 좁은 세로 long-page 1페이지`로 렌더링
- 편당 약 `7.1k~8.1k` 문자 수준으로 장문 확장
- 편당 `10장` 이미지
- 총 `4개 episode / 40개 still`
- 모든 장면 이미지를 `1600x900`로 통일
- 기준 레퍼런스 이미지를 더 많이 생성

## 7. 현재 메인 산출물

현재 기준 메인 산출물은 `prototype/webbook_episode_01_v5`이다.

### 7.1 분석 결과

- [entities.json](/Users/jedi/Documents/TheRoad-Scene/prototype/webbook_episode_01_v5/analysis/entities.json)
- [scene_stills.json](/Users/jedi/Documents/TheRoad-Scene/prototype/webbook_episode_01_v5/analysis/scene_stills.json)

### 7.2 메타데이터

- [world_guide.json](/Users/jedi/Documents/TheRoad-Scene/prototype/webbook_episode_01_v5/metadata/world_guide.json)
- [webbook_package.json](/Users/jedi/Documents/TheRoad-Scene/prototype/webbook_episode_01_v5/metadata/webbook_package.json)
- [image_generation_manifest.json](/Users/jedi/Documents/TheRoad-Scene/prototype/webbook_episode_01_v5/metadata/image_generation_manifest.json)
- [prototype_summary.json](/Users/jedi/Documents/TheRoad-Scene/prototype/webbook_episode_01_v5/metadata/prototype_summary.json)

### 7.3 결과 PDF

- [web_episode_01_깨어_있는_더미.pdf](/Users/jedi/Documents/TheRoad-Scene/prototype/webbook_episode_01_v5/rendered/web_episode_01_깨어_있는_더미.pdf)
- [web_episode_02_풀려난_포승줄.pdf](/Users/jedi/Documents/TheRoad-Scene/prototype/webbook_episode_01_v5/rendered/web_episode_02_풀려난_포승줄.pdf)
- [web_episode_03_네잎클로버.pdf](/Users/jedi/Documents/TheRoad-Scene/prototype/webbook_episode_01_v5/rendered/web_episode_03_네잎클로버.pdf)
- [web_episode_04_당첨자들.pdf](/Users/jedi/Documents/TheRoad-Scene/prototype/webbook_episode_01_v5/rendered/web_episode_04_당첨자들.pdf)

### 7.4 현재 수치

`v5` 결과 기준:

- 웹북 에피소드 수: 4
- 에피소드당 이미지 섹션 수: 10
- 총 장면 이미지 수: 40
- 총 참조 엔티티 수: 44
- PDF 형태: 1페이지 long-page
- 폭: 약 `399.69 pt`

편별 글자 수:

- episode 1: 약 8114자
- episode 2: 약 7434자
- episode 3: 약 7253자
- episode 4: 약 7185자

## 8. 예제 웹북 PDF와 비교한 현재 상태

비교 대상:

- [Soulride_e001__240124.pdf](/Users/jedi/Documents/TheRoad-Scene/novelwithimage/Soulride_e001__240124.pdf)
- [Soulride_e002__240124.pdf](/Users/jedi/Documents/TheRoad-Scene/novelwithimage/Soulride_e002__240124.pdf)
- [Soulride_e003__240124.pdf](/Users/jedi/Documents/TheRoad-Scene/novelwithimage/Soulride_e003__240124.pdf)

비교 결과:

### 예제 특징

- narrow-width long-page
- 한 편당 매우 긴 단일 페이지
- 편당 대략 7천~1만자
- 이미지 14~26장
- 텍스트 블록과 이미지가 촘촘하게 반복

### 현재 v5 특징

- narrow-width long-page 구조는 유사하게 맞춤
- 편당 글자 수는 예제 하한선 근처까지 도달
- 이미지 밀도는 늘었지만 예제보다 아직 적음
- 일부 장면은 시대감/장비 표현이 개선되었으나 특정 그룹에서 과장이 남음

## 9. 현재 남아 있는 문제

현재 남은 가장 큰 문제는 다음이다.

### 9.1 DR.NEX / 오리엔티스 과장 표현

일부 장면에서 아래 문제가 남는다.

- 전신 파워아머처럼 과장됨
- 현대/근미래 한국 기반 전술 장비보다 SF 장갑복에 가까워짐

이 문제를 줄이기 위해 코드에는 특수 가드레일이 추가되었다.

적용 파일:

- [prototype_episode_novel.py](/Users/jedi/Documents/TheRoad-Scene/screenplay/prototype_episode_novel.py)

관련 대상:

- `DR.NEX`
- `한치호`
- `은성`
- `서현`
- `오리엔티스`

하지만 **이미 생성된 v5 결과물에는 일부 컷이 여전히 남아 있을 수 있다.**

즉, 다음 run부터 더 나아질 기반은 들어갔지만, 문제 컷 선택 재생성 기능은 아직 붙지 않았다.

### 9.2 이미지 수

현재는 편당 10장이다.  
예제 상단값까지 가려면 12~16장 수준으로 더 늘려도 된다.

### 9.3 재생성 워크플로우 부재

현재는 전체 run은 UI에서 돌릴 수 있지만, 다음 기능은 아직 없다.

- `needs_fix` 장면만 선택 재생성
- 특정 entity reference만 재생성
- 특정 scene prompt만 수정 후 재실행

## 10. UI 프로토타입 상태

텍스트/이미지 생성 파이프라인을 감싸는 내부용 UI 프로토타입이 구현되었다.

### 10.1 주요 파일

- [app.py](/Users/jedi/Documents/TheRoad-Scene/prototype_ui/app.py)
- [README.md](/Users/jedi/Documents/TheRoad-Scene/prototype_ui/README.md)
- [index.html](/Users/jedi/Documents/TheRoad-Scene/prototype_ui/templates/index.html)
- [run_detail.html](/Users/jedi/Documents/TheRoad-Scene/prototype_ui/templates/run_detail.html)
- [styles.css](/Users/jedi/Documents/TheRoad-Scene/prototype_ui/static/styles.css)
- [prototype_ui.sqlite3](/Users/jedi/Documents/TheRoad-Scene/prototype_ui/prototype_ui.sqlite3)

### 10.2 현재 가능한 기능

- 기존 screenplay PDF 선택
- 새 PDF 업로드
- 현재 파이프라인 실행
- 기존 `prototype/*` 출력 자동 감지
- 결과 PDF 링크 제공
- 장면별 이미지 검수
- `pending / approved / needs_fix` 저장

### 10.3 실행 방법

문서:

- [README.md](/Users/jedi/Documents/TheRoad-Scene/prototype_ui/README.md)

명령:

```bash
python3 -m uvicorn prototype_ui.app:app --host 127.0.0.1 --port 8765
```

브라우저:

```text
http://127.0.0.1:8765
```

## 11. 현재 설치 의존성

현재 `requirements.txt`는 아래 의존성을 포함한다.

- `pypdf`
- `fpdf2`
- `Pillow`
- `fastapi`
- `uvicorn`
- `Jinja2`
- `python-multipart`

파일:

- [requirements.txt](/Users/jedi/Documents/TheRoad-Scene/screenplay/requirements.txt)

## 12. 구현/테스트 중 확인된 부가 사항

### 12.1 PDF 렌더링 폰트

한글 PDF 렌더링에는 아래 폰트를 사용 중이다.

- `/System/Library/Fonts/AppleSDGothicNeo.ttc`

### 12.2 프로젝트 저장 구조

현재 실 구현은 파일 기반 결과를 중심으로 하고 있다.

- 분석 JSON
- 메타 JSON
- 이미지 PNG
- 결과 PDF
- UI SQLite

기획상 최종 방향은 여전히 `프로젝트별 SQLite 중심 + assets 외부 저장`이다.

## 13. 다음 권장 작업

다음 우선순위는 아래 순서가 적절하다.

1. `needs_fix` 장면 선택 재생성 UI 추가
2. entity reference 재생성 UI 추가
3. `v5` 기준으로 part 2~6까지 순차 실행
4. 시리즈 continuity memory를 실제 UI run에도 연결
5. 최종적으로 EPUB 출력 추가

## 14. 한 줄 상태 요약

현재 프로젝트는 `스크린플레이 1편을 4개의 long-page 웹북 에피소드로 재구성하고, GPT-5.4 + Gemini 이미지 생성 기반으로 PDF까지 뽑아내는 내부용 프로토타입` 단계까지 와 있으며, `UI에서 실행/검수`도 가능한 상태다.  
다만 `장면 선택 재생성`과 `특정 캐릭터/세력의 과장된 SF 비주얼 억제`는 다음 단계에서 더 보완해야 한다.