"""file-backed spool — 생성 이미지 바이트를 temp 파일에 기록 (Task A3).

이미지는 1~3MB라 메모리 큐가 폭증한다. 저수준 capture 는 바이트를 spool 파일에
기록만 하고, 큐엔 ``spool_path + metadata`` 만 적재한다. step/runner finally 에서
CaptureQueue.flush 가 spool 파일을 최종 generated 경로로 rename 한다.

경로: ``projects_root/.capture_spool/<project>/<uuid>.png``
(projects_root = ``Path(settings.projects_dir).parent`` — file_paths/pipeline_graph
관례와 동일).
"""

from __future__ import annotations

import uuid
from pathlib import Path


def _spool_root() -> Path:
    from app.core.config import settings

    return Path(settings.projects_dir).parent / ".capture_spool"


def write_spool(png_bytes: bytes, project_id: str, stage: str) -> str:
    """이미지 바이트를 spool 파일에 기록하고 절대 경로(str)를 반환한다.

    Args:
        png_bytes: 생성된 이미지 raw 바이트.
        project_id: 프로젝트 격리용 서브디렉터리.
        stage: 호출자 단계명 — 현재 spool 경로엔 미사용(메타로 전달되어
            최종 rename 경로에 반영). 시그니처 일관성/디버그용으로 보존.

    Returns:
        기록된 spool 파일의 절대 경로 문자열. 매 호출 uuid 라 충돌 없음.
    """
    spool_dir = _spool_root() / project_id
    spool_dir.mkdir(parents=True, exist_ok=True)
    path = spool_dir / f"{uuid.uuid4().hex}.png"
    path.write_bytes(png_bytes)
    return str(path)