# Prompts / Settings / Tests Audit

## Prompt Contract Overview

```mermaid
flowchart TD
    FP[floor_plan_prompt] --> BG[background_prompt]
    BM[background_master_plan] --> BG
    BC[background_classify] --> BG
    SD[scene_detail] --> T2I[shot_dependency_t2i]
    REF[reference prompts] --> REFIMG[ref_image_gen]
    BG --> SCENE[scene_image_pipeline prompt]
    REFIMG --> SCENE
    T2I --> SCENE
```

## Background Prompts

관련 prompt:

- `prompts/_base/background_master_plan/*`
- `prompts/_base/background_prompt/*`
- `prompts/_base/background_classify/*`

관찰:

| 항목 | 판단 |
| --- | --- |
| `background_prompt` | floor plan/prior background reference를 받아 scene용 photoreal background 생성 |
| people/faces | background prompt 계열에서 금지 방향 |
| floor plan | layout source로 사용, top-down render가 아니라 interior/exterior background로 변환 |
| `state_label` | JSON schema에서 충분한 maxLength 제한이 없으면 DB label 길이와 충돌 가능 |

현재 DB는 `variant_label VARCHAR(255)`라 35~38자 label은 통과한다. 하지만 prompt/schema 레벨에서 label 길이를 제한하지 않으면 DB migration이 덜 된 환경이나 다른 label 컬럼에서 같은 사고가 반복될 수 있다.

## Scene Detail Prompt ID 충돌

가장 중요한 prompt 계약 문제다.

| 위치 | 지시 | 충돌 |
| --- | --- | --- |
| `scene_detail/detail_schema.json` | `t2i_prompt`는 bare `C01`만 사용, composite `C01O02` 금지 | outfit/composite reference 직접 지정 불가 |
| `scene_detail/system.md` | `C01O02` 같은 outfit/composite ID를 직접 쓰라는 지시 존재 | schema와 반대 |
| `prompt_service.py` | `C##O##`, bare `C##`, `P##`를 각각 reference image로 치환 | prompt ID 형태에 따라 붙는 이미지가 달라짐 |

이 충돌은 “참조 이미지가 생성되어 있는데 scene prompt에 안 들어감”의 직접 원인이 될 수 있다. schema가 bare character만 허용하면 outfit-specific reference가 누락될 수 있고, system이 composite ID를 요구하면 schema strict 검증과 모델 출력이 충돌한다.

## Settings

관련 파일:

- `backend/app/config.py`
- `.env`

중요 설정:

| 설정 | 의미 | 주의 |
| --- | --- | --- |
| `BACKGROUND_MODE` | background generation 방식 선택 | `phase7`이어도 injection이 자동 on은 아님 |
| `BACKGROUND_CHAIN_ENABLED` | scene prompt에 chain_bg reference 주입 | false면 생성된 background가 scene에 안 들어감 |
| `CHAIN_BG_GUIDE_ENABLED` | chain background guide 사용 | prompt/control 영향 |
| `CHAIN_BG_CAMERA_META_ENABLED` | camera metadata 사용 | shot framing consistency 영향 |

`BACKGROUND_MODE=phase7`은 background를 만드는 설정이고, `BACKGROUND_CHAIN_ENABLED=true`는 그 background를 scene prompt에 참조 이미지로 넣는 설정이다. 두 설정을 분리해서 봐야 한다.

```mermaid
flowchart LR
    A[BACKGROUND_MODE=phase7] --> B[background_render 실행]
    C[BACKGROUND_CHAIN_ENABLED=true] --> D[scene prompt ref injection]
    B --> E[chain_bg files]
    E --> D
```

## DB/Prompt Boundary

prompt는 semantic id와 label을 만들고, DB는 이를 저장 가능한 길이와 path invariant로 받아야 한다. 현재 사고 계열은 이 boundary가 느슨한 데서 반복된다.

| Boundary | 현재 문제 |
| --- | --- |
| prompt label -> DB column | label maxLength와 DB column 길이 불일치 가능 |
| prompt ID -> reference map | bare/composite ID 계약 충돌 |
| prompt background id -> checkpoint map | 설정 off/path 실패 시 주입 누락 |
| prompt success -> DB asset | image generation failure가 None/empty로 약화 가능 |

## Tests Coverage

관찰된 테스트 경향:

| 영역 | 있는 테스트 | 부족한 테스트 |
| --- | --- | --- |
| `background_render.verify_completion` | chain_bg 검증 테스트 존재 | migration 미적용 DB, long label E2E |
| path helper | 일부 상대/절대 path 테스트 존재 | checkpoint JSON raw relative path + cwd 변경 |
| scene reference service | mock/tmp_path 기반 테스트 존재 | 실제 PostgreSQL + selected still + real path 통합 |
| scene pipeline | generation/service mock 중심 | force pre-clear 후 generation 실패 rollback 보장 |
| prompt ID | prompt replacement 단위 테스트 가능 | schema/system ID 계약 충돌 E2E |

테스트에서 `tmp_path` 절대 경로와 mock DB를 많이 쓰면 production에서 발생하는 cwd/path/DB column 문제가 통과할 수 있다. 특히 다음 테스트 축이 필요하다.

1. selected scene primary가 존재하는 상태에서 force 실행 중 generation 실패 시 기존 primary가 유지되는지.
2. checkpoint manifest에 상대 `png_path`가 들어 있고 cwd가 프로젝트 root가 아닐 때도 background chain map이 정상 로드되는지.
3. `variant_label` 32자 초과 값이 실제 PostgreSQL schema에서 insert 가능한지.
4. scene prompt에 `C01`, `C01O02`, `P01`, `chain_bg:*`가 섞일 때 실제 inline images가 기대 수만큼 붙는지.
5. `scene_image_pipeline` completed 상태에서 selected still별 primary/file이 누락되면 exit verify가 실패하는지.

## Recommended Contract Direction

권장 방향은 prompt, schema, DB, resolver가 하나의 계약을 공유하도록 만드는 것이다.

| 계약 | 권장 |
| --- | --- |
| character id | bare `C##`와 outfit `C##O##`를 명시적으로 분리 |
| prop id | `P##`만 허용하고 name fallback은 보조로만 |
| background id | `chain_bg:<variant_type>` 형태로 고정 |
| label length | prompt schema에서 maxLength를 DB보다 짧게 제한 |
| path | DB/checkpoint 모두 project-root-relative 저장, read 시 helper 강제 |