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

<?php

namespace App\Http\Controllers\Coach;

use Illuminate\Http\Request;
use App\Traits\ResponseTrait;
use App\Http\Controllers\Controller;
use Illuminate\Support\Facades\Auth;
use App\Services\Coach\ProjectService;
use App\Http\Requests\Coach\SetProjectRequest;
use App\Http\Requests\Coach\OpenProjectRequest;

/**
 * @group 技师端
 *
 * 项目管理相关的API接口
 */
class ProjectController extends Controller
{
    use ResponseTrait;

    protected ProjectService $service;

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

    /**
     * [项目]获取可开通项目列表
     *
     * @description 获取技师可以开通的项目列表，包含项目的基本信息、价格信息和服务说明，以及是否已开通状态
     *
     * @authenticated 需要技师身份认证
     *
     * @response {
     *   "status": true,
     *   "message": "获取成功",
     *   "data": [
     *     {
     *       "id": 1,                    // 项目ID
     *       "title": "精油推拿",         // 项目标题
     *       "subtitle": "专业精油推拿",  // 项目副标题
     *       "cover": "http://example.com/cover.jpg", // 项目封面图
     *       "price": "188.00",          // 项目价格
     *       "original_price": "288.00", // 原价
     *       "sales": 100,               // 销量
     *       "duration": 60,             // 服务时长(分钟)
     *       "project_desc": "项目描述",  // 项目描述
     *       "service_desc": "服务说明",  // 服务说明
     *       "type": 1,                  // 项目类型
     *       "is_opened": false          // 是否已开通
     *     }
     *   ]
     * }
     *
     * @response 404 {
     *   "message": "技师信息不存在"
     * }
     */
    public function getAvailableProjects()
    {
        return $this->success(
            $this->service->getAvailableProjects(Auth::user()->coach)
        );
    }

    /**
     * [项目]开通/关闭项目
     *
     * @description 技师开通或关闭服务项目，包含项目状态和资格检查
     *
     * 业务流程：
     * 1. 验证项目ID和操作类型
     * 2. 调用服务层处理开关逻辑
     * 3. 返回操作结果
     *
     * @authenticated 需要技师身份认证
     *
     * @bodyParam project_id integer required 项目ID Example: 1
     * @bodyParam action string required 操作类型(open:开通 close:关闭) Example: "open"
     *
     * @response {
     *   "status": true,
     *   "message": "获取成功",
     *   "data": {
     *     "project_id": 1,         // 项目ID
     *     "project_name": "精油推拿", // 项目名称
     *     "state": 1,              // 项目状态
     *     "state_text": "已开通"    // 状态描述
     *   }
     * }
     *
     * @response 404 {
     *   "message": "项目不存在或已下架"
     * }
     * @response 422 {
     *   "message": "技师状态异常，无法操作项目"
     * }
     */
    public function openProject(OpenProjectRequest $request)
    {
        // 调用服务层处理开通/关闭逻辑并返回结果
        return $this->success(
            $this->service->openProject(Auth::user()->coach, $request->validated())
        );
    }

    /**
     * [项目]项目设置
     *
     * @description 设置技师已开通项目的相关参数，包括代金券、顾客性别和交通费设置
     *
     * 业务流程：
     * 1. 验证项目设置参数
     * 2. 调用服务层处理设置更新
     * 3. 返回更新结果
     *
     * @authenticated 需要技师身份认证
     *
     * @bodyParam project_id integer required 项目ID Example: 1
     * @bodyParam voucher numeric 代金卷金额(0-10元) Example: 5.00
     * @bodyParam gender integer 顾客性别(0:不限 1:男 2:女) Example: 0
     * @bodyParam traffic_fee_type integer 交通费类型(0:免费 1:单程 2:双程) Example: 2
     *
     * @response {
     *   "status": true,
     *   "message": "项目设置更新成功",
     *   "data": {
     *     "coach_id": 1,
     *     "settings": {
     *       "voucher": "5.00",
     *       "gender": 0,
     *       "traffic_fee_type": 2
     *     }
     *   }
     * }
     *
     * @response 404 {
     *   "message": "未开通该项目"
     * }
     * @response 422 {
     *   "message": "代金卷金额不能超过10元"
     * }
     */
    public function setProject(SetProjectRequest $request)
    {
        // 调用服务层处理设置更新并返回结果
        return $this->success(
            $this->service->setProject(Auth::user()->coach, $request->validated())
        );
    }

    /**
     * [项目]获取项目设置
     *
     * @description 获取技师已开通项目的相关参数设置，包括代金券、顾客性别和交通费设置
     *
     * @authenticated 需要技师身份认证
     *
     * @queryParam project_id integer required 项目ID Example: 1
     *
     * @response {
     *   "status": true,
     *   "message": "获取成功",
     *   "data": {
     *     "project_id": 1,
     *     "project_name": "精油推拿",
     *     "settings": {
     *       "voucher": "5.00",         // 代金券金额
     *       "gender": 0,               // 顾客性别(0:不限 1:男 2:女)
     *       "traffic_fee_type": 2      // 交通费类型(0:免费 1:单程 2:双程)
     *     }
     *   }
     * }
     *
     * @response 404 {
     *   "message": "未开通该项目"
     * }
     */
    public function getProjectSettings(Request $request)
    {
        $validated = $request->validate([
            'project_id' => 'required|integer|exists:project,id'
        ]);

        return $this->success(
            $this->service->getProjectSettings(Auth::user()->coach, $validated['project_id'])
        );
    }
}