"""API 响应格式工具，保证成功响应拥有一致的 JSON 结构。"""

from datetime import UTC, datetime
from typing import Any

from fastapi import Request


def utc_server_time() -> str:
    """返回毫秒精度的UTC时间，供API包络统一使用。"""
    return datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")


def success_response(request: Request, data: Any) -> dict[str, Any]:
    """包装业务数据，并附上当前请求的追踪ID和服务器时间。"""
    return {
        "success": True,
        "data": data,
        "meta": {
            "request_id": request.state.request_id,
            "server_time": utc_server_time(),
        },
    }