전 과정 생성 이미지 DB 영속화 (All Generated Images → image_asset)

1. 목표 / 비목표

목표

• 파이프라인 실행 중 모델이 생성하는 모든 이미지 바이트를 빠짐없이 image_asset으로 영속화(중간물 포함).
• 각 영속화 행에 lineage(생성 입력 관계)와 stage/role(어느 단계·용도)를 부착 → 캔버스가 정확한 노드·엣지로 표현.
• 기존 이미지 생성 파이프라인의 동작·산출물·성능을 깨지 않음(capture 실패는 항상 non-fatal).

비목표 (YAGNI / 후속)

• 캔버스에서의 실제 수정/재생성/제어 기능 — 이번 범위 아님(데이터를 제어 가능하게 "쌓는" 것까지). UI 제어는 별도 후속.
• 과거 프로젝트의 checkpoint-only 산출물 대량 backfill — 옵션(§9). 1차는 forward capture.
• 이미지 바이트의 중복 저장 제거/GC — 후속(디스크 증가는 수용, 사용자 명시).

2. 현재 상태 (감사 결과)

이미지는 단일 image_asset(backend/app/models/project.py:150)에 저장된다. 최종물만 등록되고 중간물은 temp/checkpoint에 저장 후 버려진다.

핵심 realization. 모든 이미지 생성 호출의 메타(프롬프트·참조 라벨·still_id·operation_type)는 이미 llm_call_log에 기록된다(image_tracer 통합). 빠진 건 출력 이미지 자체를 조회 가능한 image_asset으로 남기는 것뿐이다.

모델 호출 진입점 (계측 대상)

3. 접근안 (A안 채택 — 사용자 승인)

4. 아키텍처 (A안)

4.1 GenerationContext (contextvars)

파이프라인 스텝/서비스가 자기 작업을 with generation_context(...)로 감싼다. sink가 ambient로 읽어 lineage를 채운다. 설정 없으면(미배선 경로) sink는 최소 메타로라도 포착(누락 0).

@dataclass
class GenContext:
    project_id: str
    episode_id: str | None
    stage: str                 # 파이프라인 단계 (step name): "background_render", "pose_guide", ...
    role: str                  # 용도: "aerial_base"|"shot_blocking"|"pose_guide"|"composition_guide"|
                               #       "anchor_sketch"|"candidate"|"i2i_step"|"final_*"
    still_id: str | None
    scene_index: int | None; shot_index: int | None
    entity_id: str | None
    source_image_ids: list[str]   # i2i/ref 입력 자산 UUID (엣지 형성)
    is_intermediate: bool
    candidate_index: int | None

# contextvar — set/reset 은 contextmanager 로. 비어 있으면 None.
_gen_ctx: ContextVar[GenContext | None]

4.2 capture sink

def capture_generated_image(png_bytes, *, db, gen_call_id=None, override=None) -> str | None:
    """생성된 이미지 바이트를 파일로 저장 + image_asset 행 삽입. 실패 시 None(절대 raise 안 함)."""
    ctx = current_gen_context() merged with override
    if ctx is None or ctx.is_final:   # 최종물은 기존 _register_image_assets 가 담당(중복 방지)
        return None
    path = projects//episodes//images/generated//.png
    write file (+ thumb)
    row = ImageAsset(asset_type='generated', stage=ctx.stage, pipeline_role=ctx.role,
                     is_intermediate=True, entity_id, still_id, shot_index,
                     source_image_id=first(ctx.source_image_ids),
                     reference_image_ids=json(ctx.source_image_ids),
                     generation_call_id=gen_call_id, candidate_index, variant_label=ctx.role,
                     file_path=path, prompt_used=ctx.prompt, status='generated')
    db.add(row); db.flush()
    return row.id

4.3 계측 지점 (3 진입점)

1. Gemini: GeminiImageClient.generate_image 반환부에서 capture_generated_image(out_bytes) 호출(이미 image_tracer 있는 자리 옆). DB 세션 접근이 필요 → §6 참고(세션 주입 또는 deferred queue).
2. gpt-image-2: 분산된 openai_client.images.generate/edit를 단일 wrapper generate_gpt_image(...)로 중앙화(새 모듈)하고, 그 wrapper에서 capture. 기존 호출부(location_floor_plan/outdoor_site_layout_provider/registered_pose_guide 등)는 wrapper 사용으로 치환.
3. fal: apply_fal_angle 반환부에서 capture.

중복(dedup). 최종물(reference/fp/chain_bg/scene/composite)은 기존 _register_image_assets/서비스가 이미 image_asset을 만든다. sink가 같은 바이트를 또 만들면 2행이 된다. 규칙: GenContext.role 이 final_* 또는 컨텍스트가 "최종 등록 예정"이면 sink는 skip. 즉 sink는 중간물만 포착. (대안: sink가 모든 것을 만들고 최종 등록은 "promote"로 전환 — 큰 리팩토링이라 1차 제외.)

4.4 lineage / 엣지

캔버스 엣지는 source_image_id / reference_image_ids / still_id 구조키로 형성된다(이미 구현됨). 따라서 GenContext.source_image_ids를 스텝이 채우면 중간물도 자동으로 상류 엣지를 갖는다. 예: 포즈 가이드는 source=[배경 plate, 등록 마네킹 base], 항공뷰 base는 source 없음(루트), 블로킹은 source=[항공뷰 base], 씬 스틸은 source=[블로킹/스케치, 배경, char/outlook ref...].

5. 스키마 변경 (alembic 1개)

image_asset에 nullable 컬럼 소량 추가. 기존 컬럼(source_image_id/parent_image_id/reference_image_ids/still_id/shot_index/prompt_used)은 재사용.

asset_type에 신규 값 'generated' 추가(또는 role을 type로). 캔버스 nodeStyle가 stage/role로 색/라벨 매핑. 마이그레이션은 add-column만(삭제 0, drift 없음 — 부팅 fail-fast 통과).

6. 안전성 / 트랜잭션 (★중요)

• non-fatal: capture 전체를 try/except로 감싸 어떤 실패도 생성 파이프라인을 막지 않음(로그만).
• DB 세션: 저수준 모델 호출(generate_image)에는 보통 DB 세션이 없다. 옵션 (a) capture를 호출부(스텝, 세션 보유)에서 수행 — 진입점 계측 대신 "스텝이 결과 바이트를 sink에 넘김"; 또는 (b) deferred queue(contextvar에 (bytes, ctx) 적재 → 스텝 경계에서 flush). 권고: (b) deferred — 저수준 함수는 큐에 적재만, 스텝 트랜잭션 커밋 시 일괄 영속화. 생성 경로에 DB 의존성·지연을 안 준다.
• 성능: 파일 쓰기/썸네일은 이미 하는 작업(중간물도 어차피 디스크에 씀). 추가 비용은 DB insert N행/스텝 — 미미.
• idempotency: resume/재실행 시 같은 중간물 재생성 → 새 행(또는 generation_call_id+role+candidate로 upsert). 1차는 append(중복 허용, 사용자 수용), 후속 정리.

7. 캔버스(소비자) 변경

• 신규 stage/pipeline_role/is_intermediate 노드 렌더: 색·라벨·아이콘(nodeStyle 확장), 중간물 그룹/필터(기본 접기 토글).
• 아웃룩 엣지 누락 수정: 현재 reference_image_ids는 char/prop만 담아 outlook이 엣지 없이 떠 있음. 영속화 시 outlook ref도 source에 포함하거나, 캔버스가 별도 구조키로 outlook→씬 엣지 형성.
• 아웃룩 노드 색/범례 추가(현재 회색 default).
• virtual placeholder 로직 → 실제 thumb_url/full_url 있으면 이미지 표시(Codex 권고).

8. 단계 계획 (writing-plans 에서 상세화)

1. 스키마 마이그레이션(add-column) + ImageAsset 모델 필드.
2. GenContext(contextvars) + deferred capture queue + capture sink(non-fatal) + 결정론 단위테스트(컨텍스트→행 매핑, dedup skip, 실패 무해).
3. 모델 진입점 계측: Gemini generate_image / gpt-image 중앙 wrapper / fal. (gpt-image 중앙화 리팩토링 포함)
4. 주요 스텝에 generation_context(...) 배선(stage/role/source 채움) — 우선 가이드/스케치/항공뷰/블로킹/후보부터.
5. 실데이터 E2E(작은 에피소드 재생성) → 중간물 행 생성·lineage 육안 → 캔버스에서 전 과정 표시.
6. 캔버스 소비자 업데이트(stage 색/필터, 아웃룩 엣지/색).
7. Codex 리뷰(메인 코드라 Claude 구현·Codex 검토만) → 사용자 GO → 커밋.

9. 미해결 / 리스크

• backfill: 과거 프로젝트의 checkpoint-only 산출물을 소급 등록할지(옵션, 후속).
• dedup vs promote: 1차는 "최종물=기존 등록 / 중간물=sink" 분리. 장기적으로 sink 단일화(promote) 검토.
• 저장 폭증: 모든 후보/i2i까지 → 디스크/DB 행 급증. 사용자 수용. 후속 GC/보존정책 여지.
• gpt-image 중앙화가 기존 호출부(fp/aerial/pose) 동작을 바꾸지 않도록 byte-identical 검증 필요.

10. Codex 리뷰 반영 (2026-06-30) — APPROVED_DIRECTION_WITH_REQUIRED_REFINEMENTS

Codex가 설계서 + 실제 코드 진입점을 추적해 A안 방향을 승인하고, "전부 영속화"를 실제로 만족시키기 위한 필수 보강 5건을 요구했다. 아래가 §4·§5·§6·§8 대비 우선한다.

10.1 deferred queue → file-backed + worker 전파 + finally flush + 독립 세션

• worker 컨텍스트 전파: scene/image 경로는 worker thread가 많아 contextvars가 자동 전파 안 됨. image_tracer.set_context / budget bind 패턴처럼 GenerationContext + queue handle을 worker에 명시 전파.
• file-backed 큐: 이미지 1~3MB라 메모리 큐 폭증. 저수준 capture는 temp/spool 파일에 바이트 기록, 큐엔 temp_path + metadata만. step/runner finally에서 DB row insert + final generated path로 rename.
• finally flush: 성공 path만이 아니라 step finally에서 flush. 사용자가 "거부 후보까지 전부" 원하므로 step이 partial/failed여도 생성된 candidate는 남아야 함. business transaction rollback에 말려 사라지면 안 됨 → capture flush는 독립 non-fatal 세션.
• flush scope 없을 때: silent drop 금지, diagnostic counter(capture_skipped_no_context / capture_skipped_no_flush_scope) 기록 → 누락 감사 가능.

10.2 dedup → explicit intermediate capture policy (role 문자열 금지)

• role.startswith('final_') 같은 문자열 규칙 금지(사고 위험). 기본 capture_enabled=False — 명시적으로 intermediate capture scope가 열린 호출만 sink 저장. (GeminiImageClient는 reference/scene final도 전부 통과 → default-capture면 즉시 중복.)
• 최종물은 기존 _register_image_assets 유지 + intermediate만 sink. promote 단일화는 1차 defer(동의).
• 필수 테스트: "final reference/scene 호출이 sink 계측 후에도 image_asset 중복 0".

10.3 schema → reference_image_ids 의미 오염 금지 + 신규 컬럼

• 현재 ImageAsset.reference_image_ids = "visible char/prop UUID lineage"(pipeline_graph_service가 reference edge 복원에 사용). intermediate의 bg/guide/sketch 입력을 여기 넣으면 reference lineage로 오염됨.
• 신규 컬럼 input_image_ids(또는 source_image_ids_json, Text JSON)에 전체 입력 관계 저장. source_image_id는 primary/first source로 유지.
• 신규 pipeline_metadata_json(group_id, checkpoint key, rejection reason, model params, prompt hash 등 — 앞으로 늘어남).
• 캔버스 색/그룹 SOT = asset_type이 아니라 pipeline_role.
• 인덱스: (project_id, episode_id, is_intermediate), generation_call_id, (project_id, episode_id, pipeline_role).
• migration = idempotent alembic inspector 패턴. ImageAsset 모델/스키마/graph service를 같은 커밋에서 일치(startup fail-fast 충돌 방지).

10.4 진입점 — "3개"는 누락. 실제 audit 결과

• gpt-image direct 호출이 더 넓음: location_floor_plan.generate_floor_plan_image(공통 래퍼화됨) 외에 background_render.py, background_chain_render.py, floor_plan_render.py, space_set_bg_provider.py에 direct OpenAI 호출 잔존.
• Gemini도 단일 아님: gemini_i2i_editor.py가 GeminiImageClient 안 거치고 직접 REST 호출 후 b64 decode(scene variation / angle edit 경로).
• FAL = apply_fal_angle 단일 ✓.
• 비모델 PIL/결정론 산출물: registered pose underlay, zoom crop, space_set marking, outdoor birdseye render 등 → 모델 sink와 별도 capture_artifact_bytes/path(...) API 필요(없으면 항공뷰/마스크/underlay 누락).

10.5 gpt-image 중앙화 → 저수준 primitive wrapper (고수준 통합 금지)

• 각 호출부가 retry/sanitizer/ref validation/out_path/return을 다르게 가짐 → 1차에 고수준 통합하면 byte-identical 리스크 큼.
• primitive wrapper call_gpt_image_bytes(openai_client, prompt, images/ref_paths, model, size, quality, budget_source, capture_context)만 신설 — API 호출 + b64 decode + capture enqueue만. 기존 retry/sanitizer/out_path write는 각 호출부에 남김. budget source label 기존값 유지(background_render.edit_single 등 → 운영 로그 불변). 고수준 정리는 별도 wave.

10.6 확정 구현 순서 (Codex 권고)

1. A: schema + GenContext + file-backed deferred queue + capture_artifact API 만 먼저 + 단위테스트(결정론).
2. B: GeminiImageClient + gemini_i2i_editor + FAL + gpt primitive wrapper 계측. gpt direct call sites 전부 wrapper로 치환(고수준 동작 유지, audit checklist로 잠금).
3. C: 주요 intermediate(registered pose guide / outdoor aerial-base-blocking-sketch / zoom crop)에 explicit context 배선 → E2E로 DB row + canvas edge 확인.
4. D: 전체 호출부 확장.

최대 리스크(Codex): "전부라 했는데 non-model/PIL 산출물·일부 direct image call이 빠지는 것" + "reference_image_ids 의미 오염으로 캔버스 edge가 섞이는 것". → 10.3/10.4로 봉쇄.

— 끝. A안 + 캔버스 선커밋(완료) + Codex 필수보강(§10) 반영. writing-plans 로 구현 계획서(Phase A부터)를 작성한다.