"""通用下载工具：从 URL 下载文件到本地。"""
from __future__ import annotations

from pathlib import Path

import httpx

from app.core.logger import get_logger
from app.core.response import AppError

logger = get_logger(__name__)


def download_file(url: str, dest: str | Path) -> Path:
    """下载 URL 指向的文件到 dest，返回保存路径。"""
    dest = Path(dest)
    dest.parent.mkdir(parents=True, exist_ok=True)
    logger.debug("下载 %s", url)
    try:
        with httpx.Client(timeout=60.0, follow_redirects=True) as client:
            resp = client.get(url)
            resp.raise_for_status()
            dest.write_bytes(resp.content)
    except Exception as exc:  # noqa: BLE001
        logger.error("下载失败: %s: %s", url, exc)
        raise AppError(f"下载失败: {url}: {exc}") from exc
    logger.debug("下载完成: %s (%d bytes)", dest.name, len(resp.content))
    return dest