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

<?php

namespace App\Http\Controllers\Coach;

use Illuminate\Http\Request;
use App\Traits\ResponseTrait;
use App\Traits\LocationDataTrait;
use Illuminate\Support\Facades\Log;
use App\Http\Controllers\Controller;
use Illuminate\Support\Facades\Auth;
use App\Enums\TechnicianLocationType;
use App\Services\Coach\AccountService;
use App\Http\Requests\Coach\SetLocationRequest;
use App\Http\Requests\Coach\SetScheduleRequest;
use App\Http\Requests\Coach\SendVerifyCodeRequest;
use App\Http\Requests\Coach\SubmitBaseInfoRequest;
use App\Http\Requests\Coach\SubmitRealNameRequest;
use App\Http\Requests\Coach\UpdateBasicInfoRequest;
use App\Http\Requests\Coach\SubmitQualificationRequest;

/**
 * @group 技师端
 *
 * 技师账户相关的API接口
 */
class AccountController extends Controller
{
    use ResponseTrait;
    use LocationDataTrait;

    protected AccountService $service;

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

    /**
     * [账户]提交基本信息
     *
     * @description 提交技师的基本个人信息，包括头像、生活照片、个人资料等
     *
     * 业务流程：
     * 1. 验证提交的数据
     * 2. 调用服务层处理业务逻辑
     * 3. 返回处理结果
     *
     * 注意事项：
     * - 同一时间只能有一条待审核记录
     * - 审核不通过可以重新提交
     * - 头像和生活照片支持任意格式的图片数据
     * - 除性别和手机号外，其他字段均为可选
     * - 生活照片为可选，支持多张
     *
     * @authenticated 需要技师身份认证
     *
     * @bodyParam nickname string nullable 昵称(2-20个字符) Example: 张三
     * @bodyParam avatar string nullable 头像图片 Example: base64或其他格式的图片数据
     * @bodyParam life_photos array nullable 生活照片数组
     * @bodyParam life_photos.* string required 生活照片 Example: base64或其他格式的图片数据
     * @bodyParam gender string required 性别(1:男 2:女) Example: 1
     * @bodyParam mobile string required 手机号 Example: 13800138000
     * @bodyParam birthday date nullable 出生日期(年龄需满18岁) Example: 1990-01-01
     * @bodyParam work_years integer nullable 工作年限(0-99) Example: 5
     * @bodyParam intention_city string nullable 意向城市 Example: 北京
     * @bodyParam introduction string nullable 个人简介(10-255个字符) Example: 专业按摩师，从业5年
     *
     * @response 200 {
     *   "status": true,
     *   "message": "基本信息提交成功"
     * }
     * @response 404 {
     *   "message": "技师信息不存在"
     * }
     * @response 422 {
     *   "message": "已有待审核的基本信息记录"
     * }
     * @response 422 {
     *   "message": "验证错误",
     *   "errors": {
     *     "nickname": ["昵称不能少于2个字符"],
     *     "gender": ["性别不能为空"],
     *     "mobile": ["手机号不能为空"],
     *     "life_photos.*": ["生活照片格式不正确"]
     *   }
     * }
     */
    public function submitBaseInfo(SubmitBaseInfoRequest $request)
    {
        // 获取验证后的数据
        $data = $request->validated();

        // 调用服务层处理业务逻辑
        // 传入当前认证用户和验证后的数据
        return $this->success(
            $this->service->submitBaseInfo(Auth::user(), $data)
        );
    }

    /**
     * [账户]提交资质信息
     *
     * @description 提交技师的资质认证信息，包括资质照片、营业执照和健康证
     *
     * @authenticated
     *
     * @bodyParam qual_type int required 资质类型(1:初级按摩师 2:中级按摩师 3:高级按摩师) Example: 1
     * @bodyParam qual_photo string required 资质证书照片 Example: base64或其他格式的图片数据
     * @bodyParam business_license string required 营业执照照片 Example: base64或其他格式的图片数据
     * @bodyParam health_cert string required 健康证照片 Example: base64或其他格式的图片数据
     *
     * @response {
     *  "message": "资质信息提交成功"
     * }
     */
    public function submitQualification(SubmitQualificationRequest $request)
    {
        $data = $request->validated();

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

    /**
     * [账户]提交实名认证
     *
     * @description 提交技师的实名认证信息
     *
     * @authenticated
     *
     * @bodyParam real_name string nullable 姓名(2-20个字符) Example: 张三
     * @bodyParam id_card string nullable 身份证号(18位) Example: 370602199001011234
     * @bodyParam id_card_front_photo string required 身份证正面照片 Example: base64或其他格式的图片数据
     * @bodyParam id_card_back_photo string required 身份证反面照片 Example: base64或其他格式的图片数据
     * @bodyParam id_card_hand_photo string required 手持身份证照片 Example: base64或其他格式的图片数据
     *
     * @response {
     *  "message": "实名认证信息提交成功"
     * }
     */
    public function submitRealName(SubmitRealNameRequest $request)
    {
        $data = $request->validated();

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

    /**
     * [账户]获取技师认证信息
     *
     * @description 获取技师的基本信息、资质信息和实名认证信息
     *
     * @authenticated
     *
     * @response {
     *   "data": {
     *     "base_info": {
     *       "nickname": "张三",
     *       "avatar": "base64或其他格式的图片数据",
     *       "life_photos": [
     *         "base64或其他格式的图片数据1",
     *         "base64或其他格式的图片数据2"
     *       ],
     *       "gender": "1",
     *       "mobile": "138****8000",
     *       "birthday": "1990-01-01",
     *       "work_years": 5,
     *       "intention_city": "北京",
     *       "introduction": "专业按摩师，从业5年",
     *       "state": 1,
     *       "state_text": "已通过",
     *       "audit_remark": "审核通过"
     *     },
     *     "qualification": {
     *       "qual_type": "高级按摩师",
     *       "qual_photo": "base64或其他格式的图片数据",
     *       "business_license": "base64或其他格式的图片数据",
     *       "health_cert": "base64或其他格式的图片数据",
     *       "state": 1,
     *       "state_text": "已通过",
     *       "audit_remark": "审核通过"
     *     },
     *     "real_name": {
     *       "real_name": "张三",
     *       "id_card": "370602****1234",
     *       "id_card_front_photo": "base64或其他格式的图片数据",
     *       "id_card_back_photo": "base64或其他格式的图片数据",
     *       "id_card_hand_photo": "base64或其他格式的图片数据",
     *       "state": 1,
     *       "state_text": "已通过",
     *       "audit_remark": "审核通过"
     *     }
     *   }
     * }
     * @response 404 {
     *   "message": "用户不存在"
     * }
     * @response 404 {
     *   "message": "技师信息不存在"
     * }
     */
    public function info()
    {
        return $this->success($this->service->getCoachInfo(Auth::user()));
    }

    /**
     * [账户]设置技师位置信息
     *
     * @description 设置技师的当前位置或常用位置
     *
     * @authenticated
     *
     * @bodyParam latitude float required 纬度 Example: 39.9042
     * @bodyParam longitude float required 经度 Example: 116.4074
     * @bodyParam type int nullable 位置类型(1:当前位置 2:常用位置) Example: 2
     * @bodyParam province string nullable 省份 Example: 北京市
     * @bodyParam city string nullable 城市 Example: 北京市
     * @bodyParam district string nullable 区县 Example: 朝阳区
     * @bodyParam address string nullable 详细地址 Example: 建国路93号万达广场
     * @bodyParam adcode string nullable 行政区划代码 Example: 110105
     *
     * @response {
     *   "message": "位置信息设置成功"
     * }
     */
    public function setLocation(SetLocationRequest $request)
    {
        // 获取验证后的数据
        $validated = $request->validated();

        // 确保用户和技师存在
        $user = Auth::user();
        abort_if(!$user->coach, 404, '技师信息不存在');

        // 提取位置信息
        $locationInfo = $this->extractLocationInfo($validated);

        // 传递技师ID给服务层
        $this->service->setLocation(
            $user->coach->id,
            $validated['latitude'],
            $validated['longitude'],
            $validated['type'] ?? TechnicianLocationType::COMMON->value,
            $locationInfo
        );

        return $this->success(['message' => '位置信息设置成功']);
    }

    /**
     * [账户]获取技师位置信息
     *
     * @description 获取技师的位置信息
     *
     * @authenticated
     *
     * @queryParam type int 位置类型(1:当前位置 2:常用位置) Example: 2
     *
     * @response {
     *   "data": {
     *     "province": "浙江省",
     *     "city": "杭州市",
     *     "district": "西湖区",
     *     "address": "文三路478号",
     *     "adcode": "330106",
     *     "longitude": 120.12345,
     *     "latitude": 30.12345,
     *     "updated_at": "2024-03-22 10:00:00"
     *   }
     * }
     */
    public function getLocation(Request $request)
    {
        $validated = $request->validate([
            'type' => 'required|integer|in:1,2'
        ]);

        return $this->success(
            $this->service->getLocation(Auth::user(), $validated['type'])
        );
    }

    /**
     * [账户]设置排班时间
     *
     * @description 设置技师每天通用的排班时间段
     *
     * @authenticated
     *
     * @bodyParam time_ranges array required 时间段数组
     * @bodyParam time_ranges[].start_time string required 开始时间(HH:mm格式) Example: "09:00"
     * @bodyParam time_ranges[].end_time string required 结束时间(HH:mm格式) Example: "24:00"
     *
     * @response {
     *   "status": true,
     *   "message": "排班设置成功",
     *   "data": {
     *     "coach_id": 1,
     *     "time_ranges": [
     *       {
     *         "start_time": "09:00",
     *         "end_time": "12:00"
     *       }
     *     ],
     *     "updated_at": "2024-03-21 10:00:00"
     *   }
     * }
     */
    public function setSchedule(SetScheduleRequest $request)
    {
        return $this->success(
            $this->service->setSchedule(Auth::user()->coach, $request->validated()['time_ranges'])
        );
    }

    /**
     * [账户]更改技师工作状态
     *
     * @description 更改技师的工作状态(休息中/工作中)，工作状态会自动判断为空闲或忙碌
     *
     * 业务流程：
     * 1. 验证请求参数
     * 2. 检查技师认证状态
     * 3. 验证排班时间
     * 4. 根据订单状态自动判断工作状态
     * 5. 更新状态并返回结果
     *
     * @authenticated 需要技师身份认证
     *
     * @bodyParam status int required 状态(1:休息中 2:工作中) Example: 2
     *
     * @response 200 {
     *   "status": true,
     *   "message": "状态更新成功",
     *   "data": {
     *     "work_status": 2,              // 工作状态值(1:休息中 2:空闲中 3:忙碌中)
     *     "work_status_text": "空闲中",   // 工作状态文本
     *     "updated_at": "2024-03-20 10:00:00"  // 更新时间
     *   }
     * }
     * @response 400 {
     *   "message": "无效的状态值"
     * }
     * @response 422 {
     *   "message": "当前状态不能更改为休息状态"
     * }
     * @response 422 {
     *   "message": "当前时间不在排班时间内，无法切换到工作状态"
     * }
     */
    public function updateWorkStatus(Request $request)
    {
        // 验证请求参数
        $validated = $request->validate([
            'status' => 'required|integer|in:1,2',  // 1:休息中 2:工作中
        ], [
            'status.required' => '状态不能为空',
            'status.integer' => '状态必须是整数',
            'status.in' => '无效的状态值',
        ]);

        // 调用服务层处理状态更新，直接传入技师对象
        return $this->success(
            $this->service->updateWorkStatus(Auth::user()->coach, $validated['status'])
        );
    }

    /**
     * [账户]获取技师工作状态
     *
     * @description 获取技师当前工作状态
     *
     * @authenticated
     *
     * @response {
     *   "data": {
     *     "work_status": 2,
     *     "work_status_text": "空闲中",
     *     "updated_at": "2024-03-22 10:00:00"
     *   }
     * }
     * @response 404 {
     *   "message": "技师不存在"
     * }
     */
    public function getWorkStatus()
    {
        return $this->success(
            $this->service->getWorkStatus(Auth::user()->coach->id)
        );
    }

    /**
     * [排班]获取技师排班信息
     *
     * @description 获取技师当前的排班时间段设置
     *
     * @authenticated 需要技师身份认证
     *
     * @response 200 {
     *   "status": true,
     *   "message": "获取成功",
     *   "data": {
     *     "time_ranges": [                // 工作时间段列表
     *       {
     *         "start_time": "09:00",      // 开始时间
     *         "end_time": "12:00"         // 结束时间
     *       }
     *     ],
     *     "updated_at": "2024-03-21 10:00:00"  // 最后更新时间
     *   }
     * }
     * @response 404 {
     *   "message": "技师信息不存在"
     * }
     */
    public function getSchedule()
    {
        return $this->success(
            $this->service->getSchedule(Auth::user()->coach)
        );
    }

    /**
     * [账户]获取技师详细信息
     *
     * @description 获取当前登录技师的详细信息，包括基本信息、认证状态、位置信息、统计数据等
     *
     * 业务流程：
     * 1. 获取技师基本信息和关联数据
     * 2. 生成技师工号和邀请码
     * 3. 获取钱包和认证状态信息
     * 4. 获取位置和店铺信息
     * 5. 获取统计数据
     * 6. 组装返回数据
     *
     * @authenticated 需要技师身份认证
     *
     * @group 技师端-账户
     *
     * @responseFile 200 responses/coach/account/detail.json
     * @response 200 {
     *   "status": true,
     *   "message": "获取成功",
     *   "data": {
     *     "coach_no": "00000001",                // 技师工号
     *     "mobile": "138****8000",               // 手机号(脱敏)
     *     "nickname": "张三",                     // 昵称
     *     "avatar": "https://example.com/avatar.jpg", // 头像URL
     *     "age": 25,                             // 年龄
     *     "gender": 1,                           // 性别(1:男 2:女)
     *     "work_years": 5,                       // 工作年限
     *     "intention_city": "杭州",               // 意向城市
     *     "life_photos": [                       // 生活照片数组
     *       "https://example.com/photo1.jpg",
     *       "https://example.com/photo2.jpg"
     *     ],
     *     "introduction": "专业按摩师，从业5年",    // 个人简介
     *     "state": 1,                            // 状态值
     *     "state_text": "正常",                   // 状态文本
     *     "work_status": 2,                      // 工作状态(1:休息中 2:工作中-空闲 3:工作中-忙碌)
     *     "work_status_text": "空闲中",           // 工作状态文本
     *     "invite_code": "C1",                   // 邀请码
     *     "wallet": {                            // 钱包信息
     *       "balance": 1000.00,                  // 余额
     *       "frozen": 200.00,                    // 冻结金额
     *       "total_income": 5000.00,             // 总收入
     *       "today_income": 300.00,              // 今日收入
     *       "withdrawable": 800.00               // 可提现金额
     *     },
     *     "auth_status": {                       // 认证状态信息
     *       "base_info": {                       // 基本信息认证
     *         "state": 1,                        // 状态值
     *         "state_text": "已通过",             // 状态文本
     *         "audit_remark": "审核通过",          // 审核备注
     *         "updated_at": "2024-03-22 10:00:00" // 更新时间
     *       },
     *       "real_name": {                       // 实名认证
     *         "state": 1,
     *         "state_text": "已通过",
     *         "audit_remark": "审核通过",
     *         "updated_at": "2024-03-22 10:00:00"
     *       },
     *       "qualification": {                    // 资质认证
     *         "state": 1,
     *         "state_text": "已通过",
     *         "audit_remark": "审核通过",
     *         "updated_at": "2024-03-22 10:00:00"
     *       }
     *     },
     *     "location": {                          // 位置信息
     *       "province": "浙江省",                 // 省份
     *       "city": "杭州市",                     // 城市
     *       "district": "西湖区",                 // 区县
     *       "address": "文三路478号",             // 详细地址
     *       "adcode": "330106",                  // 行政区划代码
     *       "longitude": 120.12345,              // 经度
     *       "latitude": 30.12345                 // 纬度
     *     },
     *     "shop": {                              // 店铺信息
     *       "id": 1,                             // 店铺ID
     *       "name": "示例店铺",                   // 店铺名称
     *       "address": "杭州市西湖区文三路478号",   // 店铺地址
     *       "phone": "0571-88888888"             // 联系电话
     *     },
     *     "statistics": {                        // 统计数据
     *       "order_count": 100,                  // 总订单数
     *       "completed_order_count": 80,         // 已完成订单数
     *       "pending_order_count": 5,            // 未完成订单数
     *       "level": 2,                          // 技师等级
     *       "level_text": "中级技师",             // 等级文本
     *       "rating": 4.8,                       // 评分
     *       "grab_order_count": 50,              // 抢单数量
     *       "carrying_order_count": 3            // 带接单数量（已支付但未被接单的订单数）
     *     }
     *   }
     * }
     * @response 404 {
     *   "status": false,
     *   "message": "技师信息不存在"
     * }
     */
    public function detail()
    {
        // 获取技师详细信息
        $data = $this->service->getCoachDetail();

        // 返回成功响应
        return $this->success($data, '获取成功');
    }

    /**
     * [账户]更新基础信息
     *
     * @description 更新技师的基础信息，包括昵称、性别和手机号。修改手机号时需要先获取验证码进行验证。
     *
     * 业务流程：
     * 1. 验证提交的数据
     * 2. 验证手机验证码(如果修改手机号)
     * 3. 调用服务层处理更新
     * 4. 返回更新结果
     *
     * 注意事项：
     * - 可以单独更新某个字段，不需要同时提交所有字段
     * - 修改手机号时必须提供验证码
     * - 同一时间只能有一条待审核记录
     *
     * @authenticated 需要技师身份认证
     *
     * @bodyParam nickname string nullable 昵称(2-20个字符) Example: 张三
     * @bodyParam gender integer nullable 性别(1:男 2:女) Example: 1
     * @bodyParam mobile string nullable 手机号 Example: 13800138000
     * @bodyParam code string required if:mobile 验证码(修改手机号时必填) Example: 123456
     *
     * @response {
     *   "status": true,
     *   "message": "基础信息修改申请已提交",
     *   "data": {
     *     "record_id": 1,
     *     "updated_fields": ["nickname", "gender"]
     *   }
     * }
     *
     * @response {
     *   "status": true,
     *   "message": "基础信息修改申请已更新",
     *   "data": {
     *     "record_id": 1,
     *     "updated_fields": ["mobile"]
     *   }
     * }
     *
     * @response 404 {
     *   "message": "未找到有效的基础信息记录"
     * }
     * @response 422 {
     *   "message": "没有需要更新的字段"
     * }
     * @response 422 {
     *   "message": "验证码错误或已过期"
     * }
     * @response 422 {
     *   "message": "验证错误",
     *   "errors": {
     *     "nickname": ["昵称不能少于2个字符"],
     *     "gender": ["性别只能是1(男)或2(女)"],
     *     "mobile": ["手机号格式不正确"],
     *     "code": ["验证码不能为空"]
     *   }
     * }
     */
    public function updateBasicInfo(UpdateBasicInfoRequest $request)
    {
        return $this->success(
            $this->service->updateBasicInfo(Auth::user()->coach, $request->validated())
        );
    }

    /**
     * [账户]发送验证码
     *
     * @description 发送手机验证码，用于修改手机号等操作
     *
     * @authenticated 需要技师身份认证
     *
     * @bodyParam mobile string required 手机号 Example: 13800138000
     * @bodyParam type string required 验证码类型(update:修改手机号) Example: "update"
     *
     * @response {
     *   "status": true,
     *   "message": "验证码发送成功",
     *   "data": {
     *     "mobile": "138****8000",
     *     "expire_time": 300
     *   }
     * }
     *
     * @response 422 {
     *   "message": "该手机号已被使用"
     * }
     */
    public function sendVerifyCode(SendVerifyCodeRequest $request)
    {
        return $this->success(
            $this->service->sendVerifyCode($request->validated())
        );
    }

    /**
     * [账户]获取已开通项目
     *
     * @description 获取技师已开通的服务项目列表
     *
     * @authenticated 需要技师身份认证
     *
     * @response {
     *   "status": true,
     *   "message": "获取成功",
     *   "data": {
     *     "total": 2,
     *     "list": [
     *       {
     *         "id": 1,
     *         "project_id": 100,
     *         "project_name": "全身按摩",
     *         "category_id": 1,
     *         "category_name": "按摩",
     *         "duration": 60,
     *         "price": 200.00,
     *         "discount_amount": 20.00,
     *         "final_price": 180.00,
     *         "service_gender": "all",
     *         "service_distance": 5000,
     *         "traffic_fee_type": "round_trip",
     *         "traffic_fee": 10.00,
     *         "created_at": "2024-03-16 10:00:00",
     *         "updated_at": "2024-03-16 10:00:00"
     *       }
     *     ]
     *   }
     * }
     */
    public function enabledProjects()
    {
        return $this->success(
            $this->service->getEnabledProjects(Auth::user()->coach->id)
        );
    }
}