owl-admin/app/Http/Controllers/Coach/OrderController.php

<?php

namespace App\Http\Controllers\Coach;

use App\Http\Controllers\Controller;
use App\Services\Coach\OrderService;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

/**
 * @group 技师端
 *
 * 订单相关的API接口
 */
class OrderController extends Controller
{
    protected OrderService $service;

    public function __construct(OrderService $service)
    {
        $this->service = $service;
    }

    /**
     * [订单]获取可抢订单列表
     *
     * @description 获取当前技师40公里范围内的可抢订单列表，包含订单基本信息和距离
     *
     * @authenticated
     *
     * @queryParam area_code string required 区划代码 Example: 370602
     * @queryParam page int 页码 Example: 1
     * @queryParam per_page int 每页数量 Example: 10
     *
     * @response {
     *   "data": [
     *     {
     *       "id": 1,
     *       "order_no": "202403210001",
     *       "project_name": "精油推拿",
     *       "project_duration": 60,
     *       "project_price": "188.00",
     *       "address": "山东省烟台市芝罘区幸福小区1号楼",
     *       "distance": 2.5,
     *       "service_time": "2024-03-21 10:00:00",
     *       "created_at": "2024-03-21 09:30:00"
     *     }
     *   ],
     *   "meta": {
     *     "total": 100,
     *     "per_page": 10,
     *     "current_page": 1,
     *     "last_page": 10
     *   }
     * }
     */
    public function getGrabList(Request $request)
    {
        $params = $request->validate([
            'area_code' => 'required|string',
            'page' => 'nullable|integer|min:1',
            'per_page' => 'nullable|integer|min:1|max:50',
        ]);

        return $this->service->getGrabList(Auth::user()->id, $params);
    }

    /**
     * [订单]获取订单列表
     *
     * @description 获取当前技师的订单列表，不包含已创建和已分配状态的订单
     *
     * @authenticated
     *
     * @queryParam page int 页码 Example: 1
     * @queryParam per_page int 每页数量 Example: 10
     *
     * @response {
     *   "data": {
     *     "items": [
     *       {
     *         "id": 1,
     *         "order_no": "202403210001",
     *         "project_name": "精油推拿",
     *         "project_duration": 60,
     *         "project_price": "188.00",
     *         "address": "山东省烟台市芝罘区幸福小区1号楼",
     *         "service_time": "2024-03-21 10:00:00",
     *         "status": "completed",
     *         "created_at": "2024-03-21 09:30:00"
     *       }
     *     ],
     *     "total": 100
     *   }
     * }
     */
    public function getOrderList(Request $request)
    {
        $params = $request->validate([
            'page' => 'nullable|integer|min:1',
            'per_page' => 'nullable|integer|min:1|max:50',
        ]);

        return $this->service->getOrderList(Auth::user()->id, $params);
    }

    /**
     * [订单]抢单
     *
     * @description 技师抢取指定订单
     *
     * @authenticated
     *
     * @urlParam order_id integer required 订单ID Example: 1
     *
     * @response {
     *   "message": "抢单成功",
     *   "order_id": 1
     * }
     * @response 400 {
     *   "message": "订单状态异常，无法抢单"
     * }
     * @response 400 {
     *   "message": "订单超出服务范围"
     * }
     * @response 400 {
     *   "message": "未开通该项目服务资格"
     * }
     */
    public function grabOrder(int $order_id)
    {
        return $this->service->grabOrder(Auth::user()->id, $order_id);
    }

    /**
     * [订单]接单
     *
     * @description 技师接受已分配的订单
     *
     * @authenticated
     *
     * @urlParam order_id integer required 订单ID Example: 1
     *
     * @response {
     *   "message": "接单成功",
     *   "order_id": 1,
     *   "order_no": "202403210001"
     * }
     * @response 400 {
     *   "message": "订单状态异常，无法接单"
     * }
     * @response 403 {
     *   "message": "该订单未分配给您"
     * }
     */
    public function acceptOrder(int $order_id)
    {
        return $this->service->acceptOrder(Auth::user()->id, $order_id);
    }

    /**
     * [订单]拒单
     *
     * @description 技师拒绝已分配的订单
     *
     * @authenticated
     *
     * @urlParam order_id integer required 订单ID Example: 1
     *
     * @bodyParam reason string required 拒单原因(8-200个字符) Example: 距离太远，无法服务
     *
     * @response {
     *   "message": "拒单成功",
     *   "order_id": 1,
     *   "order_no": "202403210001"
     * }
     * @response 400 {
     *   "message": "订单状态异常，无法拒单"
     * }
     * @response 403 {
     *   "message": "该订单未分配给您"
     * }
     */
    public function rejectOrder(Request $request, int $order_id)
    {
        $data = $request->validate([
            'reason' => 'required|string|min:8|max:200',
        ]);

        return $this->service->rejectOrder(Auth::user()->id, $order_id, $data['reason']);
    }

    /**
     * [订单]出发
     *
     * @description 技师确认出发前往服务地点
     *
     * @authenticated
     *
     * @urlParam order_id integer required 订单ID Example: 1
     *
     * @response {
     *   "message": "已确认出发",
     *   "order_id": 1,
     *   "order_no": "202403210001",
     *   "departed_at": "2024-03-21 10:00:00"
     * }
     * @response 400 {
     *   "message": "订单状态异常，无法确认出发"
     * }
     * @response 403 {
     *   "message": "该订单未分配给您"
     * }
     */
    public function depart(int $order_id)
    {
        return $this->service->depart(Auth::user()->id, $order_id);
    }

    /**
     * [订单]到达
     *
     * @description 技师确认已到达服务地点
     *
     * @authenticated
     *
     * @urlParam order_id integer required 订单ID Example: 1
     *
     * @response {
     *   "message": "已确认到达",
     *   "order_id": 1,
     *   "order_no": "202403210001",
     *   "arrived_at": "2024-03-21 10:30:00"
     * }
     * @response 400 {
     *   "message": "订单状态异常，无法确认到达"
     * }
     * @response 403 {
     *   "message": "该订单未分配给您"
     * }
     */
    public function arrive(int $order_id)
    {
        return $this->service->arrive(Auth::user()->id, $order_id);
    }
}