# 04. Pipeline Steps 감사

> 원본 코드/프롬프트/기존 문서를 수정하지 않고 생성한 read-only 감사 문서입니다.

## Step catalog 실측

`STEP_CATALOG` 로딩 기준으로 확인한 실측은 다음과 같다.

| 항목 | 값 |
|---|---:|
| total entries | 59 |
| active | 48 |
| deprecated | 10 |
| removed | 1 |
| analysis category | 48 |
| image category | 9 |
| auxiliary category | 2 |
| transform step_type | 48 |
| asset step_type | 9 |
| editorial step_type | 2 |

Applicability 분포:

| applicability | count |
|---|---:|
| `always` | 38 |
| `if_planning_doc` | 1 |
| `if_background_mode` | 6 |
| `if_shot_essence_enabled` | 1 |
| `if_has_outlooks` | 1 |
| `on_demand` | 4 |
| `disabled` | 8 |

## Manifest 문서 주석 drift

`backend/app/core/step_manifest.py` 상단 주석은 총 50개/active 42개 등 과거 수치를 포함한다. 실제 `STEP_CATALOG`는 59개/active 48개다.

이 drift는 런타임에 직접 장애를 만들지는 않지만, 개발자가 단계 수와 active 범위를 잘못 판단하게 만든다.

## Step metadata source

```mermaid
flowchart TB
    Manifest[STEP_MANIFEST] --> Catalog[STEP_CATALOG]
    Classes[STEP_CLASSES] --> Catalog
    Catalog --> UIRead[step_readmodel]
    Manifest --> DispatchSelect[analysis_dispatch_service step selection]
    Classes --> DispatchRunner[analysis_dispatch_service get_step_runner]
    Catalog -. intended source .-> Consumers[future consumers]
```

의도는 `STEP_MANIFEST` + `STEP_CLASSES`를 `STEP_CATALOG`에서 합쳐 소비자가 catalog만 보는 것이다.

실제는 아직 다음처럼 혼재한다.

| 소비자 | 참조 |
|---|---|
| read model | manifest/catalog 중심 |
| runtime runner binding | `STEP_CLASSES` 직접 merge |
| category selection | manifest helpers |
| LLM model defaults | `llm_client.PIPELINE_STEPS` 별도 |
| frontend display | backend read model/API 결과 |

## Active pipeline 큰 흐름

```mermaid
flowchart TB
    PD[planning_doc_analysis optional] --> Clean[text_cleanup]
    Clean --> Seg[scene_segmentation]
    Seg --> Save[scene_save]
    Seg --> Summary[episode_summary / scene_summary]
    Save --> Beat[beat_extract]
    Beat --> Shot[shot_extract]
    Shot --> Validator[shot_validator]
    Validator --> Entity[entity extraction/merge/detail/t2i]
    Validator --> ShotSel[shot_selection]
    Entity --> Directors[scene_director / shot_director / camera_flow]
    ShotSel --> Directors
    Directors --> Staging[shot_staging]
    Staging --> Detail[scene_detail]
    Detail --> DepT2I[shot_dependency_t2i]
    DepT2I --> T2IReview[t2i_review]
    T2IReview --> Image[image steps]
```

## Active step group

| 그룹 | 대표 step |
|---|---|
| 입력/분해 | `planning_doc_analysis`, `text_cleanup`, `scene_segmentation`, `scene_save` |
| 요약 | `episode_summary`, `visual_world_rules`, `scene_summary` |
| beat/shot | `beat_extract`, `shot_extract`, `shot_validator`, `shot_selection` |
| entity | `entity_character_list`, `entity_all`, `entity_extract_character`, `entity_extract_location`, `entity_extract_prop`, `entity_merge`, `entity_relation`, `entity_filter`, `entity_detail`, `entity_t2i` |
| shot planning | `scene_director`, `shot_director`, `scene_camera_flow`, `shot_dependency`, `shot_dependency_t2i`, `shot_staging`, `shot_essence` |
| outlook | `outlook_phase1`, `outlook_phase2`, `outlook_phase3` |
| scene detail | `scene_consistency`, `scene_detail`, `t2i_review` |
| background Phase 7 | `background_classify`, `background_master_plan`, `floor_plan_prompt`, `floor_plan_render`, `background_prompt`, `background_render` |
| guide/reference | `world_guide`, `ref_image_gen`, `composite_image_gen`, `character_state_variant` |
| final scene | `scene_image_pipeline` |
| utility | `outlook_dedup` |

## Background mode conditional path

현재 배경 생성은 `if_background_mode` 조건을 통해 활성화된다.

```mermaid
flowchart TB
    ShotData[shot_validator + shot_selection] --> Classify[background_classify]
    World[visual_world_rules] --> Classify
    SceneDirector[scene_director] --> Classify
    Classify --> Master[background_master_plan]
    Master --> FPPrompt[floor_plan_prompt]
    FPPrompt --> FPRender[floor_plan_render]
    Master --> BGPrompt[background_prompt]
    FPRender --> BGPrompt
    BGPrompt --> BGRender[background_render]
    BGRender --> SceneImage[scene_image_pipeline]
```

핵심은 `floor_plan_render`와 `background_render`가 image category asset step이라는 점이다. 이 단계는 file 생성과 DB asset registration이 모두 성공해야 completed로 볼 수 있다.

## Deprecated / disabled / removed step

| step | 상태 | 메모 |
|---|---|---|
| `scene_split` | deprecated | v4 flow에서 대체 |
| `scene_cinematography` | deprecated/disabled 계열 | old cinematography |
| `shot_cinematography` | disabled | old path |
| `scene_dependency` | disabled/deprecated | old dependency |
| `outlook_extraction` | on_demand/deprecated | outlook v2/v3 split으로 대체 |
| `location_floor_plan` | disabled/deprecated | Phase 5/old floor plan |
| `background_planner` | deprecated | Phase 7 `background_classify/master_plan`으로 대체 |
| `background_chain_planning` | deprecated/disabled | chain experiment lineage |
| `scene_verify` | disabled/deprecated | editorial old verification |
| `background_chain_render` | disabled/deprecated | chain render experiment |
| `project_summary` | removed | UI legacy compatibility 후보 |

## Editorial step 위험

`t2i_review`는 `entity_t2i`와 `scene_detail` checkpoint를 수정하는 editorial step이다.

```mermaid
flowchart LR
    EntityT2I[entity_t2i checkpoint] --> Review[t2i_review]
    SceneDetail[scene_detail checkpoint] --> Review
    Review --> EntityT2I2[modified entity_t2i]
    Review --> SceneDetail2[modified scene_detail]
    SceneDetail2 --> Downstream[shot_dependency_t2i / image]
```

위험은 다음과 같다.

| 위험 | 설명 |
|---|---|
| downstream invalidation 약함 | editorial 수정 후 어떤 downstream을 stale 처리할지 명확해야 함 |
| provenance 혼동 | 원본 LLM output과 검수 후 output이 같은 step 파일에 공존 가능 |
| partial downstream | 검수 partial 결과가 image step으로 전달될 수 있음 |

## Resume / force / partial 정책

| 정책 | 현재 의미 | 위험 |
|---|---|---|
| resume | checkpoint/hash/schema를 보고 재사용 | verify가 bypass되는 entry path 존재 가능 |
| force | checkpoint archive 후 재실행, downstream invalidation | 2-pass consumes_downstream 예외로 drift 가능 |
| partial | 일부 결과라도 저장 가능 | gate가 partial을 통과시키면 incomplete artifact 소비 |
| blocked | dependency failure cascade | partial은 failed처럼 cascade하지 않음 |
| not_applicable | 조건 불충족 | background mode/shot essence/outlook 여부에 의존 |

## Image step contract

Image step은 일반 transform step보다 contract가 강해야 한다.

| 필요 contract | 이유 |
|---|---|
| expected asset count | prompt/manifest가 만들기로 한 대상 수 |
| file count | PNG/JPG 실제 존재 여부 |
| DB row count | `image_asset` 등록 여부 |
| path resolvability | DB/checkpoint path가 cwd와 무관하게 열리는지 |
| selected filter consistency | selected shot만 생성/등록되는지 |
| parent/reference chain | floor/background/ref/scene dependency path가 유효한지 |

현재 문제는 일부 image step에서 "파일은 있음, DB row 없음" 또는 "step completed, 실제 consumer는 참조 못함" 같은 상태가 가능하다는 점이다.

## 권장 개선 방향

| 우선순위 | 개선 |
|---|---|
| P1 | `STEP_CATALOG`를 runtime dispatch에서도 단일 source로 사용 |
| P1 | `llm_client.PIPELINE_STEPS`와 manifest default_model/provider 통합 |
| P1 | asset step 공통 exit verify base class 도입 |
| P1 | partial downstream 소비 정책을 step별로 명시 |
| P2 | manifest generated doc 자동 갱신을 CI에 포함 |
| P2 | deprecated/disabled step은 UI와 script에서 실행 불가/명시적 override 필요 |
| P2 | background Phase 5/chain experiment와 Phase 7 active path를 문서/코드에서 분리 |