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

<?php

namespace App\Http\Controllers\Coach;

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

/**
 * @group 技师端
 *
 * 订单相关的API接口
 */
class OrderController extends Controller
{
    use ResponseTrait;

    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->success($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->success($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->success($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->success($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->success($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->success($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->success($this->service->arrive(Auth::user()->id, $order_id));
    }

    /**
     * [订单]开始服务
     *
     * @description 技师扫描客户二维码开始服务
     *
     * @bodyParam order_id integer required 订单ID Example: 1
     * @bodyParam qr_code string required 二维码内容 Example: order_1_1677123456_abcdef
     *
     * @response {
     *  "status": true,
     *  "message": "开始服务成功",
     *  "data": {
     *    "order_id": 1,
     *    "state": "serving",
     *    "service_start_time": "2024-01-01 12:00:00"
     *  }
     * }
     */
    public function startService(Request $request)
    {
        $validated = $request->validate([
            'order_id' => 'required|integer',
            'qr_code' => 'required|string',
        ]);

        return $this->success(
            $this->service->startService(
                Auth::user()->id,
                $validated['order_id'],
                $validated['qr_code']
            )
        );
    }

    /**
     * [订单]撤离
     *
     * @description 技师确认已完成服务并撤离服务地点
     *
     * @authenticated
     *
     * @urlParam order_id integer required 订单ID Example: 1
     *
     * @response {
     *   "status": true,
     *   "message": "撤离成功",
     *   "data": {
     *     "order_id": 1,
     *     "state": "completed",
     *     "leave_time": "2024-03-21 12:30:00"
     *   }
     * }
     * @response 400 {
     *   "message": "订单状态异常，无法确认撤离"
     * }
     * @response 403 {
     *   "message": "该订单未分配给您"
     * }
     */
    public function leave(int $order_id)
    {
        return $this->success($this->service->leave(Auth::user()->id, $order_id));
    }

    /**
     * [订单]订单设置
     *
     * @return JsonResponse
     *
     * @description 更新技师的订单相关设置，如服务距离等
     *
     * @bodyParam distance float 服务距离(公里) Example: 10
     *
     * @response {
     *   "message": "订单设置更新成功",
     *   "coach_id": 1,
     *   "settings": {
     *     "distance": 10
     *   }
     * }
     */
    public function setOrder(Request $request)
    {
        $data = $request->validate([
            'distance' => 'nullable|numeric|min:0',
        ]);

        return $this->success(
            $this->service->setOrder(Auth::user()->id, $data)
        );
    }

    /**
     * [订单]获取订单设置
     *
     * @description 获取技师的订单相关设置，如服务距离等
     *
     * @authenticated 需要技师身份认证
     *
     * @response 200 {
     *   "status": true,
     *   "message": "获取成功",
     *   "data": {
     *     "distance": 10,              // 服务距离(公里)
     *     "distance_max": 40,          // 最大服务距离(公里)
     *     "distance_min": 1            // 最小服务距离(公里)
     *   }
     * }
     */
    public function getOrderSettings()
    {
        return $this->success(
            $this->service->getOrderSettings(Auth::user()->coach)
        );
    }
}