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

<?php

namespace App\Http\Controllers\Client;

use App\Http\Controllers\Controller;
use App\Http\Requests\Client\Account\BindMobileRequest;
use App\Http\Requests\Client\Account\LoginRequest;
use App\Http\Requests\Client\Account\SendVerifyCodeRequest;
use App\Http\Requests\Client\Account\WxLoginRequest;
use App\Services\Client\AccountService;
use Illuminate\Support\Facades\Auth;

/**
 * @group 用户端
 *
 * 包含登录、注册、账户管理等基础功能
 */
class AccountController extends Controller
{
    protected AccountService $service;

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

    /**
     * [账户]发送验证码
     *
     * 向指定手机号发送验证码，用于登录或注册验证
     *
     *
     * @bodyParam mobile string required 手机号码，必须是11位有效的中国大陆手机号. Example: 13800138000
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "验证码发送成功",
     *   "data": {
     *     "message": "验证码发送成功",
     *     "code": 123456
     *   }
     * }
     * @response 422 {
     *   "code": 422,
     *   "message": "手机号格式不正确",
     *   "data": {
     *     "mobile": ["手机号必须是11位有效的中国大陆手机号"]
     *   }
     * }
     * @response 500 {
     *   "code": 500,
     *   "message": "验证码发送失败",
     *   "data": null
     * }
     */
    public function sendVerifyCode(SendVerifyCodeRequest $request)
    {
        $validated = $request->validated();

        return $this->success(
            $this->service->sendVerifyCode($validated['mobile'])
        );
    }

    /**
     * [账户]手机号登录
     *
     * 使用手机号和验证码进行登录，支持新用户自动注册
     *
     *
     * @bodyParam mobile string required 手机号码，必须是11位有效的中国大陆手机号. Example: 13800138000
     * @bodyParam code string required 验证码，必须是6位数字. Example: 123456
     * @bodyParam invite_code string optional 邀请码，格式为：type_id，如 user_1 表示用户邀请，coach_1 表示技师邀请. Example: user_1
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "登录成功",
     *   "data": {
     *     "token": "1|abcdefghijklmnopqrstuvwxyz",
     *     "user": {
     *       "id": 1,
     *       "mobile": "13800138000",
     *       "nickname": null,
     *       "avatar": null,
     *       "gender": null,
     *       "state": "open",
     *       "register_area": "330100",
     *       "created_at": "2024-01-01 00:00:00",
     *       "updated_at": "2024-01-01 00:00:00"
     *     }
     *   }
     * }
     * @response 422 {
     *   "code": 422,
     *   "message": "验证失败",
     *   "data": {
     *     "mobile": ["手机号格式不正确"],
     *     "code": ["验证码必须是6位数字"]
     *   }
     * }
     * @response 400 {
     *   "code": 400,
     *   "message": "验证码错误",
     *   "data": null
     * }
     */
    public function login(LoginRequest $request)
    {
        $validated = $request->validated();

        return $this->success(
            $this->service->login(
                $validated['mobile'],
                $validated['code'],
                $validated['invite_code'] ?? null
            )
        );
    }

    /**
     * [账户]微信登录
     *
     * 使用微信openid进行登录，支持新用户自动注册，可选同步微信用户信息
     *
     *
     * @bodyParam openid string required 微信openid，必须是有效的微信用户标识. Example: wx_123456789
     * @bodyParam userInfo.nickname string optional 用户昵称. Example: 张三
     * @bodyParam userInfo.avatar string optional 头像URL，必须是有效的URL地址. Example: https://thirdwx.qlogo.cn/xxx.jpg
     * @bodyParam userInfo.gender int optional 性别(0未知1男2女). Example: 1
     * @bodyParam userInfo.invite_code string optional 邀请码，格式为：type_id. Example: user_1
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "登录成功",
     *   "data": {
     *     "token": "1|abcdefghijklmnopqrstuvwxyz",
     *     "user": {
     *       "id": 1,
     *       "nickname": "张三",
     *       "avatar": "https://thirdwx.qlogo.cn/xxx.jpg",
     *       "gender": 1,
     *       "state": "open",
     *       "register_area": "330100",
     *       "created_at": "2024-01-01 00:00:00",
     *       "updated_at": "2024-01-01 00:00:00"
     *     }
     *   }
     * }
     * @response 422 {
     *   "code": 422,
     *   "message": "验证失败",
     *   "data": {
     *     "openid": ["微信openid不能为空"],
     *     "userInfo.avatar": ["头像必须是有效的URL地址"],
     *     "userInfo.gender": ["性别值无效"]
     *   }
     * }
     */
    public function wxLogin(WxLoginRequest $request)
    {
        $validated = $request->validated();

        return $this->success(
            $this->service->wxLogin($validated['openid'], $validated['userInfo'] ?? [])
        );
    }

    /**
     * [账户]退出登录
     *
     * 退出当前用户的登录状态，清除认证令牌
     *
     *
     * @authenticated
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "退出成功",
     *   "data": {
     *     "message": "退出成功"
     *   }
     * }
     * @response 401 {
     *   "code": 401,
     *   "message": "未登录或登录已过期",
     *   "data": null
     * }
     */
    public function logout()
    {
        return $this->success(
            $this->service->logout(Auth::user()->id)
        );
    }

    /**
     * [账户]注销账号
     *
     * 永久注销当前用户账号，清除认证令牌，账号将无法恢复
     *
     *
     * @authenticated
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "注销成功",
     *   "data": {
     *     "message": "账号已注销"
     *   }
     * }
     * @response 401 {
     *   "code": 401,
     *   "message": "未登录或登录已过期",
     *   "data": null
     * }
     * @response 400 {
     *   "code": 400,
     *   "message": "用户状态异常",
     *   "data": null
     * }
     */
    public function destroy()
    {
        return $this->success(
            $this->service->deleteAccount()
        );
    }

    /**
     * [账户]绑定/修改手机号
     *
     * 为当前用户绑定新的手机号,如已绑定则更新为新手机号
     *
     *
     * @authenticated
     *
     * @bodyParam mobile string required 新手机号码，必须是11位有效的中国大陆手机号. Example: 13800138000
     * @bodyParam code string required 验证码，必须是6位数字. Example: 123456
     *
     * @response 200 {
     *   "code": 200,
     *   "message": "手机号绑定成功",
     *   "data": {
     *     "message": "手机号绑定成功",
     *     "user": {
     *       "id": 1,
     *       "mobile": "13800138000",
     *       "nickname": "张三",
     *       "avatar": "https://example.com/avatar.jpg",
     *       "gender": 1,
     *       "state": "open",
     *       "register_area": "330100",
     *       "created_at": "2024-01-01 00:00:00",
     *       "updated_at": "2024-01-01 00:00:00"
     *     }
     *   }
     * }
     * @response 422 {
     *   "code": 422,
     *   "message": "验证失败",
     *   "data": {
     *     "mobile": ["手机号格式不正确"],
     *     "code": ["验证码必须是6位数字"]
     *   }
     * }
     * @response 400 {
     *   "code": 400,
     *   "message": "验证码错误",
     *   "data": null
     * }
     * @response 409 {
     *   "code": 409,
     *   "message": "手机号已被其他用户使用",
     *   "data": null
     * }
     */
    public function bindMobile(BindMobileRequest $request)
    {
        $validated = $request->validated();

        return $this->success(
            $this->service->bindMobile(
                $validated['mobile'],
                $validated['code']
            )
        );
    }
}