<?php

namespace Kylin\Core;

use Illuminate\Http\JsonResponse;
use Illuminate\Pagination\LengthAwarePaginator;
use Kylin\Core\Traits\HasTraceId;

/**
 * 统一 API 响应格式
 *
 * 提供标准化的 JSON 响应结构，所有响应均包含：
 *  - code：业务错误码（SUCCESS 表示成功）
 *  - message：面向用户的提示信息
 *  - data：业务数据（可为 null）
 *  - trace_id：请求追踪 ID（通过 X-Trace-Id 请求头传递）
 *
 * 支持的响应类型：
 *  - success()：通用成功响应
 *  - paginate()：分页响应
 *  - created()：资源创建成功响应（HTTP 201）
 *  - noContent()：无内容响应（HTTP 204）
 *  - error()：错误响应
 */
class ApiResponse
{
    use HasTraceId;

    /**
     * 通用成功响应
     *
     * @param  mixed   $data    响应数据
     * @param  string  $message 提示信息
     * @return JsonResponse
     */
    public static function success(mixed $data = null, string $message = '操作成功'): JsonResponse
    {
        return response()->json([
            'code' => config('kylin-core.response.success_code', 'SUCCESS'),
            'message' => $message,
            'data' => $data,
            'trace_id' => static::traceId(),
        ]);
    }

    /**
     * 分页响应
     *
     * 将 Laravel 分页器结果转换为标准分页格式：
     *  - list：当前页数据列表
     *  - pagination：分页元信息（页码、每页条数、总数、总页数）
     *
     * @param  LengthAwarePaginator  $paginator 分页器实例
     * @param  string                $message   提示信息
     * @return JsonResponse
     */
    public static function paginate(LengthAwarePaginator $paginator, string $message = '操作成功'): JsonResponse
    {
        return response()->json([
            'code' => config('kylin-core.response.success_code', 'SUCCESS'),
            'message' => $message,
            'data' => [
                'list' => $paginator->items(),
                'pagination' => [
                    'current_page' => $paginator->currentPage(),
                    'per_page' => $paginator->perPage(),
                    'total' => $paginator->total(),
                    'last_page' => $paginator->lastPage(),
                ],
            ],
            'trace_id' => static::traceId(),
        ]);
    }

    /**
     * 创建成功响应（HTTP 201 Created）
     *
     * @param  mixed   $data    新创建的资源数据
     * @param  string  $message 提示信息
     * @return JsonResponse
     */
    public static function created(mixed $data = null, string $message = '创建成功'): JsonResponse
    {
        return response()->json([
            'code' => config('kylin-core.response.success_code', 'SUCCESS'),
            'message' => $message,
            'data' => $data,
            'trace_id' => static::traceId(),
        ], 201);
    }

    /**
     * 无内容响应（HTTP 204 No Content）
     *
     * 用于 DELETE 操作或需要表示操作成功但无需返回内容的场景。
     */
    public static function noContent(): JsonResponse
    {
        return response()->json(null, 204);
    }

    /**
     * 错误响应
     *
     * @param  string  $code       业务错误码（如 CORE-VAL-001）
     * @param  string  $message    错误描述
     * @param  int     $httpStatus HTTP 状态码
     * @param  mixed   $data       附加错误数据（如验证错误详情）
     * @return JsonResponse
     */
    public static function error(
        string $code,
        string $message,
        int $httpStatus,
        mixed $data = null,
    ): JsonResponse {
        $response = [
            'code' => $code,
            'message' => $message,
            'data' => $data,
            'trace_id' => static::traceId(),
        ];

        return response()->json($response, $httpStatus);
    }
}
