# 파이프라인 v3 — 아웃룩 시스템 + N개 변형 + I2I 통합

## 날짜: 2026-03-18

---

## A. 요소 처리 변경

### A1. 인물 참조 이미지 → 얼굴만
- T2I 프롬프트에 "white background, passport photo style, face only, no body" 추가
- 기존: 전신 프로필 → 변경: 증명사진 스타일 얼굴만
- 프롬프트는 외부 파일로 관리 (하드코딩 금지)

### A2. 배경 참조 이미지 → 배경만
- T2I 프롬프트에 "no people, no vehicles, no objects, empty background only" 추가
- 사람/탈것/물체 완전 제거

### A3. 물체 참조 이미지 → 오브젝트만
- T2I 프롬프트에 "isolated object on neutral background, no people, no background" 추가
- 베어메탈 형태, 물체 자체만

### A4. 아웃룩 시스템 (신규)

**DB 구조:**
```
entity_canon (entity_type='outlook')
  - name: "군복", "일상복", "수트" 등
  - description: 시각적 설명
  - t2i_prompt: 아웃룩 자체 T2I

character_outlook (신규 조인 테이블)
  - id (PK)
  - character_id (FK → entity_canon)
  - outlook_id (FK → entity_canon)
  - project_id (FK)
  - created_at
```

**생성 시점:** 씬 상세 분석 시 Gemini가 자동 감지
- 씬 분석 프롬프트에 "이 씬에서 각 인물이 입고 있는 의상/아웃룩을 식별하세요" 추가
- 이전에 생성된 아웃룩 목록을 컨텍스트로 전달
- 새 아웃룩이면 생성, 기존 아웃룩이면 재사용
- 여러 인물이 같은 아웃룩 공유 가능 (유니폼 등)

**아웃룩 병합 (이미지 생성 전 필수 단계):**
- 모든 씬 분석 완료 후, 이미지 생성 전에 LLM으로 중복 아웃룩 병합
- 병렬 씬 분석에서 "군복"/"전투복"/"택티컬 유니폼" 같이 동일 아웃룩이 다른 이름으로 생성됨
- LLM에게 전체 아웃룩 목록을 보내서 병합 그룹 판단
- 병합: character_outlook 참조 이전 + 씬 T2I 프롬프트 내 이름 일괄 치환 + 중복 삭제

**인물+아웃룩 합성 이미지 (캐시 구조):**
- 씬 이미지 생성 전: 해당 씬에 등장하는 인물+아웃룩 조합마다 풀바디 샷 생성
- 캐시: 이미 같은 조합 이미지가 있으면 재사용 (대표 이미지)
- 없으면 생성: 인물 얼굴 참조 + 아웃룩 설명 → 전신 이미지
- 이 합성 이미지가 씬 T2I의 참조 이미지로 사용됨
- 요소 UI에 별도 탭으로 표시 (소품 다음, 다른 색상)

### A5. T2I 마커 형식 변경
- 기존: `[[동녘]]`
- 변경: `[[동녘]+[군복]]` (인물+아웃룩)
- 배경: `[장소: 설명]` (변경 없음)
- 물체: `[[물체]]` (변경 없음)

---

## B. 씬 처리 변경

### B1. N개 원본 T2I 프롬프트 생성
- 환경변수: `SCENE_VARIATION_COUNT=3` (기본값)
- 씬 분석 시 Gemini에게 N개의 서로 다른 해석으로 T2I 프롬프트 생성 요청
  - 예: 인물 중심, 상황 중심, 분위기 중심
  - 각각 주제 라벨 + T2I 프롬프트

### B2. 이미지 생성 파이프라인
```
1. N개 원본 T2I → N개 이미지 생성 (병렬)
2. GPT LVM 검증 → 문제 있으면 재생성 (각각)
3. N개 검증된 원본 → 각각 GPT LVM이 앵글+색감 추천
4. N개 I2I 변형 생성 (앵글+색감 동시 적용, 한쪽만 적용은 정말 좋을 때만)
5. 총 2N개 이미지 (N 원본 + N 변형)
6. GPT LVM이 2N개 중 대표 이미지 1개 선택
```

### B3. 이미지 계보 (Image Lineage)
- `ImageAsset.parent_image_id` (FK → self)
- 링크드 리스트: 원본 → 검증수정본 → 변형 → 수동편집본
- UI에서 이력 추적 가능

### B4. I2I 통합
- 앵글+색감을 한번의 I2I 호출로 처리
- 모듈 분리: 나중에 순차 처리로 변경 가능하게
- `GeminiI2IEditor.edit_angle_and_color_combined()`

### B5. UI 변경

**씬 카드:**
- 원본 시나리오 세그먼트 표시 (앞뒤 100자 포함)
- N개 원본 + N개 변형 = 2N개 이미지 그리드
- 각 이미지에 주제 라벨 표시
- 대표 이미지 플래그 표시

**이미지 클릭 모달:**
- 클릭 → 큰 이미지 + 앵글 슬라이더 + 색감 입력 동시 표시
- "적용" 클릭 → I2I 생성 → 새 변형 이미지 추가
- 생성 중 로딩 표시

**요소 탭:**
- 인물 / 배경 / 소품 / 아웃룩(별도 색상) 탭
- 아웃룩 탭: 인물+아웃룩 합성 이미지 표시
- 프롬프트 표시 + 수정 + 재생성 가능

---

## 파일 변경 목록

### DB / 모델
- `project.py` — CharacterOutlook 모델 추가, ImageAsset에 parent_image_id 추가
- DB 마이그레이션 — character_outlook 테이블, parent_image_id 컬럼

### 설정
- `config.py` — `scene_variation_count: int = 3`

### 프롬프트 (외부 파일, 하드코딩 금지)
- `prompts/_base/entity_extractor_v2/{version}/` — 참조 이미지 타입별 프롬프트
- `prompts/_base/scene_extractor_v2/{version}/turn_scene_detail.md` — 아웃룩 감지 + N개 T2I 추가
- `prompts/_base/lvm_prompts/{version}/` — N개 중 대표 선택 프롬프트

### 백엔드
- `scene_extractor_v2.py` — 아웃룩 감지, N개 T2I 반환
- `outlook_merger.py` (신규) — LLM 기반 아웃룩 중복 병합
- `analysis_service.py` — 씬 분석 후 아웃룩 병합 단계 추가
- `image_service.py` — 인물+아웃룩 합성 캐시, N개 생성+검증+변형+선택
- `ref_image_pipeline.py` — 타입별 프롬프트 분기
- `gemini_i2i_editor.py` — angle+color 통합 메서드
- API — 아웃룩 CRUD, 인물+아웃룩 합성 이미지

### 프론트엔드
- `EpisodeDetail.tsx` — 시나리오 세그먼트 표시, 아웃룩 탭
- `SceneVariationCard.tsx` — 2N개 이미지 그리드, 이미지 클릭 모달 통합
- `AngleEditor.tsx` — 색감 입력 통합

---

## 개발 순서 (Phase)

### Phase 1: DB + 모델
- CharacterOutlook 테이블
- ImageAsset.parent_image_id
- config: scene_variation_count

### Phase 2: 요소 참조 이미지 프롬프트 (A1~A3)
- 타입별 프롬프트 외부 파일
- ref_image_pipeline 수정

### Phase 3: 아웃룩 시스템 (A4)
- 씬 분석 프롬프트에 아웃룩 감지 추가
- 아웃룩 DB 저장 + character_outlook 연결
- 인물+아웃룩 합성 이미지 캐시

### Phase 3.5: 아웃룩 병합 (A4 후처리)
- 모든 씬 분석 완료 후, 이미지 생성 전에 실행
- 병렬 씬 분석에서 동일 아웃룩이 다른 이름으로 생성될 수 있음
  - 예: "군복", "전투복", "택티컬 유니폼" → 하나로 병합
- LLM에게 전체 아웃룩 목록 + 설명을 보내서 병합 그룹 판단
  - 입력: 전체 아웃룩 목록 [{name, description, linked_characters}]
  - 출력: 병합 그룹 [{keep_name, merge_names[], reason}]
- 병합 실행: merge 대상 아웃룩의 character_outlook 참조를 keep 대상으로 이전, merge 대상 삭제
- 씬 T2I 프롬프트 내 아웃룩 이름도 일괄 치환
- 프롬프트: `prompts/_base/outlook_merger/{version}/merge_prompt.md` (외부 파일)

### Phase 4: T2I 마커 변경 (A5)
- [[인물]+[아웃룩]] 형식
- 씬 T2I 프롬프트 생성 시 자동 적용

### Phase 5: N개 변형 씬 (B1~B2)
- 씬 분석: N개 T2I 프롬프트 반환
- 이미지 생성: N 원본 + N 변형 = 2N
- GPT 대표 선택

### Phase 6: I2I 통합 (B4)
- angle+color 통합 메서드
- 모듈 분리

### Phase 7: UI (B5)
- 시나리오 세그먼트 표시
- 2N개 이미지 그리드
- 이미지 클릭 → 앵글+색감 통합 모달
- 아웃룩 탭
- 생성 중 표시

### Phase 8: 테스팅 + 코드리뷰