# Scene Image / Reference Generation Audit

생성일: 2026-05-02 KST  
범위: 배경 이미지 생성, chain background, scene image generation, reference asset injection, DB/file checkpoint 연동  
작업 원칙: 원본 코드, 프롬프트, 기존 문서 수정 없음. 이 폴더의 신규 감사 문서만 생성.

## 문서 목록

- [01_execution_flow.md](./01_execution_flow.md): 활성 실행 경로, deprecated/orphan 경로 구분, StepRunner 흐름, 실패 시퀀스 다이어그램.
- [02_db_filesystem_state.md](./02_db_filesystem_state.md): PostgreSQL 현재 상태, 오늘 생성된 이미지/에셋 상태, checkpoint/manifest 관찰.
- [03_code_audit.md](./03_code_audit.md): 관련 코드 전수 감사 결과. path invariant, background render, scene pipeline, reference service 포함.
- [04_prompts_settings_tests.md](./04_prompts_settings_tests.md): 프롬프트 계약, 설정 토글, 테스트 커버리지와 누락 지점.
- [problems.md](./problems.md): 결함/리스크만 분리한 문제 목록. 심각도, 영향, 증거, 권장 방향 포함.

## 핵심 결론

현재 로컬 PostgreSQL 상태만 보면 `variant_label` 컬럼은 `VARCHAR(255)`로 확장되어 있고, `chain_bg` DB row도 존재하며, selected scene still 64개는 모두 primary scene asset을 가지고 있다. 즉 현재 DB는 “씬 이미지가 하나도 없음” 상태에서는 복구된 것으로 보인다.

그러나 코드 경로에는 여전히 재발 가능한 결함이 남아 있다. 가장 위험한 경로는 `scene_image_pipeline` force 실행 시 기존 scene primary를 먼저 해제한 뒤 새 이미지 생성/저장에 실패하는 경우다. 이때 새 primary가 생기기 전까지 DB는 selected still 기준 scene primary 0개 상태가 될 수 있다.

`background_render` 쪽의 과거 결함인 `variant_label VARCHAR(32)` truncation과 chain_bg 등록 실패 silent 처리 문제는 현재 코드/DB 기준 상당 부분 수정되어 있다. 다만 migration 미적용 환경, checkpoint raw path, scene pipeline 검증 부재, prompt ID 계약 충돌은 별도 위험으로 남아 있다.

## 전체 데이터 흐름

```mermaid
flowchart TD
    FP[floor_plan_render<br/>floor_plan ImageAsset] --> BG[background_render<br/>chain_bg PNG 생성]
    BG --> BGDB[(ImageAsset<br/>asset_type=chain_bg)]
    BG --> BGMAN[checkpoint manifest<br/>background_render/manifest.json]
    REF[ref_image_gen<br/>entity reference ImageAsset] --> REFDB[(ImageAsset<br/>reference)]
    DETAIL[scene_detail<br/>selected still + prompt ids] --> SCENE[scene_image_pipeline]
    BGMAN --> LOADBG[scene_checkpoint_loaders<br/>chain_bg map]
    BGDB --> BGVERIFY[background_render.verify_completion]
    REFDB --> SREF[scene_reference_service]
    LOADBG --> COORD[scene_generation_coordinator]
    SREF --> COORD
    SCENE --> COORD
    COORD --> SDB[(ImageAsset<br/>asset_type=scene)]
    COORD --> SFILES[scene PNG files]
```

## 활성 코드와 orphan 코드 구분

이 감사에서 “orphan”은 파일이 남아 있거나 registry에 import되어도 현재 manifest에서 disabled/deprecated 처리되어 기본 실행 경로가 아닌 것을 의미한다. 특히 `background_chain_render`는 과거 Phase 5 legacy 단계이며, 현재 핵심 실행 경로는 Phase 7 `background_render`다.

| 구분 | 단계/파일 | 상태 | 감사 판단 |
| --- | --- | --- | --- |
| 활성 | `background_render` / `background_render_step.py` | enabled | chain_bg 생성 및 DB 등록의 현재 핵심 경로 |
| 활성 | `scene_image_pipeline` / `image_steps.py` + services | enabled | scene 이미지 생성/primary 등록 핵심 경로 |
| 활성 | `scene_reference_service.py` | enabled | entity/reference map 구성 |
| 활성 | `scene_checkpoint_loaders.py` | enabled | background chain map 주입 |
| deprecated | `background_chain_render` | disabled/deprecated | 과거 비교/legacy 경로. 원인 분석 참고용 |
| 비교군/실험 | `experiment_*` scripts | 직접 pipeline 아님 | 실험 코드. 운영 pipeline 원인과 분리 필요 |