# 세션 요약 — 2026-03-21

## 완료된 작업

### 1. LiteLLM + Opik 통합 ✅
- `llm_client.py` — LiteLLM Router (Gemini 5키 + OpenAI), Opik Cloud 자동 추적
- 12개 텍스트 LLM 단계 전부 `call_structured`/`call_text` 전환
- 기존 `GeminiTextClient`, `OpenAIClient` 직접 호출 제거 (이미지 경로 제외)
- GPT Vision 호출 (`_select_and_recommend_angle`, `_select_final_best`)은 아직 raw urllib 유지

### 2. Entity Extractor v3 ✅
- 멀티턴 세션 제거 → 독립 4단계 (Step1 스타일+이름 → Step2a GPT리뷰 → Step2b GPT상세 → Step3 T2I 병렬)
- 각 단계 체크포인트 저장/resume
- entity_extractor_v2.py 유지 (롤백용)

### 3. 프롬프트 개선 ✅
- v7 system.md — visible_entities 물리적 존재 판단 강화 (목소리/원격조종/상상/대사 제외)
- 아웃룩 프롬프트 v3 — 의상 연속성 + 물리적 등장 규칙
- 참조 이미지 라벨에 캐릭터 구별 특징 (visual_anchor_traits)

### 4. 교차 모델 검증기 ✅
- `scene_validator.py` — GPT↔Gemini 교차 검증
- 씬 분석 후 자동 실행 (scene_detail과 분리)
- 비물리적 엔티티 자동 제거 + T2I 마커 정리

### 5. 프롬프트 DB 관리 ✅
- `prompt_template` 테이블 — 114개 파일 이관
- `prompt_loader.py` — DB 우선, 파일 fallback
- CRUD API 7개 + 프롬프트 관리 UI (`/prompts`)

### 6. 파이프라인 게이트 ✅
- `pipeline_gate.py` — 모든 단계 전환 100% 완성 검증
- DB + 파일 존재 동시 확인
- API + 서비스 이중 게이트
- 단건 API에도 게이트 적용

### 7. 파이프라인 Step 프레임워크 ✅
- `step_manifest.py` — 16개 step DAG 정의
- `step_runner.py` — 베이스 클래스 (게이트/체크포인트/무효화/upsert)
- `step_run` DB 테이블
- 14개 StepRunner 서브클래스 (분석 10 + 이미지 4)
- `steps.py` API — 전체 상태 조회, 결과 조회, 단계 실행
- `PipelineStepsPanel.tsx` — UI 16단계 표시 + 실행/재실행 버튼

### 8. 이미지 관련 ✅
- PNG 메타데이터 임베딩 (`png_metadata.py`)
- 씬 의존성 그래프에 `dependent_scene_id` 반영 (배치 순서 보장)
- `dependent_scenes` API 수정 (location 기반 → dependent_scene_id 기반)
- 아웃룩 중복 제거 (`outlook_dedup.py` — GPT 판별 + DB 병합)
- 인물 누락 방지 (아웃룩 배정 인물 T2I 강제 추가)
- 썸네일 크기 확대 (200px) + 생성 시간/fal.ai 배지 표시
- 이미지 모달: 이미지별 참조 요소 + 원본 T2I + 최종 프롬프트 표시
- 앵글 편집 fal.ai 전용 전환 (색감 편집 제거)

### 9. UI 개선 ✅
- `GenerationStatusPanel` — 파이프라인 3단계 진행률 바
- `LLMConfigPanel` — 단계별 모델 선택 테이블
- `ImageGalleryModal` — 이미지별 프롬프트/참조 요소/배경 표시
- `PipelineStepsPanel` — 16단계 DAG 상태 + 실행/재실행

### 10. 체크포인트/Resume ✅
- `ImageCheckpointManager` — 참조/씬 이미지 원자적 체크포인트
- 모든 fan-out 단계 증분 체크포인트
- resume 시 파일 존재 확인 (DB만 신뢰 안 함)
- 참조 실패 시 합성 자동 차단

## 미완료 / 향후 작업

### 높은 우선순위
1. **GPT Vision 호출 LiteLLM 전환** — `_select_and_recommend_angle`, `_select_final_best`, ref/scene validation이 아직 raw urllib
2. **prompt_loader 파이프라인 연결** — 각 모듈의 `_load_prompt()`를 `prompt_loader.load_prompt()`로 교체
3. **기존 `run_analysis` → StepRunner 래퍼** — 내부적으로 step 순차 호출
4. **기존 `generate_images` → StepRunner 래퍼** — 동일
5. **config key 마이그레이션** — `entity_detail` vs `entity_t2i` vs `entity_detail_batch`

### 중간 우선순위
6. **step 실행이 백그라운드 스레드** — 현재 동기 실행, 긴 단계는 타임아웃
7. **webbook_generator LLM 호출** — PIPELINE_STEPS 미등록
8. **style_rules_generator LLM 호출** — PIPELINE_STEPS 미등록
9. **프론트엔드 에러 처리 보강** — 여러 catch {} 블록
10. **권한 체크** — 프롬프트/step API에 require_admin

### 낮은 우선순위
11. **Opik 병렬 span 전파** — ThreadPoolExecutor에서 `current_span_data` 명시 전달
12. **VariationRecommender, T2IPromptComposer** — LiteLLM 미전환
13. **outlook_merger** — LiteLLM 미전환
14. **프론트엔드 i18n 통일** — 하드코딩 한국어 → t() 함수

## 생성된 파일 목록

### 백엔드 신규
```
app/core/pipeline_gate.py          — 파이프라인 게이트
app/core/step_manifest.py          — Step DAG 정의
app/core/step_runner.py            — StepRunner 베이스 클래스
app/core/steps/__init__.py
app/core/steps/analysis_steps.py   — 분석 10개 StepRunner
app/core/steps/image_steps.py      — 이미지 4개 StepRunner
app/api/v1/steps.py                — Step API
app/api/v1/prompts.py              — 프롬프트 CRUD API
app/modules/llm/llm_client.py      — LiteLLM + Opik 통합
app/modules/pipeline/entity_extractor_v3.py — 독립 4단계
app/modules/pipeline/scene_validator.py     — 교차 검증기
app/modules/pipeline/outlook_dedup.py       — 아웃룩 중복 제거
app/modules/image_checkpoint.py    — 이미지 체크포인트
app/modules/prompt_loader.py       — DB+파일 프롬프트 로더
app/modules/png_metadata.py        — PNG 메타데이터 임베딩
```

### 프론트엔드 신규
```
src/components/shared/PipelineStepsPanel.tsx  — 16단계 UI
src/components/shared/GenerationStatusPanel.tsx — 진행률 바
src/components/shared/LLMConfigPanel.tsx       — 모델 선택
src/pages/PromptManager.tsx                    — 프롬프트 관리
```

### 프롬프트 신규
```
prompts/_base/scene_extractor_v2/7.202603210900/  — v7 visible_entities 강화
prompts/_base/outlook_extractor/3.202603202200/   — 물리적 등장 규칙
prompts/_base/scene_extractor_v2/6.202603202200/  — GPT strict schema
```

### 문서
```
docs/architecture-current.md       — 현재 아키텍처 문서
docs/refactoring-plan.md           — 리팩토링 플랜 v1
docs/pipeline-refactoring-v2.md    — 17단계 설계 v2
docs/pipeline-refactoring-v3.md    — DAG 기반 최종 설계 v3
docs/session-summary-20260321.md   — 이 문서
```

### DB 테이블 추가
```
step_run           — 단계별 실행 상태/결과
prompt_template    — 프롬프트 버전 관리
project_settings.llm_config_json — 프로젝트별 LLM 설정
```

## 교차 코드 리뷰 이력

총 **20회+** Claude + Codex 교차 리뷰 수행:
- entity_extractor_v3 (2회)
- LLM 마이그레이션 (2회)
- 프롬프트 DB (2회)
- 파이프라인 게이트 (4회)
- 씬 검증기 (2회)
- 아웃룩 중복 제거 (2회)
- 리팩토링 플랜 (2회)
- Phase 0 step 프레임워크 (1회)
- Phase 1 분석 단계 (2회)
- Phase 2 이미지 단계 (2회)

## 테스트 프로젝트

| 프로젝트 | 상태 |
|----------|------|
| SRD v3 | 분석+이미지 완료 (기준) |
| SRD v4 | 분석+이미지 완료 (의상 연속성) |
| SRD v5 GPT | 분석+이미지 부분 (API 429) |
| SRD v6 LiteLLM | 분석+이미지 완료 (LiteLLM 전환) |
| SRD v7 | 분석+이미지 완료 (최종 리팩토링) |
| 미아 v1 | 분석+이미지 완료 |
| 파과 v1 | 분석+이미지 완료 (161씬) |