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

<?php

namespace App\Http\Controllers\Client;

use App\DTOs\CoachApplicationDTO;
use App\Http\Controllers\Controller;
use App\Services\Client\UserService;
use Illuminate\Support\Facades\Auth;
use App\Http\Resources\Client\UserResource;
use App\Http\Requests\Client\User\UpdateRequest;
use App\Http\Requests\Client\User\FeedbackRequest;
use App\Http\Requests\Client\User\RegisterRequest;
use App\Http\Requests\Client\User\ApplyCoachRequest;

/**
 * @group 用户端
 *
 * 用户相关的API接口
 */
class UserController extends Controller
{
    protected UserService $service;

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

    /**
     * [用户]获取用户信息
     *
     * @description 获取当前登录用户的详细信息
     *
     * @authenticated
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "获取成功",
     *   "data": {
     *     "id": 1,
     *     "mobile": "13800138000",
     *     "nickname": "张三",
     *     "avatar": "https://example.com/avatar.jpg",
     *     "gender": "male",
     *     "created_at": "2024-03-20 10:00:00",
     *     "updated_at": "2024-03-20 10:00:00"
     *   }
     * }
     * @response 401 {
     *   "code": 401,
     *   "message": "请先登录",
     *   "data": null
     * }
     */
    public function show()
    {
        $data = $this->service->getUserInfo();

        return $this->success(new UserResource($data));
    }

    /**
     * [用户]用户注册
     *
     * @description 新用户注册接口，支持邀请注册功能
     *
     * @bodyParam mobile string required 手机号码 Example: 13800138000
     * @bodyParam code string required 短信验证码 Example: 123456
     * @bodyParam invite_code string optional 邀请码 Example: ABC123
     * @bodyParam invite_id integer optional 邀请人ID Example: 1
     * @bodyParam invite_role string optional 邀请人角色(user/coach) Example: user
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "注册成功",
     *   "data": {
     *     "user_id": 1,
     *     "mobile": "13800138000",
     *     "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
     *     "invite_code": "DEF456"
     *   }
     * }
     * @response 422 {
     *   "code": 422,
     *   "message": "验证失败",
     *   "errors": {
     *     "mobile": ["手机号格式不正确"],
     *     "code": ["验证码错误"]
     *   }
     * }
     */
    public function register(RegisterRequest $request)
    {
        $validated = $request->validated();

        $data = $this->service->register(
            $validated['mobile'],
            $validated['code'],
            $validated['invite_code'] ?? null,
            $validated['invite_id'] ?? null,
            $validated['invite_role'] ?? null
        );

        return $this->success($data, '注册成功');
    }

    /**
     * [用户]修改用户信息
     *
     * @description 修改当前登录用户的基本信息，包括昵称、头像和性别
     *
     * @authenticated
     *
     * @bodyParam nickname string optional 用户昵称 Example: 张三
     * @bodyParam avatar string optional 头像URL Example: https://example.com/avatar.jpg
     * @bodyParam gender integer optional 性别(0:未知/1:男/2:女) Example: 1
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "修改成功",
     *   "data": {
     *     "id": 1,
     *     "nickname": "张三",
     *     "avatar": "https://example.com/avatar.jpg",
     *     "gender": 1,
     *     "gender_text": "男",
     *     "updated_at": "2024-03-20 10:00:00"
     *   }
     * }
     * @response 422 {
     *   "code": 422,
     *   "message": "验证失败",
     *   "errors": {
     *     "avatar": ["头像必须是有效的URL地址"]
     *   }
     * }
     */
    public function update(UpdateRequest $request)
    {
        $validated = $request->validated();

        $result = $this->service->updateUserInfo($validated);

        return $this->success($result, '修改成功');
    }

    /**
     * [用户]用户反馈
     *
     * @description 提交用户反馈信息
     *
     * @authenticated
     *
     * @bodyParam content string required 反馈内容 Example: 系统使用体验很好，建议增加更多功能
     * @bodyParam images array optional 图片数组 Example: ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
     * @bodyParam contact string optional 联系方式 Example: 13800138000
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "反馈提交成功",
     *   "data": {
     *     "id": 1,
     *     "content": "系统使用体验很好，建议增加更多功能",
     *     "images": ["https://example.com/image1.jpg"],
     *     "created_at": "2024-03-20 10:00:00"
     *   }
     * }
     * @response 422 {
     *   "code": 422,
     *   "message": "内容不能为空",
     *   "data": null
     * }
     */
    public function feedback(FeedbackRequest $request)
    {
        $validated = $request->validated();

        $result = $this->service->feedback(
            $validated['content'],
            $validated['images'] ?? [],
            $validated['contact'] ?? null
        );

        return $this->success($result, '反馈提交成功');
    }

    /**
     * [用户]申请成为技师
     *
     * @description 普通用户申请成为平台技师，提交技师申请信息
     *
     * 业务流程：
     * 1. 检查用户申请资格
     * 2. 创建或更新技师基础信息
     * 3. 创建申请记录
     *
     * 注意事项：
     * - 同一时间只能有一条待审核申请
     * - 已是技师的用户不能重复申请
     * - 生活照片支持任意格式的图片数据
     * - 年龄必须在18-60岁之间
     * - 工作年限不能超过实际年龄
     *
     * @authenticated 需要用户身份认证
     *
     * @bodyParam age integer required 年龄(18-60岁) Example: 25
     * @bodyParam mobile string required 联系电话 Example: 13800138000
     * @bodyParam gender integer required 性别(1:男/2:女) Example: 1
     * @bodyParam work_years integer required 工作年限(0-50年) Example: 5
     * @bodyParam intention_city string required 意向城市 Example: 杭州
     * @bodyParam life_photos array required 生活照片(最多6张)
     * @bodyParam life_photos.* string required 生活照片 Example: base64或其他格式的图片数据
     * @bodyParam introduction string optional 个人简介(最多1000字) Example: 专业按摩师，有多年经验
     *
     * @response 200 {
     *   "status": true,
     *   "message": "申请提交成功",
     *   "data": {
     *     "id": 1,
     *     "coach_id": 100,
     *     "age": 25,
     *     "mobile": "13800138000",
     *     "gender": 1,
     *     "work_years": 5,
     *     "intention_city": "杭州",
     *     "life_photos": [
     *         "base64或其他格式的图片数据1",
     *         "base64或其他格式的图片数据2"
     *     ],
     *     "introduction": "专业按摩师，有多年经验",
     *     "state": "auditing",
     *     "created_at": "2024-03-20 10:00:00",
     *     "updated_at": "2024-03-20 10:00:00"
     *   }
     * }
     * @response 422 {
     *   "message": "您已是技师，无需重复申请"
     * }
     * @response 422 {
     *   "message": "您有正在审核的申请，请耐心等待"
     * }
     * @response 422 {
     *   "message": "验证错误",
     *   "errors": {
     *     "mobile": ["手机号码格式不正确"],
     *     "gender": ["性别只能是1(男)或2(女)"],
     *     "work_years": ["工作年限必须是0-50之间的整数"],
     *     "intention_city": ["意向城市不能为空"],
     *     "life_photos": ["生活照片不能为空"],
     *     "life_photos.*": ["图片格式不正确"]
     *   }
     * }
     */
    public function applyCoach(ApplyCoachRequest $request)
    {
        $dto = CoachApplicationDTO::fromRequest($request->validated());

        $result = $this->service->applyCoach($dto);

        return $this->success($result, '申请提交成功');
    }

    /**
     * [用户]生成邀请二维码
     *
     * @description 生成当前用户专属的邀请码和邀请二维码，支持普通用户和技师两种身份
     *
     * @authenticated
     *
     * @queryParam type string required 邀请码类型(user:普通用户/coach:技师) Example: user
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "生成成功",
     *   "data": {
     *     "invite_code": "user_1",
     *     "invite_url": "https://example.com/invite?invite_id=1&invite_role=user&invite_code=user_1",
     *     "qr_code": "data:image/svg+xml;base64,..."
     *   }
     * }
     * @response 401 {
     *   "code": 401,
     *   "message": "请先登录",
     *   "data": null
     * }
     * @response 422 {
     *   "code": 422,
     *   "message": "无法生成邀请码，用户类型不匹配",
     *   "data": null
     * }
     */
    public function generateInviteCode()
    {
        $result = $this->service->generateInviteCode();

        return $this->success($result, '生成成功');
    }

    /**
     * [用户]查看技师申请记录
     *
     * @description 获取当前用户的技师申请记录，如果用户不是技师或没有申请记录则返回 null
     *
     * @authenticated
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "获取成功",
     *   "data": {
     *     "id": 1,
     *     "coach_id": 100,
     *     "age": 25,
     *     "mobile": "13800138000",
     *     "gender": 1,
     *     "work_years": 5,
     *     "intention_city": "杭州",
     *     "portrait_images": ["https://example.com/portrait1.jpg"],
     *     "introduction": "专业按摩师，有多年经验",
     *     "state": 1,
     *     "state_text": "待审核",
     *     "created_at": "2024-03-20 10:00:00",
     *     "updated_at": "2024-03-20 10:00:00"
     *   }
     * }
     * @response 200 {
     *   "code": 200,
     *   "message": "您还不是技师",
     *   "data": null
     * }
     * @response 200 {
     *   "code": 200,
     *   "message": "暂无申请记录",
     *   "data": null
     * }
     * @response 401 {
     *   "code": 401,
     *   "message": "请先登录",
     *   "data": null
     * }
     */
    public function getCoachApplication()
    {
        $result = $this->service->getCoachApplication();

        // 如果用户不是技师
        if ($result === null && ! Auth::user()->coach) {
            return $this->success(null, '您还不是技师');
        }

        // 如果是技师但没有申请记录
        if ($result === null) {
            return $this->success(null, '暂无申请记录');
        }

        return $this->success($result, '获取成功');
    }
}