# TheRoad Scene Lab — 기능 개선 & 개발 개선 제안서

> 4개 분석가 (Codex GPT-5.5, Claude 파이프라인, Claude 아키텍처, Claude UX) 통합
> 버그 수정이 아닌 **로직/플로우/품질/성능/UX 개선** 중심

---

## 요약 대시보드

```mermaid
pie title 개선 제안 분포
    "파이프라인 & AI 품질" : 15
    "아키텍처 & 성능" : 18
    "프론트엔드 UX" : 26
    "보안 & 운영" : 8
```

---

## 1. 파이프라인 & AI 품질 개선

### 1.1 몽타주/보이스오버 씬 처리 개선
**현재**: Gemini가 V.O. 캐릭터를 물리적 등장으로 오인 (씬 10 사례)
**제안**: 시스템 프롬프트에 "V.O., (V.O.), (E) 등 음성으로만 등장하는 인물은 visible_entities에 포함하지 말 것" 규칙 추가 + 아웃룩 매핑에 없는 인물은 자동 제외 필터
**효과**: S | Impact: high

### 1.2 씬 분석 피드백 루프
**현재**: 1회 LLM 호출로 씬 분석 완료, 품질 검증 없음
**제안**: GPT-5.5로 씬 분석 결과 교차 검증 (visible_entities vs 아웃룩 매핑 일치율, T2I 프롬프트 마커 유효성)
**효과**: M | Impact: high

### 1.3 참조 이미지 일관성 검증
**현재**: 참조 이미지 생성 후 개별 품질만 검증
**제안**: 같은 캐릭터의 여러 참조 이미지(얼굴 + 아웃룩별) 간 일관성 교차 검증. GPT Vision으로 "같은 인물인가?" 확인
**효과**: L | Impact: high

### 1.4 씬 이미지 시각적 연속성 강화
**현재**: dependent_scene_id로 이전 씬 이미지를 참조로 전달
**제안**: 연속 씬 이미지 생성 후 GPT Vision으로 시각적 일관성 점수 산출. 점수 낮으면 이전 씬 이미지를 추가 참조로 넣어 재생성
**효과**: L | Impact: high

### 1.5 프롬프트 번역 품질 검증
**현재**: Gemini Pro가 한국어 T2I → 영어로 번역, 검증 없음
**제안**: 번역된 프롬프트를 다시 한국어로 역번역하여 원본과 의미 비교 (BLEU/LLM 판단). 의미 손실이 크면 재번역
**효과**: M | Impact: medium

### 1.6 adaptive 씬 변형 수
**현재**: 모든 씬에 동일하게 N개(기본 3) 변형 생성
**제안**: 씬의 복잡도(등장인물 수, 액션 강도)에 따라 변형 수를 2~5로 동적 조정. 단순 대화 씬은 2개, 액션 씬은 5개
**효과**: M | Impact: medium

### 1.7 엔티티 추출 다중 에피소드 학습
**현재**: 각 에피소드 독립 분석, prior_entities로 이름만 전달
**제안**: 이전 에피소드의 확정된 요소 정보(설명, 시각 특성, T2I 프롬프트)를 컨텍스트로 전달하여 일관성 향상
**효과**: M | Impact: high

---

## 2. 아키텍처 & 성능 개선

### 2.1 DB 인덱스 추가 (최우선)
**현재**: PK와 UniqueConstraint 외 인덱스 없음
**제안**: scene_still(project_id, episode_id), image_asset(entity_id, asset_type), image_asset(still_id), pipeline_progress(project_id, episode_id, operation) 등 핵심 쿼리 컬럼에 인덱스 추가
**효과**: S | Impact: critical

### 2.2 N+1 쿼리 제거
**현재**: list_stills에서 씬당 엔티티/이미지 개별 쿼리 (55씬×5엔티티=275쿼리)
**제안**: IN 쿼리로 일괄 로드 → 메모리에서 매핑
**효과**: M | Impact: high

### 2.3 DB 커넥션 풀 설정
**현재**: SQLAlchemy 기본 풀 (pool_size=5)
**제안**: `pool_size=10, max_overflow=20, pool_timeout=30` 명시 설정. 15개 이미지 동시 생성 + LLM 로깅 대응
**효과**: S | Impact: high

### 2.4 Episode.fulltext lazy loading
**현재**: 모든 Episode 쿼리에서 fulltext (80K+ chars) 로드
**제안**: `defer(Episode.fulltext)` 적용, 분석/전문 조회에서만 로드
**효과**: S | Impact: medium

### 2.5 AnalysisService 리팩토링 (God Method 분할)
**현재**: run_analysis 400줄 단일 메서드, reanalyze_scenes와 60% 코드 중복
**제안**: `_run_entity_phase()`, `_run_scene_phase()`, `_save_style_and_summary()`로 분할
**효과**: M | Impact: medium

### 2.6 ImageService 분할
**현재**: image_service.py 3,500줄+ 단일 파일
**제안**: ReferenceImageService, SceneImageService, VariationService, ImageCrudService로 분리
**효과**: L | Impact: medium

### 2.7 백그라운드 태스크 시스템
**현재**: `threading.Thread(daemon=True)` — 프로세스 재시작 시 작업 소실
**제안**: Phase 1: in-process task registry + 시작 시 stale running 상태 복구. Phase 2: Celery/ARQ 도입
**효과**: L~XL | Impact: high

### 2.8 Alembic 마이그레이션 도입
**현재**: database.py에서 ALTER TABLE 인라인 실행, 에러 무시
**제안**: Alembic 초기화 + timestamp 컬럼 TIMESTAMPTZ 전환 + 인덱스 마이그레이션
**효과**: M | Impact: medium

### 2.9 구조화 로깅 (structlog)
**현재**: 일반 Python logging, 구조화 안 됨
**제안**: structlog 도입, project_id/episode_id/operation 바인딩, JSON 포맷 출력
**효과**: M | Impact: medium

### 2.10 헬스체크 엔드포인트
**현재**: 없음
**제안**: `GET /api/v1/health` — DB 연결, Gemini 키 수, OpenAI 키 상태 반환
**효과**: S | Impact: medium

---

## 3. 프론트엔드 UX 개선

### 3.1 글로벌 토스트/에러 시스템 (최우선)
**현재**: 모든 catch 블록이 에러 무시
**제안**: `useToast` 훅 + AppShell에 토스트 렌더러 마운트. 모든 API 에러 표시
**효과**: M | Impact: critical

### 3.2 EpisodeDetail 2패널 레이아웃
**현재**: 50개 씬이 단일 스크롤 칼럼
**제안**: 좌측 씬 목록(인덱스+비트+썸네일) 고정, 우측 상세 패널
**효과**: L | Impact: high

### 3.3 SceneVariationCard 아코디언
**현재**: 6개 섹션이 평면 카드에 모두 펼침
**제안**: 콘텐츠 / 프롬프트 / 이미지 3단 아코디언. 이미지는 항상 펼침
**효과**: M | Impact: high

### 3.4 이미지 리뷰 키보드 단축키
**현재**: 모든 리뷰가 마우스 클릭
**제안**: ←/→ 네비게이션, A 승인, R 수정필요, S 대표설정
**효과**: M | Impact: high

### 3.5 배치 승인/거부
**현재**: 이미지 1개씩 리뷰
**제안**: 체크박스 다중선택 + "일괄 승인" / "일괄 수정필요" 액션
**효과**: M | Impact: high

### 3.6 SSE 실시간 업데이트
**현재**: 3초 인터벌 폴링 × 3개 페이지
**제안**: `/progress/stream` SSE 엔드포인트. 상태 변경 시에만 push
**효과**: L | Impact: high

### 3.7 WorldGuide 구조화 폼 에디터
**현재**: raw JSON textarea
**제안**: era, region, genre, color_tone 등 필드별 입력 + "고급" 토글로 JSON 편집
**효과**: M | Impact: high

### 3.8 이미지 나란히 비교
**현재**: 변형 이미지를 1개씩 모달로 확인
**제안**: 2~3컬럼 비교 뷰, 클릭으로 대표 선택
**효과**: M | Impact: high

### 3.9 씬 점프 네비게이션
**현재**: 50개 씬에서 스크롤로만 이동
**제안**: 상단 고정 "씬 #" 입력 → scrollIntoView + G 단축키
**효과**: S | Impact: high

### 3.10 엔티티 검색
**현재**: 타입별 탭 필터만 존재
**제안**: 텍스트 검색 입력 (이름 필터)
**효과**: S | Impact: high

### 3.11 스켈레톤 로더
**현재**: "로딩 중..." 텍스트만 표시
**제안**: 카드/리스트 형태 스켈레톤 컴포넌트
**효과**: S | Impact: medium

### 3.12 세그먼테이션 슬라이더 디바운스
**현재**: 매 틱마다 API 호출
**제안**: 400ms 디바운스
**효과**: S | Impact: medium

### 3.13 에피소드 번호 자동 증가
**현재**: 수동 입력
**제안**: `Math.max(...episodes.map(e => e.episode_number)) + 1` 기본값
**효과**: S | Impact: low

---

## 4. 보안 & 운영

### 4.1 기본 비밀번호 제거
**현재**: config.py에 admin123/creator123 하드코딩
**제안**: 기본값 제거, .env 필수 + 시작 시 검증
**효과**: S | Impact: critical

### 4.2 세션 쿠키 Secure 플래그
**현재**: httponly=True만, secure=False
**제안**: 프로덕션에서 secure=True 추가
**효과**: S | Impact: high

### 4.3 LLMCallLog 프롬프트 자르기 + 보존 정책
**현재**: 전체 프롬프트 텍스트 무제한 저장
**제안**: max 10,000자 자르기 + 30일 보존 후 자동 삭제
**효과**: S | Impact: medium

### 4.4 PostgreSQL 통합 테스트 환경
**현재**: 테스트가 SQLite 사용 → PostgreSQL과 동작 차이
**제안**: docker-compose.test.yml로 PostgreSQL 테스트 환경 구축
**효과**: M | Impact: high

---

## 실행 우선순위 로드맵

```mermaid
gantt
    title 개선 실행 로드맵
    dateFormat YYYY-MM-DD
    section Phase 1 (Quick Wins)
    DB 인덱스 추가              :p1a, 2026-03-20, 1d
    커넥션 풀 설정              :p1b, 2026-03-20, 1d
    헬스체크 엔드포인트          :p1c, 2026-03-20, 1d
    글로벌 토스트 시스템         :p1d, 2026-03-20, 2d
    스켈레톤 로더               :p1e, 2026-03-21, 1d
    엔티티 검색                 :p1f, 2026-03-21, 1d
    씬 점프 네비게이션           :p1g, 2026-03-21, 1d
    기본 비밀번호 제거           :p1h, 2026-03-21, 1d
    section Phase 2 (Core UX)
    N+1 쿼리 제거              :p2a, 2026-03-22, 2d
    WorldGuide 구조화 편집      :p2b, 2026-03-22, 2d
    이미지 키보드 단축키         :p2c, 2026-03-23, 2d
    배치 승인/거부              :p2d, 2026-03-23, 2d
    나란히 비교 뷰              :p2e, 2026-03-24, 2d
    SceneCard 아코디언          :p2f, 2026-03-24, 2d
    section Phase 3 (Architecture)
    AnalysisService 리팩토링    :p3a, 2026-03-25, 3d
    ImageService 분할           :p3b, 2026-03-26, 3d
    SSE 실시간 업데이트          :p3c, 2026-03-27, 3d
    2패널 레이아웃              :p3d, 2026-03-28, 3d
    section Phase 4 (Infra)
    Alembic 마이그레이션         :p4a, 2026-03-30, 2d
    structlog 도입              :p4b, 2026-03-31, 2d
    PostgreSQL 통합 테스트       :p4c, 2026-04-01, 3d
    Celery 태스크 큐            :p4d, 2026-04-03, 5d
```

---

## 5. Codex 제안 — 전략적 개선 (High-Leverage)

### 5.1 내구성 있는 작업 큐 시스템
**현재**: raw threading.Thread(daemon=True) — 프로세스 재시작 시 작업 소실
**제안**: Durable job table + worker queue + SSE/WebSocket + 취소/재시도/우선순위
**효과**: XL | Impact: critical

### 5.2 단계별 증분 파이프라인
**현재**: 재분석 시 이전 데이터 전체 삭제 → 작은 수정에도 대규모 재계산
**제안**: 단계별 아티팩트를 content hash로 관리 + 변경된 단계만 선택적 재실행
**효과**: XL | Impact: critical

### 5.3 관계형 데이터 정규화
**현재**: visible_entities가 JSON 텍스트, composite는 prompt_used LIKE로 식별
**제안**: scene_visible_entity, scene_reference_image, scene_dependency 등 명시적 테이블
**효과**: L | Impact: critical

### 5.4 다중 신호 이미지 랭킹
**현재**: GPT 1회 호출로 최적 이미지 선택, 검증 점수/연속성/커버리지 미반영
**제안**: vision 선택 + 검증 점수 + 연속성 + 엔티티 커버리지 복합 스코어
**효과**: M | Impact: high

### 5.5 씬 플래닝 아티팩트
**현재**: 정규식 + 1회 AI 2분할만 지원, 분할 후 즉시 실행
**제안**: n-way 분할 + 비트 밀도 휴리스틱 + 신뢰도 + 사용자 승인 후 실행
**효과**: M | Impact: high

### 5.6 WorldGuide 버전 관리
**현재**: 존재하면 재사용, 내용 변경 감지 없음
**제안**: 소스 해시로 버전 관리 + 부분 갱신 + 가드레일 주입
**효과**: M | Impact: high

### 5.7 다중 사용자 작업 잠금
**현재**: 분석만 row lock, 이미지/내보내기는 잠금 없음
**제안**: 에피소드 단위 exclusive lease/version token으로 충돌 방지
**효과**: M | Impact: high

### 5.8 운영 대시보드 (Observability)
**현재**: LLM 로그 DB 저장만, 프론트에서 미사용
**제안**: correlation ID + 비용/큐 시간 메트릭 + 운영자용 runs/traces 화면
**효과**: M | Impact: high

---

## 6. 파이프라인 심층 분석 (Claude Pipeline Architect)

### 6.1 씬 타입 분류 추가 (몽타주/회상/꿈/V.O.)
**현재**: 모든 씬을 동일하게 처리, 몽타주/회상 구분 없음
**제안**: `scene_type` enum (normal|montage|flashback|dream|voiceover|transition) 추가. 타입별 T2I 전략 차별화 (몽타주→콜라주, 회상→세피아, 꿈→소프트포커스)
**효과**: S | Impact: high

### 6.2 T2I 변형의 구도 다양성 강제
**현재**: N개 변형이 거의 동일한 구도로 생성됨
**제안**: 변형마다 `camera_angle_hint` 필수 (extreme_wide, medium, close_up, over_shoulder, bird_eye)
**효과**: M | Impact: high

### 6.3 엔티티 설명 잘림 방지 (40자→150자)
**현재**: scene_extractor_v2.py에서 `description[:40]`으로 잘림
**제안**: 120~150자로 확대하거나 `visual_traits` 배열을 구조화 블록으로 전달
**효과**: S | Impact: medium

### 6.4 WorldGuide `style_rules` 필드 누락 — 씬 가드레일 미적용
**현재**: WorldGuide 스키마에 `style_rules` 없음 → 씬 이미지에서 `must_maintain/must_avoid` 항상 비어있음
**제안**: 스키마에 추가 + 프롬프트에서 생성 지시
**효과**: M | Impact: high

### 6.5 첫 등장 장소에 배경 참조 이미지 포함
**현재**: location 참조 이미지가 씬 생성에서 제외됨 (연속성은 이전 씬 이미지로만)
**제안**: 해당 장소 첫 등장 씬에는 location 참조 이미지를 포함
**효과**: M | Impact: high

### 6.6 씬 간 캐릭터 일관성 교차 검증
**현재**: 개별 씬 검증만, 씬 간 캐릭터 외모 일관성 미확인
**제안**: 연속 씬 생성 후 GPT Vision으로 캐릭터 외모 비교. 불일치 시 재생성
**효과**: L | Impact: high

### 6.7 의존성 텍스트 미리보기 확대 (200→400~600자)
**현재**: scene_dependency_extractor가 씬 텍스트 200자만 전달
**제안**: 400~600자 + 엔티티 공출현 정보 포함으로 연관성 판단 정확도 향상
**효과**: S | Impact: medium

### 6.8 adaptive 엔티티 워커 스태거 (2초 고정→적응형)
**현재**: entity_extractor에서 모든 워커에 2초 고정 대기
**제안**: 0.5초 시작 + 429 발생 시 공유 backoff 이벤트로 적응형 조절
**효과**: S | Impact: medium

### 6.9 씬 변형 내부 병렬 생성
**현재**: 씬당 3개 변형이 순차 생성, 외부에서만 씬 간 병렬
**제안**: 씬 내부에서도 3개 변형을 동시 생성 → 씬당 시간 ~2x 단축
**효과**: M | Impact: high

### 6.10 재분석 시 고아 ImageAsset 정리
**현재**: run_analysis()가 SceneStill 삭제하지만 연관 ImageAsset 미삭제
**제안**: SceneStill 삭제 전 연관 ImageAsset도 함께 삭제
**효과**: S | Impact: medium

---

## Phase별 요약

| Phase | 기간 | 항목 수 | 핵심 효과 |
|-------|------|---------|-----------|
| **1. Quick Wins** | 2일 | 8건 | DB 성능 2~5x, UX 기본 피드백, 보안 강화 |
| **2. Core UX** | 5일 | 6건 | 리뷰 효율 3~5x, 편집 경험 대폭 개선 |
| **3. Architecture** | 10일 | 4건 | 유지보수성, 실시간성, 확장성 |
| **4. Infrastructure** | 12일 | 4건 | 운영 안정성, 테스트 신뢰성, 스케일링 |