# TheRoad Scene Lab

> **절대 규칙: LLM에 전달하는 데이터(시나리오 텍스트, 씬 텍스트 등)를 절대로 자르지 마라 ([:400], [:500] 등 금지). 어떤 경우에도 원문 전체를 전달할 것. 명시적 요청 전까지 예외 없음.**

> **절대 규칙 — 한국어 쓰는 법 (2026-08-26 지적).** 사용자에게 보내는 모든 글에 적용한다.
>
> 1. **없는 말을 만들지 마라.** 논문·실험실·고문서에나 나오는 한자어를 가져다 쓰지 않는다.
>    실제로 지적받은 것들: ~~양성 대조~~ · ~~즉사~~ · ~~회수~~ · ~~실증~~ · ~~폐기~~ · ~~산출~~ ·
>    ~~접수되다~~ · ~~파탄~~ · ~~관문~~ · ~~전량~~ · ~~정합성~~ · ~~사장님~~.
> 2. **막히면 두 가지 중 하나로 간다.**
>    - 영어 원어를 그대로 쓴다 — 문장은 한국어로. 예: "positive control 로 확인했다" ✕ →
>      **"고친 걸 일부러 다시 빼서 테스트가 잡는지 봤다"** ○, 또는 "regression 은 없다" ○
>    - 우리말로 **풀어서** 쓴다. 두 글자로 줄이지 말고 세 낱말로 늘린다.
> 3. **개발 용어는 원어 그대로.** 테스트(~~시험~~) · 리그레션(~~회귀~~) · 재시작(~~재기동~~) ·
>    수정안(~~수리안~~) · commit · push · branch · staged.
> 4. **가르는 법:** 그 말을 **소리 내어** 사람에게 설명한다고 생각해 본다.
>    입에서 안 나오면 안 쓴다. 보내기 직전에 문장의 동사·명사를 하나씩 훑는다.
>    짧게 줄이려는 욕심이 병의 뿌리다 — 길어져도 된다.

## 핵심 규칙

- **모델 분업 (2026-07-11 현행 — Gemini 원복 8c0719fe + 캐릭터 추출 Sol 재이관)**:
  - **Gemini 3.1 Pro** (`gemini-pro`): 확정·감독 계열 — beat/shot extract, shot_validator, scene_director, scene_detail, scene_consistency, entity_extract_location/prop, entity_t2i, 아웃룩 3단계
  - **GPT-5.6 Sol** (`gpt` alias, OPENAI_MODEL=gpt-5.6-sol): 분석 주력 37스텝 + **캐릭터 추출 3스텝**(entity_character_list, entity_all/extract_character — 2026-07-11 4회차 모델 비교 Claude+Codex 합의: 후보 회수율 Sol 우세)
  - **Gemini Flash** (`gemini-flash`, `gpt-mini` alias 매핑): 보조 — 씬 세그먼테이션, 요약, 필터, shot 선택, 번역
  - **Gemini 전용**: planning_doc_analysis+text_cleanup (`gemini-lite`, PDF multimodal) + 이미지 생성 (`gemini-3.1-flash-image-preview`) + VLM 이중 판정(canon GPT/Gemini 합산, indoor/outdoor judge)
  - **GPT LVM**: 이미지 검증, 비교 선택, 앵글 추천
- **모델 비교 판정 지식(2026-07-11, 4회차 전수+Codex 교차)**: Sol=회수율·구체 명명 우세 but beat/shot 과세분(+160%)·VE 핵심 배정 결함·요약 과손실 / Gemini Pro=감독·배정·실사용 연속성 우세. GPT 엔티티 출력은 후보 발굴용 — SOT 직승격 금지(dedupe 게이트 후속 과제). 근거 갤러리=scratchpad/forest_exp/model_compare_gpt_vs_gemini.html
- **요소 추출 3단계 분리**: 인물 → 배경 → 소품 (각각 별도 step)
- **요소 필터**: 저빈도(3씬 이하) 요소 LLM 필터링 → 제거 판단
- **아웃룩 3단계**: Phase1(목록) → Phase2(씬별 매핑) → Phase3(의상 정리/병합)
- **director_notes**: visual_world_rules에서 물리적 존재 판단 기준 추출 → beat_extract + shot_extract + scene_director에 전달
- **visible_entities**: LLM 의존 X, scene_director 확정 데이터에서 코드 자동 구축
- **VE 위반 검사**: scene_detail T2I 프롬프트에 VE 밖 엔티티 사용 시 retry + 강제 제거
- **요소 변형은 별도 EntityCanon** + RelationFact로 의존성 연결
- **기존 모듈 삭제 금지**: pipeline/ 디렉토리에 새 모듈로 대체
- **DB/프로젝트 파일 삭제 금지** (명시적 요청 제외)
- **프롬프트 파일 덮어쓰기 금지**: 새 버전 디렉토리로 관리
- **버전 형식**: `2.202603171200` (버전.YYYYMMDDHHmm)
- **시나리오 분석 시 청킹 금지**: 전문을 한 번에 전달
- **T2I 프롬프트**: 콘티형 단순함 (한 컷 = 한 문장, 인물 2~3명 최대)
- **T2I에서 복합 ID 금지**: LLM에게 C08O09 같은 복합 ID를 달라고 하지 말고, 인물/아웃룩 따로 받아서 코드에서 조합
- **작품 고유명사 코드/프롬프트에 넣지 말 것**: 어떤 시나리오에도 범용 적용
- **스타일 규칙**: LLM이 시나리오 분석 후 자동 생성 (프로젝트 단위)
- **scene_still sync는 UPSERT**: DELETE→INSERT 금지 (이미지 still_id 참조 보존)
- **이미지 자동 생성**: 마지막 N개 T2I + fal.ai 앵글 1개 (N = scene_variation_count, fal.ai는 `FAL_AI_ENABLED=true` 시만)
- **T2I 단일 스틸컷 원칙**: 하나의 t2i_prompt = 한 순간, 한 시공간만. 아래 3가지 고려:
  1. **인물 변형**: 변신/변형 캐릭터는 선택한 순간의 형태 ID만 사용 (변형 전이면 원본만, 후면 변형만)
  2. **서브씬**: 몽타주/회상/인터컷/꿈/평행액션 등 씬 안에 시공간이 다른 장면이 섞여 있으면 하나만 선택
  3. **전체 ≠ 한 컷**: scene_director가 씬에 배정한 전체 인물을 한 스틸컷에 다 넣을 필요 없음

## 개발 사이클

설계 → 개발 → 리뷰(codex) → 테스팅 → 수정 → 리뷰(codex) → E2E 테스팅(UI) → 분석 → 수정 → 리뷰(codex) → 디플로이

## 배포 시퀀스

- **production deploy**: `alembic upgrade head` → backend startup (순서 엄격).
- startup 시 `_migrations` 검증이 fail-fast 모드 — alembic 미실행 / schema drift 시 부팅 abort + RuntimeError ("Run `alembic upgrade head` manually before retry"). 이전 silent skip 패턴은 problems.md #2 로 제거됨.

## 완료된 Phase

- Phase 1: gemini_text_client.py ✅
- Phase 2: entity_extractor_v2.py (4턴 요소 추출) ✅
- Phase 3: scene_extractor_v2.py (정규식 세그먼테이션 + Gemini 분할 + 멀티턴 상세) ✅
- Pipeline v3: 26단계 리팩토링 ✅ (feat/pipeline-v3 브랜치)
- Pipeline v4: beat→shot 기반 파이프라인 ✅ (feat/pipeline-v4-beat-shot 브랜치)

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

```
텍스트 정리 → 씬 세그먼테이션 → 에피소드 요약 → 시각적 세계관 규칙
  → 씬 저장(원본, scene_split 제거) → 씬별 요약(병렬)
  → beat 추출(gemini-pro, 번들 병렬) → shot 추출(gemini-pro, 번들 병렬)
  → 인물 추출(gpt, shot 기반 1회) → 배경 추출(gpt, 체이닝) → 소품 추출(gpt, 체이닝)
  → 요소 병합 → 요소 상세 → T2I 프롬프트
  → shot 선택(gpt-mini, 씬별 최대 3개) → 씬 감독(gemini-pro)
  → shot별 촬영 기법(gemini-pro, 2개/shot) → shot 연관 분석(gpt)
  → 아웃룩 3단계 → shot별 상세(gpt, 병렬) → 교차 검증
  → 이미지 단계(참조→합성→씬 이미지)
```

### v4 핵심 변경
- **scene_split 제거**: 원본 씬 그대로 보존
- **beat→shot 계층**: 씬 → beat(상태변화) → shot(스틸컷) → selected shots
- **shot 단위 DB**: scene_still = 1 shot, scene_index로 씬 그룹핑
- **shot별 T2I**: 각 shot에 technique_1 + technique_2 = 2개 T2I variation
- **shot_dependency**: 앞쪽 연관 shot (배경 참조 + 인물 참조)
- **fal.ai**: `FAL_AI_ENABLED` env로 비활성화 가능 (기본 false)
- **retry 로직**: beat/shot/cinematography/dependency에 max_retry=2