# Problem List

이 문서는 결함과 재발 리스크만 분리한다. `active`는 현재 기본 실행 경로, `legacy`는 deprecated/orphan 경로, `fixed-current`는 현재 코드/DB 기준 수정 확인된 항목이다.

## P0-1. scene force 실행이 기존 primary를 먼저 해제함

| 항목 | 내용 |
| --- | --- |
| 상태 | active / remaining |
| 위치 | `backend/app/core/steps/image_steps.py`, `scene_image_pipeline` |
| 영향 | 새 scene 이미지 생성 실패 시 selected still의 기존 primary scene asset이 0개가 될 수 있음 |
| 증거 | force mode에서 selected still 기존 primary를 false로 만든 뒤 checkpoint 삭제와 generation 진행 |
| 권장 | 새 이미지 파일 생성, DB insert, file exists 검증, selected still별 complete set 확보 후 transaction으로 primary swap |

## P0-2. scene_image_pipeline exit verify 부재

| 항목 | 내용 |
| --- | --- |
| 상태 | active / remaining |
| 위치 | `backend/app/core/steps/image_steps.py`, `backend/app/core/step_runner.py` |
| 영향 | selected still별 scene primary/file 누락이 completed로 통과 가능 |
| 증거 | `background_render`에는 verify override가 있으나 `scene_image_pipeline`은 base verify 사용 |
| 권장 | selected still 전체에 대해 `ImageAsset(asset_type='scene', is_primary=true)`와 file exists를 검증하는 `verify_completion()` 추가 |

## P0-3. generation failure가 None/empty result로 약화됨

| 항목 | 내용 |
| --- | --- |
| 상태 | active / remaining |
| 위치 | `scene_image_service.py`, `scene_generation_coordinator.py` |
| 영향 | image generation 실패가 batch continue로 흡수되어 scene 누락이 partial/completed 왜곡으로 이어질 수 있음 |
| 증거 | variation 실패 시 `None`, empty `var_results_list`는 continue 경로 존재 |
| 권장 | selected still에서 required variation 0개면 hard fail. 실패 사유를 step_run error_message와 checkpoint에 남김 |

## P1-1. StepRun error_message가 비어 있을 수 있음

| 항목 | 내용 |
| --- | --- |
| 상태 | active / remaining |
| 위치 | `backend/app/core/step_runner.py` |
| 영향 | UI/로그에서 실패 원인을 추적하기 어려움 |
| 증거 | failed_count 기반 partial/failed 경로에서 explicit error_message가 없으면 NULL 가능 |
| 권장 | failed_count > 0이면 synthetic summary error를 저장. AppError 문자열이 비어도 code/context를 저장 |

## P1-2. completed resume short-circuit가 검증을 우회할 수 있음

| 항목 | 내용 |
| --- | --- |
| 상태 | active / remaining |
| 위치 | `backend/app/core/services/step_execution_service.py`, `step_runner.py` |
| 영향 | 과거 silent completed 상태가 남아 있으면 재실행 시 exit verify 없이 skipped 처리 가능 |
| 증거 | service layer에서 completed/schema/hash만 보고 resume skip하는 경로 존재 |
| 권장 | completed skip 전에도 step-specific verify를 lightweight로 실행하거나, 핵심 asset step은 verify-clean checkpoint marker를 요구 |

## P1-3. checkpoint config_hash 계산 기준 불일치

| 항목 | 내용 |
| --- | --- |
| 상태 | active / remaining |
| 위치 | `backend/app/core/step_runner.py`, background/floor plan step checkpoint |
| 영향 | 입력이 바뀌지 않았는데 stale/force로 오판되거나, 반대로 step-local 변화 감지가 약해질 수 있음 |
| 증거 | checkpoint 저장 시 step-provided `config_hash`를 보존하지만 mismatch 검사에서는 `project_config` hash를 재계산 |
| 권장 | step별 hash provider를 명시화하고 save/check 모두 같은 함수를 사용 |

## P1-4. checkpoint raw path가 cwd에 의존할 수 있음

| 항목 | 내용 |
| --- | --- |
| 상태 | active / remaining |
| 위치 | `scene_checkpoint_loaders.py`, reference checkpoint consumers |
| 영향 | DB path는 정상이어도 manifest/checkpoint path가 cwd 변경 시 존재하지 않는 것으로 판단되어 background/reference map이 비어질 수 있음 |
| 증거 | JSON path는 `ImagePathType`을 거치지 않고 `Path(...)` 직접 처리되는 경로 존재 |
| 권장 | checkpoint path도 project-root-relative로 저장하고 읽을 때 `resolve_image_path()` 강제 |

## P1-5. scene_detail prompt ID 계약 충돌

| 항목 | 내용 |
| --- | --- |
| 상태 | active / remaining |
| 위치 | `prompts/_base/scene_detail/12.202605021300/detail_schema.json`, `system.md`, `prompt_service.py` |
| 영향 | outfit/composite reference image가 생성되어도 scene prompt에 붙지 않을 수 있음 |
| 증거 | schema는 bare `C##` 중심/`C##O##` 금지, system은 `C##O##` 직접 사용 지시 |
| 권장 | schema와 system을 하나로 통일. resolver가 지원하는 ID 형태를 prompt contract로 명문화 |

## P1-6. background 생성과 scene 주입 설정이 분리되어 있음

| 항목 | 내용 |
| --- | --- |
| 상태 | active / operational risk |
| 위치 | `backend/app/config.py`, `.env`, `scene_checkpoint_loaders.py` |
| 영향 | background PNG가 생성되어도 `BACKGROUND_CHAIN_ENABLED=false`면 scene prompt에 참조 이미지가 안 들어감 |
| 증거 | `BACKGROUND_MODE`와 `BACKGROUND_CHAIN_ENABLED`는 별도 설정 |
| 권장 | phase7 background를 쓰는 프로젝트에서는 chain injection 상태를 startup validation으로 확인 |

## P2-1. `variant_label VARCHAR(32)` truncation은 현재 수정됐지만 migration 의존

| 항목 | 내용 |
| --- | --- |
| 상태 | fixed-current / migration risk |
| 위치 | `project.py`, `database.py`, `alembic/versions/004_variant_label_extend.py` |
| 영향 | migration 미적용 환경에서는 chain_bg insert 전부 실패 가능 |
| 증거 | 현재 DB는 `VARCHAR(255)`, longest observed label 38 |
| 권장 | startup schema check hard fail. prompt schema maxLength도 255보다 낮게 제한 |

## P2-2. chain_bg DB sync silent failure는 현재 개선됐지만 회귀 방지 필요

| 항목 | 내용 |
| --- | --- |
| 상태 | fixed-current / regression risk |
| 위치 | `background_render_step.py` |
| 영향 | DB insert 실패가 completed로 저장되면 scene 단계에서 background DB 검증/추적이 깨짐 |
| 증거 | 현재 코드는 `[BG_RENDER_SYNC_FAIL]` raise와 verify_completion 존재 |
| 권장 | unit/integration test로 DB insert exception이 step failed/partial이 되는지 고정 |

## P2-3. floor_plan_render DB sync continue 가능성

| 항목 | 내용 |
| --- | --- |
| 상태 | active / needs follow-up |
| 위치 | `floor_plan_render_step.py` |
| 영향 | root anchor floor plan이 DB에 없으면 background root가 text-only fallback으로 갈 수 있음 |
| 증거 | DB sync 예외를 log/rollback 후 계속하는 경로가 남아 있는 것으로 분석됨 |
| 권장 | floor_plan ImageAsset 등록 실패도 hard fail로 통일 |

## P2-4. reference generation completed count 해석이 모호함

| 항목 | 내용 |
| --- | --- |
| 상태 | active / design risk |
| 위치 | `reference_pipeline_orchestrator.py`, `reference_phase1_service.py`, `episode_projection_service.py` |
| 영향 | `completed 27/46 failed 0` 같은 상태가 실제 필요한 entity ref 누락인지 skip인지 바로 구분 어려움 |
| 증거 | low-frequency skip, already_done checkpoint merge, prompt appearance count 기반 batch 구성 |
| 권장 | selected scene prompt에서 요구한 ID 기준 required reference coverage report 생성 |

## P2-5. `set_primary_asset` scope 검증 약함

| 항목 | 내용 |
| --- | --- |
| 상태 | active / remaining |
| 위치 | `scene_persistence_service.py` |
| 영향 | 잘못된 asset id 또는 file missing row가 primary로 지정될 수 있음 |
| 증거 | asset_id 중심 update, project/still/file existence 검증이 약함 |
| 권장 | project_id, still_id, asset_type, file exists, rowcount를 모두 검증한 뒤 primary 설정 |

## P3-1. 테스트가 production path/DB 현실을 충분히 재현하지 않음

| 항목 | 내용 |
| --- | --- |
| 상태 | active / test gap |
| 위치 | `backend/tests/**` |
| 영향 | tmp_path 절대 경로와 mock DB에서는 cwd/raw checkpoint/PostgreSQL column 문제가 통과 |
| 증거 | 여러 서비스 테스트가 tmp_path/MagicMock 중심 |
| 권장 | PostgreSQL integration, cwd 변경, raw checkpoint relative path, force failure E2E 테스트 추가 |

## P3-2. file_path invariant가 DB schema에서 강제되지 않음

| 항목 | 내용 |
| --- | --- |
| 상태 | active / architectural risk |
| 위치 | `ImageAsset.file_path`, `ImagePathType`, checkpoint writers |
| 영향 | producer별 ad-hoc path format이 계속 생김 |
| 증거 | DB column은 string이며 checkpoint path는 별도 규칙 없음 |
| 권장 | DB에는 project-root-relative만 허용. 절대 path passthrough는 debug escape hatch로 제한 |

## 우선순위 권장

1. `scene_image_pipeline.verify_completion()` 추가.
2. force mode primary swap을 원자적 교체 방식으로 변경.
3. generation None/empty result를 selected still 기준 hard fail로 승격.
4. prompt ID 계약을 schema/system/resolver 기준으로 통일.
5. checkpoint raw path를 모두 `resolve_image_path()` 경유로 통일.
6. PostgreSQL + cwd 변경 + force failure 통합 테스트 추가.