owl-admin/app/Http/Controllers/Client/ProjectController.php

<?php

namespace App\Http\Controllers\Client;

use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
use App\Services\Client\ProjectService;

/**
 * @group 用户端
 *
 * 项目相关的API接口
 */
class ProjectController extends Controller
{
    protected ProjectService $service;

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

    /**
     * [项目]获取项目列表
     *
     * 根据区域代码获取项目列表
     *
     * @authenticated
     *
     * @queryParam area_code string required 区域代码. Example: 330100
     * @queryParam project_cate_id integer 项目分类ID. Example: 1
     * @queryParam type integer required 项目类型(1:普通项目,2:加钟项目). Example: 1
     *
     * @response {
     *   "code": 200,
     *   "message": "获取成功",
     *   "data": {
     *     "current_page": 1,
     *     "data": [
     *       {
     *         "id": 1,
     *         "name": "项目名称",
     *         "description": "项目描述",
     *         "price": "100.00",
     *         "duration": 60,
     *         "category": {
     *           "id": 1,
     *           "name": "分类名称"
     *         }
     *       }
     *     ],
     *     "total": 10,
     *     "per_page": 10
     *   }
     * }
     */
    public function index(Request $request)
    {
        // 验证请求参数
        $validated = $request->validate([
            'area_code' => ['required', 'string', 'regex:/^\d{6}$/'],
            'project_cate_id' => 'nullable|integer',
            'type' => 'required|in:1,2'
        ]);

        // 调用服务层获取项目列表
        return $this->success(
            $this->service->getProjectList(
                $validated['area_code'],
                $validated['project_cate_id'] ?? null,
                $validated['type']
            )
        );
    }

    /**
     * [项目]获取项目详情
     *
     * 获取指定项目的详细信息
     *
     * @authenticated
     *
     * @queryParam id integer required 项目ID. Example: 1
     * @queryParam area_code string required 区域代码. Example: 330100
     *
     * @response {
     *   "code": 200,
     *   "message": "获取成功",
     *   "data": {
     *     "id": 1,
     *     "name": "项目名称",
     *     "description": "项目描述",
     *     "price": "100.00",
     *     "duration": 60,
     *     "category": {
     *       "id": 1,
     *       "name": "分类名称"
     *     },
     *     "agent": {
     *       "id": 1,
     *       "name": "代理商名称",
     *       "contact": "联系人",
     *       "mobile": "13800138000"
     *     }
     *   }
     * }
     * @response 404 {
     *   "code": 404,
     *   "message": "项目不存在"
     * }
     * @response 400 {
     *   "code": 400,
     *   "message": "该区域暂无代理商"
     * }
     */
    public function detail(Request $request)
    {
        $projectId = $request->input('id');
        $areaCode = $request->input('area_code');

        return $this->success($this->service->getProjectDetail($projectId, $areaCode));
    }

    /**
     * [项目]获取技师项目列表
     *
     * 获取指定技师已开通的项目列表
     *
     * @authenticated
     *
     * @queryParam coach_id integer required 技师ID. Example: 6
     * @queryParam area_code string required 区域代码. Example: 330100
     * @queryParam project_cate_id integer 项目分类ID. Example: 1
     *
     * @response {
     *   "code": 200,
     *   "message": "获取成功",
     *   "data": {
     *     "current_page": 1,
     *     "data": [
     *       {
     *         "id": 1,
     *         "name": "项目名称",
     *         "description": "项目描述",
     *         "price": "100.00",
     *         "duration": 60,
     *         "category": {
     *           "id": 1,
     *           "name": "分类名称"
     *         }
     *       }
     *     ],
     *     "total": 10,
     *     "per_page": 10
     *   }
     * }
     * @response 404 {
     *   "code": 404,
     *   "message": "技师不存在或未通过认证"
     * }
     */
    public function coachProjectList(Request $request)
    {
        $validated = $request->validate([
            'coach_id' => 'required|integer',
            'area_code' => 'required|string',
            'project_cate_id' => 'required|integer',
        ]);

        return $this->success(
            $this->service->getCoachProjectList(
                $validated['coach_id'],
                $validated['area_code'],
                $validated['project_cate_id']
            )
        );
    }
}