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

<?php

namespace App\Http\Controllers\Client;

use App\Http\Controllers\Controller;
use App\Http\Requests\Client\Wechat\GetAuthUrlRequest;
use App\Http\Requests\Client\Wechat\HandleCallbackRequest;
use App\Services\Client\WechatService;

/**
 * @group 用户端
 *
 * 微信相关的API接口
 */
class WechatController extends Controller
{
    protected WechatService $wechatService;

    public function __construct(WechatService $wechatService)
    {
        $this->wechatService = $wechatService;
    }

    /**
     * [微信]获取微信授权URL
     *
     * @description 获取微信网页授权URL
     *
     * @queryParam redirect_url required 授权后的回调地址，必须是有效的URL Example: https://example.com/callback
     * @queryParam scope 授权范围，可选值：snsapi_base,snsapi_userinfo Example: snsapi_userinfo
     *
     * @response 200 scenario="成功" {
     *   "code": 200,
     *   "data": {
     *     "auth_url": "https://open.weixin.qq.com/connect/oauth2/authorize?appid=wx123456&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&response_type=code&scope=snsapi_userinfo&state=7d8f69a...",
     *     "state": "7d8f69a..."
     *   }
     * }
     * @response 422 scenario="参数验证失败" {
     *   "code": 422,
     *   "message": "回调地址不能为空|回调地址必须是一个有效的URL"
     * }
     * @response 400 scenario="参数错误" {
     *   "code": 400,
     *   "message": "生成授权链接失败，请稍后重试"
     * }
     *
     * @throws BusinessException
     */
    public function getAuthUrl(GetAuthUrlRequest $request)
    {
        $validated = $request->validated();

        $result = $this->wechatService->getAuthUrl(
            $validated['redirect_url'],
            $validated['scope'] ?? 'snsapi_userinfo'
        );

        return $this->success($result);
    }

    /**
     * [微信]处理微信授权回调
     *
     * @description 处理微信授权回调，完成登录。用于接收微信授权后的回调，处理用户登录注册流程。
     *
     * @bodyParam code string required 微信授权码 Example: 071Jh6ll2tQfM54Kjtol2pWDCE1Jh6lH
     * @bodyParam state string required 状态码，需要与获取授权URL时返回的state一致，长度必须为32位 Example: 7d8f69a...
     *
     * @response 200 scenario="成功" {
     *   "code": 200,
     *   "data": {
     *     "token": "1|2uyxxxxxxxxxx",
     *     "user": {
     *       "id": 1,
     *       "nickname": "张三",
     *       "avatar": "https://thirdwx.qlogo.cn/mmopen/xxx/132",
     *       "gender": "male",
     *       "country": "中国",
     *       "province": "广东",
     *       "city": "深圳",
     *       "created_at": "2024-01-01 00:00:00",
     *       "updated_at": "2024-01-01 00:00:00"
     *     }
     *   }
     * }
     * @response 422 scenario="参数验证失败" {
     *   "code": 422,
     *   "message": "授权码不能为空|状态码长度必须为32位"
     * }
     * @response 400 scenario="无效的state" {
     *   "code": 400,
     *   "message": "无效的授权请求"
     * }
     * @response 400 scenario="授权失败" {
     *   "code": 400,
     *   "message": "微信授权失败，请稍后重试"
     * }
     *
     * @throws BusinessException 当授权验证失败或处理出错时抛出
     */
    public function handleCallback(HandleCallbackRequest $request)
    {
        $validated = $request->validated();

        $result = $this->wechatService->handleAuthCallback(
            $validated['code'],
            $validated['state'],
            $validated['invite_code'] ?? null
        );

        return $this->success($result);
    }
}