# TheRoad Scene Lab v10codex 개발기획서

작성 기준일: 2026-04-15  
문서 성격: `docs/v10` 초안 보완판 + 현재 코드 기준 구현 계획서  
원본 보존 원칙: `docs/v10` 원문은 수정하지 않고, 이 문서에서만 보완/정정한다.

## 1. 문서 목적

이 문서는 현재 저장소의 실제 구현 상태를 기준으로, TheRoad Scene Lab을 안정적으로 개발·확장·운영하기 위한 실행 가능한 개발기획서다.

초안 기준 문서:
- [docs/v10/00-architecture.md](/Users/manta/Documents/Projects/TheRoad-I1/docs/v10/00-architecture.md:1)
- [docs/v10/01-pipeline-steps.md](/Users/manta/Documents/Projects/TheRoad-I1/docs/v10/01-pipeline-steps.md:1)
- [docs/v10/02-prompts-and-schemas.md](/Users/manta/Documents/Projects/TheRoad-I1/docs/v10/02-prompts-and-schemas.md:1)
- [docs/v10/03-image-generation.md](/Users/manta/Documents/Projects/TheRoad-I1/docs/v10/03-image-generation.md:1)
- [docs/v10/04-infrastructure.md](/Users/manta/Documents/Projects/TheRoad-I1/docs/v10/04-infrastructure.md:1)

주요 코드 근거:
- [backend/app/core/step_manifest.py](/Users/manta/Documents/Projects/TheRoad-I1/backend/app/core/step_manifest.py:1)
- [backend/app/core/step_runner.py](/Users/manta/Documents/Projects/TheRoad-I1/backend/app/core/step_runner.py:1)
- [backend/app/api/v1/steps.py](/Users/manta/Documents/Projects/TheRoad-I1/backend/app/api/v1/steps.py:1)
- [backend/app/models/project.py](/Users/manta/Documents/Projects/TheRoad-I1/backend/app/models/project.py:1)
- [backend/app/services/image_service.py](/Users/manta/Documents/Projects/TheRoad-I1/backend/app/services/image_service.py:1)
- [backend/app/modules/llm/llm_client.py](/Users/manta/Documents/Projects/TheRoad-I1/backend/app/modules/llm/llm_client.py:1)
- [frontend/src/App.tsx](/Users/manta/Documents/Projects/TheRoad-I1/frontend/src/App.tsx:1)
- [frontend/package.json](/Users/manta/Documents/Projects/TheRoad-I1/frontend/package.json:1)

## 2. 한 줄 요약

TheRoad Scene Lab은 프로젝트 단위 세계관과 에피소드 단위 시나리오를 입력받아, `텍스트 분석 → beat/shot 분해 → 엔티티/아웃룩/연출 추출 → T2I 프롬프트 생성 → 참조/씬 이미지 생성 → 웹북/PDF export`까지 수행하는 멀티스테이지 영상-이미지 제작 파이프라인이다.

이 문서의 핵심 방향은 다음 세 가지다.
- Step 기반 v4 파이프라인을 시스템의 주 실행 경로로 확정한다.
- 멀티 에피소드/멀티 사용자 환경에서 데이터 손실이 없도록 동기화 규칙을 재정의한다.
- 프롬프트/체크포인트/DB/UI가 같은 상태 모델을 보도록 SSOT를 정리한다.

## 3. 현재 구현 기준 보정 사항

초안 문서와 실제 코드 사이의 차이를 먼저 고정해야 이후 개발이 흔들리지 않는다.

| 항목 | `docs/v10` 초안 | 현재 구현 | 본 계획서 기준 |
|---|---|---|---|
| 프런트엔드 스택 | Next.js | Vite + React 19 + React Router SPA | 현재 구현 기준으로 Vite SPA 유지 |
| 주 분석 실행 경로 | StepRunner 중심으로 기술 | Step API와 legacy `AnalysisService`가 공존 | Step API를 주 경로로, legacy는 호환 레이어로 축소 |
| 단계 수 표기 | 33단계 | manifest에는 active/legacy/disabled/aux 포함 40+ 엔트리 | "핵심 active 경로"와 "legacy/disabled 경로"를 분리 표기 |
| 모델 할당 SSOT | `step_manifest.py`처럼 읽힘 | 실제 라우팅은 `llm_client.PIPELINE_STEPS`가 따로 관리 | manifest 중심 설계로 수렴, 런타임 매핑은 코드 생성/검증 대상으로 전환 |
| 체크포인트-DB 동기화 | UPSERT/삭제 금지 원칙 | 일부 project-wide delete, still delete 존재 | Episode-scoped UPSERT + soft stale 원칙으로 재설계 |

## 4. 제품 목표

### 4.1 제품 목표

- 시나리오 PDF 업로드 후 분석 및 이미지 생성까지 한 플랫폼에서 수행한다.
- 프로젝트 단위로 세계관/인물/아웃룩을 축적해 후속 에피소드에 재사용한다.
- shot 단위 이미지 생성과 교차 shot 일관성 유지 기능을 제공한다.
- 제작자가 프롬프트, 엔티티, still, 이미지 대표본을 수동 보정할 수 있어야 한다.
- 웹북/PDF export가 제작 파이프라인의 최종 산출물로 연결되어야 한다.

### 4.2 비목표

- 실시간 협업 편집기 구현
- 분산 워커/Celery 기반 대규모 배치 인프라 즉시 도입
- 완전 자동 품질 보장
- 범용 DCC 툴 대체

## 5. 사용자와 역할

| 역할 | 설명 | 주요 권한 |
|---|---|---|
| `admin` | 시스템 운영자 | 사용자 관리, feature flag 변경, 전 프로젝트 접근 |
| `owner` | 프로젝트 책임자 | 프로젝트/멤버/에피소드 관리, 파이프라인 실행 |
| `member` | 협업 사용자 | 조회, 일부 편집, 생성/검수 |
| `creator` | 기본 제작 계정 | 내부 운영/시드 사용자 |

## 6. 시스템 범위

### 6.1 백엔드 범위

- 인증/권한
- 프로젝트/에피소드/멤버 관리
- Step 기반 분석 파이프라인
- 참조/합성/씬 이미지 생성
- 이미지 검수 및 재생성
- 프롬프트 버전 관리
- 웹북/PDF export
- 활동 로그, 진행률, 생성 trace

### 6.2 프런트엔드 범위

- 대시보드
- 프로젝트 상세
- 에피소드 목록/상세
- 엔티티 관리
- 이미지 검수
- 프롬프트 관리자
- export studio
- 관리자 화면

## 7. 시스템 아키텍처

```mermaid
flowchart LR
    U[User]
    FE[Vite React SPA]
    API[FastAPI API]
    JOB[Background Job Manager<br/>threading]
    STEP[StepRunner / Step Manifest]
    LEG[Legacy AnalysisService]
    LLM[LiteLLM Router<br/>OpenAI / Gemini]
    IMG[GeminiImageClient / ImageService]
    DB[(PostgreSQL)]
    FS[(projects/ + checkpoints/ + prompts/)]

    U --> FE
    FE --> API
    API --> JOB
    API --> STEP
    API --> LEG
    STEP --> LLM
    STEP --> DB
    STEP --> FS
    LEG --> LLM
    LEG --> DB
    LEG --> FS
    API --> IMG
    IMG --> DB
    IMG --> FS
    IMG --> LLM
```

### 7.1 권장 운영 구조

- 분석 파이프라인의 기준 경로는 `StepRunner + /steps API`다.
- `AnalysisService` 기반 `/episodes/{id}/analyze`는 호환용이다.
- 이미지 생성은 step class와 `ImageService`가 함께 동작한다.
- 장기적으로는 `AnalysisService`의 기능을 step graph 쪽으로 흡수하고, service는 orchestration helper만 남긴다.

### 7.2 실행 모델

- 현재 백그라운드 작업은 [backend/app/core/job_manager.py](/Users/manta/Documents/Projects/TheRoad-I1/backend/app/core/job_manager.py:1)의 daemon thread 기반이다.
- 활성 태스크 중복 실행 방지는 [backend/app/core/task_registry.py](/Users/manta/Documents/Projects/TheRoad-I1/backend/app/core/task_registry.py:1)에서 담당한다.
- 서버 재시작 시 `PipelineProgress.status=running`은 `error`로 복구된다.

## 8. 기술 스택

### 8.1 현재 기준

| 레이어 | 스택 |
|---|---|
| Backend | FastAPI + SQLAlchemy |
| DB | PostgreSQL |
| Frontend | Vite + React 19 + React Router |
| LLM 라우팅 | LiteLLM Router |
| Text LLM | GPT-5.5 계열, Gemini 3.x 계열 |
| Image LLM | Gemini Flash Image Preview |
| Config | pydantic-settings |
| Job Runtime | Python threading |
| Export | HTML/PDF export service |

### 8.2 유지 방침

- 단기: 현재 스택 유지
- 중기: background job abstraction 유지 후 Celery/ARQ로 교체 가능하게 준비
- 장기: prompt/step/llm mapping을 manifest 기반 생성 체계로 통합

## 9. 디렉터리 기준 구조

| 경로 | 역할 |
|---|---|
| `backend/app/core` | config, DB, gate, step engine, runtime |
| `backend/app/core/steps` | StepRunner 구현체 |
| `backend/app/modules/pipeline` | 각 step의 LLM 로직/도메인 로직 |
| `backend/app/services` | legacy orchestration + image/export service |
| `backend/app/api/v1` | REST API |
| `backend/app/models` | SQLAlchemy 모델 |
| `frontend/src/pages` | 라우트 단위 페이지 |
| `frontend/src/components` | 공통 UI/패널 |
| `prompts/_base` | 프롬프트 파일 버전 저장소 |
| `projects/{project_id}` | 자산, checkpoints, 생성 결과 |

## 10. 도메인 모델

### 10.1 핵심 엔터티

```mermaid
erDiagram
    PROJECT_REGISTRY ||--o{ EPISODE : has
    PROJECT_REGISTRY ||--o{ ENTITY_CANON : owns
    EPISODE ||--o{ ENTITY_EPISODE_LINK : links
    ENTITY_CANON ||--o{ ENTITY_EPISODE_LINK : linked
    ENTITY_CANON ||--o{ CHARACTER_OUTLOOK : character
    ENTITY_CANON ||--o{ CHARACTER_OUTLOOK : outlook
    EPISODE ||--o{ SCENE_STILL : has
    SCENE_STILL ||--o{ IMAGE_ASSET : renders
    ENTITY_CANON ||--o{ IMAGE_ASSET : references
    PROJECT_REGISTRY ||--o{ WORLD_GUIDE : has
    PROJECT_REGISTRY ||--o{ PROJECT_SETTINGS : has
    PROJECT_REGISTRY ||--o{ PIPELINE_PROGRESS : tracks
    PROJECT_REGISTRY ||--o{ OPERATION_LOG : logs
    PROJECT_REGISTRY ||--o{ LLM_CALL_LOG : logs
    RELATION_FACT ||--o{ RELATION_PARTICIPANT : has
    ENTITY_CANON ||--o{ RELATION_PARTICIPANT : joins
```

### 10.2 데이터 소유권 규칙

현재 구현에서 가장 중요한 보정 포인트다.

- `EntityCanon`은 프로젝트 전역 canon이다.
- `EntityEpisodeLink`는 에피소드별 연결/출현 카운트다.
- `CharacterOutlook`은 프로젝트 전역 캐릭터-아웃룩 매핑이다.
- `SceneStill`은 에피소드 단위 분석 결과다.
- `ImageAsset`은 `entity_id` 또는 `still_id`를 기준으로 자산을 참조한다.

### 10.3 설계 원칙

- 에피소드 재분석이 프로젝트 전역 canon을 삭제해서는 안 된다.
- still 재분석이 기존 이미지 자산의 FK를 일괄 해제해서는 안 된다.
- checkpoint는 DB의 보조 저장소가 아니라 step 실행의 공식 산출물이어야 한다.
- DB sync는 항상 `UPSERT + stale marking` 원칙으로 동작해야 한다.

## 11. 체크포인트 설계

### 11.1 경로 규칙

`{projects_dir}/{project_id}/checkpoints/episodes/{episode_id}/{step_id}/manifest.json`

### 11.2 저장 원칙

- 임시 파일 생성 후 `os.replace()`
- 이전 manifest는 archive로 보존
- resume는 성공 결과를 재사용
- force는 downstream을 stale 처리

### 11.3 추가 규칙

- 한 step이 다른 step의 checkpoint 파일을 직접 `write_text()`로 덮어쓰지 않는다.
- alias step이 필요한 경우 공통 checkpoint writer를 사용한다.
- checkpoint 저장 실패는 step failure로 승격한다.

## 12. 파이프라인 전개 구조

### 12.1 전체 흐름

```mermaid
flowchart TD
    A[Project 생성] --> B[Episode PDF 업로드]
    B --> C[text_cleanup]
    C --> D[scene_segmentation]
    D --> E[scene_save]
    E --> F[beat_extract + shot_extract]
    F --> G[entity listing/extract/merge/detail/t2i]
    G --> H[scene_director + shot_director]
    H --> I[outlook_phase1/2/3]
    I --> J[shot_staging + scene_consistency + set_design]
    J --> K[scene_detail]
    K --> L[shot_dependency_t2i + t2i_review]
    L --> M[world_guide + ref_image_gen]
    M --> N[composite_image_gen + character_state_variant]
    N --> O[scene_image_pipeline]
    O --> P[webbook / pdf export]
```

### 12.2 실행 경로 정의

- `Step API` 경로
  - `GET /steps`
  - `POST /steps/{step_id}`
  - `POST /steps/run-all`
  - `GET /steps/{step_id}/result`
- `Legacy episode API` 경로
  - `POST /episodes/{episode_id}/analyze`
  - `POST /episodes/{episode_id}/reanalyze-scenes`

기획 기준:
- 신규 기능은 `Step API`에 먼저 붙인다.
- legacy API는 step orchestration wrapper 역할만 하게 줄인다.

## 13. 단계 카탈로그

### 13.1 분석 단계

| Order | Step | 성격 | 입력 | 산출 | 기본 모델 | 비고 |
|---|---|---|---|---|---|---|
| 0 | `planning_doc_analysis` | 조건부 | planning doc PDF/text | 구조화된 기획서 맥락 | flash-lite 계열 의도 | project-level 성격 |
| 1 | `text_cleanup` | active | episode fulltext/PDF | cleaned text | `gemini-lite` | |
| 2 | `scene_segmentation` | active | cleaned text | segments | `gemini-flash` | |
| 3 | `episode_summary` | active | fulltext | episode summary | `gpt-mini` | |
| 4 | `visual_world_rules` | active | summary/fulltext | world rules | `gpt` | 이후 거의 모든 step에 주입 |
| 5 | `scene_split` | on-demand | segmentation | split scenes | `gemini-flash` | legacy 보조 |
| 6 | `scene_save` | active | segments | checkpoint + scene text 저장 | no LLM | |
| 6.5 | `entity_character_list` | active | scenes, world rules | character name list | `gemini-pro` | beat/shot 안정화 |
| 7 | `scene_summary` | active | saved scenes | scene summaries | `gpt-mini` | fan-out |
| 7.1 | `beat_extract` | active | scenes | beats | `gemini-pro` | fan-out |
| 7.2 | `shot_extract` | active | beats | shots | `gemini-pro` | sequential bundles |
| 8 | `entity_all_character` | active | shots | character list | `gemini-pro` | |
| 9 | `entity_extract_character` | active | char list | character profiles | `gpt` | |
| 10 | `entity_all_location` | active | shots | location list | `gpt` | |
| 11 | `entity_extract_location` | active | location list | location profiles | `gemini-pro` | |
| 12 | `entity_all_prop` | active | shots | prop list | `gpt` | |
| 13 | `entity_extract_prop` | active | prop list | prop profiles | `gemini-pro` | |
| 13.5 | `entity_merge` | active | char/location/prop extracts | merged canon candidates | `gpt` | |
| 13.6 | `entity_relation` | active | merged entities | variant relations | `gpt` | relation tables 연동 |
| 13.7 | `entity_filter` | active | relations + counts | filtered entities | `gpt-mini` | |
| 14 | `entity_detail` | active | filtered entities | detailed entity profiles | `gpt` | |
| 15 | `entity_t2i` | active | entity detail | reference prompts | `gemini-pro` | fan-out |
| 15.5 | `shot_selection` | active | shots | selected shots | `gpt-mini` | |
| 16 | `scene_director` | active | selected shots + scenes | scene-level VE/VAH/location | `gemini-pro` | Gemini 고정 |
| 16.5 | `shot_director` | active | scene_director + shots | shot-level VE + variant resolve | `gpt` | |
| 17 | `scene_cinematography` | disabled/legacy | - | - | `gemini-pro` | 유지 호환 |
| 17.1 | `shot_cinematography` | disabled/legacy | - | - | `gemini-pro` | 유지 호환 |
| 18 | `scene_dependency` | disabled/legacy | - | - | `gpt` | |
| 18.1 | `shot_dependency` | active | selected shots + scene director | base dependency refs | `gpt` | |
| 19 | `outlook_phase1` | active | scene director | outlook inventory | `gemini-pro` | |
| 19.1 | `outlook_phase2` | active | phase1 | scene assignments | `gemini-pro` | |
| 19.2 | `outlook_phase3` | active | phase2 | merged outlooks | `gemini-pro` | |
| 19.3 | `outlook_extraction` | on-demand/legacy | scene director | legacy 3-phase wrapper | `gemini-pro` | |
| 19.5 | `shot_staging` | active | shots + selection + entity/world | DP staging | `gpt` | |
| 19.7 | `set_design` | conditional | shots + staging + location | bg hints / bg refs | `gpt` | feature flag |
| 19.9 | `scene_consistency` | active | staging + director + shots | fixed elements | `gemini-pro` | safety fallback 있음 |
| 20 | `scene_detail` | active | multiple upstreams | shot-level T2I variations | `gpt` | 핵심 |
| 20.5 | `shot_dependency_t2i` | active | scene_detail + consistency | refined bg dependency | `gpt-mini` | image pipeline feeding |
| 20.7 | `t2i_review` | active | entity_t2i + scene_detail | review result | `gemini-flash` | |
| 21 | `scene_verify` | legacy/conditional | scene_detail | cross verification | `gpt` | optional |

### 13.2 이미지 단계

| Order | Step | 입력 | 산출 | 기본 모델 | 비고 |
|---|---|---|---|---|---|
| 22 | `world_guide` | entities + scene_detail | global image guide | `gpt` | |
| 23 | `ref_image_gen` | entity_t2i | entity reference images | `gemini-image` | |
| 24 | `composite_image_gen` | ref images + outlooks | character+outlook composites | `gemini-image` | `if_has_outlooks` 의도 |
| 24.5 | `character_state_variant` | composites + staging | dead/injured variants | `gemini-image` | |
| 25 | `scene_image_pipeline` | stills + refs + guide + dependency | final scene assets | mixed | compound sub-steps |

### 13.3 보조 단계

| Step | 역할 |
|---|---|
| `outlook_dedup` | 아웃룩 중복 정리 보조 |
| `project_summary` | 프로젝트 단위 요약 생성 |

## 14. 단계별 입력/출력 규약

### 14.1 공통 출력 규격

```json
{
  "completed_count": 10,
  "applicable_count": 10,
  "failed_count": 0,
  "data": {}
}
```

### 14.2 `scene_detail` 핵심 규약

- 입력:
  - `scene_save`
  - `shot_extract`
  - `shot_selection`
  - `shot_staging`
  - `shot_director`
  - `scene_consistency`
  - `set_design`
  - `entity_t2i`
  - `outlook_phase3`
  - `visual_world_rules`
- 출력:
  - shot별 `t2i_variations`
  - `visible_entities`
  - `_shot_index`
  - `representative_moment`

규칙:
- LLM에는 bare `C##`, `L##`, `P##`만 노출
- `C##O##` 조합은 코드에서 후처리
- VE 외 ID는 retry 후 강제 제거 가능
- user-edited shot은 checkpoint에 `_user_edited=true`로 보존

### 14.3 `scene_image_pipeline` 핵심 규약

- 참조 이미지 우선순위:
  - set_design background
  - previous shot background
  - composite reference
  - base face reference
  - prop reference
  - state variant reference
- `exact_background`와 `atmosphere_reference`는 반드시 구분
- `scene_consistency`의 character_state가 있고 exact background가 존재하면 state variant 대신 background에서 유지

## 15. 프런트엔드 정보 구조

### 15.1 라우트 구조

| 경로 | 페이지 | 역할 |
|---|---|---|
| `/` | `Dashboard` | 프로젝트 목록 |
| `/projects/:id` | `ProjectDetail` | 프로젝트 개요 |
| `/projects/:id/episodes` | `Episodes` | 에피소드 목록 |
| `/projects/:id/episodes/:episodeId` | `EpisodeDetail` | step 실행, still 편집, 진행률 |
| `/projects/:id/entities` | `Entities` | canon/outlook 관리 |
| `/projects/:id/images` | `ImageReview` | 이미지 검수 |
| `/projects/:id/export` | `ExportStudio` | 웹북/PDF export |
| `/prompts` | `PromptManager` | 프롬프트 버전 관리 |
| `/admin/users` | `Users` | 관리자 |
| `/admin/activity` | `ActivityLog` | 관리자 |

### 15.2 핵심 UI 패널

- `PipelineStepsPanel`
- `PipelineProgress`
- `GenerationStatusPanel`
- `ImageGallery`
- `SceneVariationCard`
- `LLMConfigPanel`

### 15.3 프런트 개발 원칙

- step 상태와 버튼 활성 조건은 백엔드 semantics와 일치해야 한다.
- `partial`, `stale`, `not_applicable`, `disabled`를 시각적으로 구분해야 한다.
- 에피소드 상세 화면은 step 기반 실행을 표준 UX로 사용한다.
- 분석/이미지/export 진행률은 polling과 SSE 둘 다 수용 가능하게 유지한다.

## 16. API 경계와 책임

### 16.1 프로젝트 API

- 프로젝트 CRUD
- 멤버 관리
- 활동 로그
- feature flags
- planning doc 업로드/삭제/조회
- per-project LLM config

### 16.2 에피소드 API

- episode CRUD
- PDF upload
- legacy analyze / reanalyze
- fulltext 조회
- progress polling / stream
- segmentation preview

### 16.3 Step API

- step list/status
- single step run
- run-all
- result 조회
- snapshot 생성/복원
- shot selection toggle

### 16.4 Entity API

- entity list/detail/update
- still list/update
- T2I translation helper
- style rules 조회/수정
- character-outlook 조합 조회

### 16.5 Image API

- image list/detail/file
- review/validate/regenerate/set-primary
- single entity/still generation
- batch reference/scene generation
- variation recommend/generate/apply/select
- generation status / pipeline gate / traces

### 16.6 Export API

- webbook generation
- PDF render
- HTML zip export
- export validation
- file download/list

## 17. 개발 원칙

### 17.1 SSOT 원칙

- 단계 정의의 단일 진실 소스는 `step_manifest`여야 한다.
- 모델 alias 해석은 manifest에서 파생되거나 정합성 검증을 받아야 한다.
- 프런트 상태 라벨/버튼 조건은 `step_run.status` 규칙과 동일해야 한다.

### 17.2 데이터 안전 원칙

- episode 재분석은 project-wide destructive delete를 수행하지 않는다.
- `SceneStill`은 hard delete보다 soft stale을 우선한다.
- `ImageAsset`는 가능한 한 ID 안정성을 유지한다.
- checkpoint 저장 실패는 무시하지 않는다.

### 17.3 프롬프트 원칙

- DB 우선, 파일 fallback 유지
- 파일 프롬프트는 새 버전 디렉터리로만 추가
- 시나리오 고유명사 하드코딩 금지
- structured schema는 step 단위 contract로 관리

### 17.4 백그라운드 작업 원칙

- 같은 `job_key`는 중복 실행 금지
- 시작/종료/실패를 명시적으로 기록
- thread 기반 구현을 유지하되 job abstraction은 고정

## 18. 반드시 수정해야 할 구조적 이슈

이 절은 개발 순서의 기준이 된다.

### 18.1 P0 안정화 이슈

1. `checkpoint -> DB sync`의 project-wide delete 제거
2. `scene_still` hard delete 제거 또는 soft stale 전환
3. `scene_consistency` fallback 성공 후 실패 결과 추가 버그 수정
4. `partial` 게이트 semantics 통일
5. checkpoint write failure 승격
6. `shot_dependency_t2i`의 타 step checkpoint 직접 쓰기 제거
7. applicability `if_*` 공통 처리
8. manifest와 llm mapping 정합성 검증 추가

### 18.2 설계 결정

- 신규 개발은 위 8개 이슈 정리 전까지 기능 확장보다 안정화 우선
- 이미지 품질 개선 기능은 P0 이후 진행
- 프런트 고도화는 상태 모델 정리 이후 진행

## 19. 목표 상태 아키텍처

```mermaid
sequenceDiagram
    participant FE as Frontend
    participant API as Steps API
    participant JOB as JobManager
    participant RUN as StepRunner
    participant CP as Checkpoint Store
    participant DB as PostgreSQL
    participant LLM as LLM/Image Providers

    FE->>API: POST /steps/run-all
    API->>JOB: submit_background_job(job_key)
    JOB->>RUN: ordered step execution
    loop for each step
        RUN->>DB: read deps / step_run
        RUN->>LLM: call model
        RUN->>CP: atomic save manifest
        RUN->>DB: update step_run
    end
    API->>DB: sync checkpoint -> DB (UPSERT only)
    FE->>API: GET /steps, /result, /progress
```

목표 상태에서 지켜야 할 점:
- DB sync는 destructive rebuild가 아니라 idempotent apply다.
- checkpoint는 항상 step 소유자만 쓴다.
- run-all과 single-step은 같은 validation/gate를 사용한다.
- UI는 `partial` downstream 허용 여부를 정확히 반영한다.

## 20. 개발 로드맵

### Phase 0. 안정화

목표:
- 데이터 손실 제거
- 상태 모델 일관성 확보

작업:
- `_sync_checkpoints_to_db()` 분해
- project-wide delete 제거
- `SceneStill` soft stale 설계
- `scene_consistency` fallback bug fix
- `save_checkpoint` failure propagation
- `get_all_steps`의 `partial` 처리 수정
- applicability 공통화
- llm mapping validation startup check

산출물:
- 안정화 PR
- 회귀 테스트
- migration plan

완료 기준:
- 멀티 에피소드 프로젝트에서 episode 재분석 후 기존 canon 손실 없음
- partial upstream 이후 downstream 수동 실행 가능
- checkpoint write 실패 시 step이 실패 상태로 기록

### Phase 1. Step Engine 정규화

목표:
- Step API를 주 실행 경로로 확정

작업:
- legacy `AnalysisService`와 step orchestration 역할 구분
- run-all / single-step / snapshot restore 일관화
- checkpoint alias 쓰기 제거
- step metadata와 UI 모델 동기화

완료 기준:
- 신규 분석 기능은 service가 아니라 step으로만 추가
- `AnalysisService`는 wrapper 또는 migration helper 수준으로 축소

### Phase 2. 데이터 모델 정리

목표:
- project canon / episode linkage / still assets 경계 명확화

작업:
- canon upsert 규칙 재정의
- episode link diff apply
- character_outlook ownership 규칙 명확화
- still lifecycle 모델 도입
- orphan asset 처리 정책 명시

완료 기준:
- DB ERD와 sync 로직이 일치
- step rerun이 image asset identity를 불필요하게 끊지 않음

### Phase 3. 이미지 파이프라인 강화

목표:
- 참조 이미지 해석과 continuity 품질 안정화

작업:
- `shot_dependency`/`shot_dependency_t2i` 소비 구조 단일화
- set_design / prev-shot / state_variant 우선순위 명문화
- validation/sanitize retry strategy 정리
- generation trace와 UI 연결 강화

완료 기준:
- 배경 continuity 실패 케이스 감소
- state variant/background 유지 전략이 deterministic하게 작동

### Phase 4. 프런트 UX 정리

목표:
- 제작자가 실제 운영 가능한 화면 흐름 확보

작업:
- step status semantic 개선
- blocked/partial/stale 시각화
- still/detail editing UX 정리
- prompt manager와 LLM config 연결
- project detail의 planning doc workflow 개선

완료 기준:
- 운영자가 UI만으로 step 상태를 오해하지 않음
- 수동 보정 후 재실행 UX가 자연스럽게 이어짐

### Phase 5. 테스트/관측성

목표:
- 실제 운영 전 회귀 방지 체계 확보

작업:
- unit/integration/e2e test matrix 확장
- prompt/schema parity test
- manifest/llm mapping parity test
- snapshot restore regression test
- generation trace and operation log 대시보드화

완료 기준:
- 핵심 경로에 대한 자동 테스트 존재
- step resume/force/snapshot 복원 회귀를 잡을 수 있음

## 21. 테스트 전략

### 21.1 Unit Test

- `step_manifest` ordering / dependency / applicability
- checkpoint writer atomicity
- `llm_client` model resolution parity
- entity/still sync diff logic
- `scene_consistency` fallback branch

### 21.2 Integration Test

- episode upload -> step run-all -> checkpoint 생성
- multi-episode entity sync
- shot selection toggle -> scene_detail/still sync
- snapshot restore -> UI state 반영
- image pipeline gate 조건

### 21.3 E2E Test

- 프로젝트 생성, 에피소드 업로드, planning doc 업로드
- step 실행, still 편집, 이미지 검수, export
- admin/user 권한 경계

### 21.4 테스트 환경 원칙

- CI에서는 실제 외부 LLM 대신 mock adapter 우선
- schema validation은 실제 JSON schema 기준으로 검증
- image pipeline은 최소 smoke test + provider mock split 적용

## 22. 관측성과 운영

### 22.1 필수 로그

- step 시작/종료/실패
- checkpoint 경로/버전
- model alias와 resolved model
- sync diff 결과
- image generation retry/sanitize
- background job registration/unregistration

### 22.2 저장해야 할 운영 데이터

- `step_run`
- `PipelineProgress`
- `OperationLog`
- `LLMCallLog`
- `GenerationTrace`
- activity log

### 22.3 운영 알림 기준

- checkpoint write 실패
- sync destructive diff 시도
- step partial 비율 증가
- image moderation failure 급증
- snapshot restore 실패

## 23. 비기능 요구사항

| 항목 | 요구사항 |
|---|---|
| 안전성 | episode 재분석이 다른 episode 데이터를 손상시키지 않아야 함 |
| 일관성 | step 상태 semantics가 runner/API/UI에서 동일해야 함 |
| 추적성 | 어떤 prompt/model/version으로 생성되었는지 역추적 가능해야 함 |
| 복구성 | snapshot restore와 resume가 deterministic해야 함 |
| 확장성 | 새 step 추가 시 manifest + prompt + schema + UI 반영 경로가 명확해야 함 |
| 성능 | 긴 텍스트/여러 shot에서도 timeouts와 retries가 통제 가능해야 함 |

## 24. 개발 체크리스트

### 신규 step 추가 시

- `step_manifest.py` 등록
- `core/steps/__init__.py` 등록
- prompt 파일/스키마 추가
- model mapping parity 반영
- result checkpoint contract 정의
- UI 표시명/카테고리 확인
- 테스트 추가

### prompt 변경 시

- 새 버전 디렉터리 생성
- schema 호환 여부 확인
- downstream parser 영향 확인
- prompt manager DB/file fallback 경로 확인

### DB 필드 추가 시

- model 정의
- `init_db()` migration 문 추가
- sync 로직 반영
- API schema 반영
- 프런트 소비 지점 반영

## 25. 남은 의사결정 항목

1. `AnalysisService`를 언제 완전히 step orchestration으로 대체할 것인가
2. `SceneStill`에 soft delete 전용 컬럼을 둘지, `status=stale`만으로 처리할지
3. `shot_dependency_t2i`를 별도 step 결과로 유지할지, `shot_dependency`를 refinement step으로 합칠지
4. `ProjectSettings.style_rules_json`와 `visual_world_rules` checkpoint의 책임 경계를 어떻게 나눌지
5. thread 기반 job runtime을 언제 큐 시스템으로 교체할지

## 26. 최종 기준

이 프로젝트의 개발 기준은 다음과 같다.

- 원본 초안은 `docs/v10`에 유지한다.
- 구현 기준 개발기획서는 이 문서를 우선한다.
- 신규 기능 설계는 반드시 "현재 코드 경계"와 "보정된 데이터 규칙"을 따라야 한다.
- 안정화 이전에는 기능 추가보다 상태 일관성, sync 안전성, checkpoint 신뢰성을 우선한다.

이 문서는 v10 초안의 대체가 아니라, 현재 코드베이스를 기준으로 한 `실행 가능한 보완판`이다.