257 lines
11 KiB
Markdown
257 lines
11 KiB
Markdown
# 微信 H5 授权流程重构 - 设计文档
|
||
|
||
## 📋 核心业务需求
|
||
|
||
在微信 H5 环境中，**整个应用在没有有效 token 时，都需要进行微信授权登录**。授权完成后，用户应该被重定向回他们尝试访问的原始页面。
|
||
|
||
---
|
||
|
||
## 🔄 流程设计
|
||
|
||
### **完整的授权流程图**
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 用户在微信中访问任意页面（无 token） │
|
||
└──────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 路由守卫检测：微信 + 无 token │
|
||
│ → 保存目标路由到 authStore.pendingRoute │
|
||
│ → 生成微信授权 URL │
|
||
│ → window.location.href = 授权 URL （不调用 next()） │
|
||
└──────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 跳转到微信授权页面 │
|
||
│ https://open.weixin.qq.com/connect/oauth2/authorize?... │
|
||
└──────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
┌─────────┴─────────┐
|
||
│ 用户点击"同意" │
|
||
└────────┬──────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 微信回调：redirectUri?code=xxx&state=yyy │
|
||
│ 浏览器重新加载应用，URL 中包含 code/state 参数 │
|
||
└──────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ App.vue onMounted 检测到 code + state 参数 │
|
||
│ → 调用 handleWeixinAuthCallback(code) │
|
||
└──────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 1. 调用后端接口 /user/wxh5Auth 交换 token │
|
||
│ 2. 保存 token 到 localStorage │
|
||
│ 3. 清理 URL 中的 code/state 参数 │
|
||
│ 4. 获取用户信息 │
|
||
│ 5. 标记授权完成 authStore.completeWeixinAuth() │
|
||
└──────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 获取 pendingRoute，重定向回原始页面 │
|
||
│ router.replace(pendingRoute) │
|
||
│ 如果没有 pendingRoute，重定向到首页 "/" │
|
||
└──────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ ✅ 授权完成，用户看到原始页面 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 关键文件修改
|
||
|
||
### **1. `src/router/index.js` - 路由守卫**
|
||
|
||
**关键变化：**
|
||
- 检测到 **微信 + 无 token** 的情况
|
||
- **直接发起授权**（调用 `window.location.href`）
|
||
- **不调用 `next()`**，完全停止导航
|
||
- 授权 URL 中的 redirectUri 指向当前页面（清理旧的 code/state 参数）
|
||
|
||
**代码片段：**
|
||
```javascript
|
||
if (isWeChat.value && !isAuthenticated && !isTokenExpired) {
|
||
// 保存目标路由
|
||
authStore.startWeixinAuth(to);
|
||
|
||
// 生成授权 URL
|
||
const appId = import.meta.env.VITE_WECHAT_APP_ID;
|
||
const url = new URL(window.location.href);
|
||
const params = new URLSearchParams(url.search);
|
||
params.delete("code");
|
||
params.delete("state");
|
||
const cleanUrl = `${url.origin}${url.pathname}${params.toString() ? "?" + params.toString() : ""}`;
|
||
const redirectUri = encodeURIComponent(cleanUrl);
|
||
const weixinAuthUrl = `https://open.weixin.qq.com/connect/oauth2/authorize?appid=${appId}&redirect_uri=${redirectUri}&response_type=code&scope=snsapi_base&state=snsapi_base#wechat_redirect`;
|
||
|
||
// 直接跳转，不调用 next()
|
||
window.location.href = weixinAuthUrl;
|
||
return;
|
||
}
|
||
```
|
||
|
||
### **2. `src/App.vue` - 授权回调处理**
|
||
|
||
**关键职责：**
|
||
1. **检测回调**：读取 URL 中的 code/state 参数
|
||
2. **处理回调**：调用 `/user/wxh5Auth` 交换 token
|
||
3. **恢复导航**：使用保存的 pendingRoute 重定向用户
|
||
|
||
**核心函数：`handleWeixinAuthCallback(code)`**
|
||
```javascript
|
||
const handleWeixinAuthCallback = async (code) => {
|
||
// 1. 交换 token
|
||
const { data, error } = await useApiFetch("/user/wxh5Auth").post({ code }).json();
|
||
|
||
// 2. 保存 token
|
||
localStorage.setItem("token", data.value.data.accessToken);
|
||
localStorage.setItem("refreshAfter", data.value.data.refreshAfter);
|
||
localStorage.setItem("accessExpire", data.value.data.accessExpire);
|
||
|
||
// 3. 清理 URL
|
||
const url = new URL(window.location.href);
|
||
const params = new URLSearchParams(url.search);
|
||
params.delete("code");
|
||
params.delete("state");
|
||
window.history.replaceState({}, "", newUrl);
|
||
|
||
// 4. 获取用户信息
|
||
await userStore.fetchUserInfo();
|
||
|
||
// 5. 标记授权完成
|
||
authStore.completeWeixinAuth();
|
||
|
||
// 6. 重定向回 pendingRoute
|
||
const pendingRoute = authStore.pendingRoute;
|
||
await router.replace(pendingRoute || "/");
|
||
};
|
||
```
|
||
|
||
### **3. `src/stores/authStore.js` - 授权状态管理**
|
||
|
||
**关键方法：**
|
||
|
||
| 方法 | 作用 |
|
||
|------|------|
|
||
| `startWeixinAuth(targetRoute)` | 开始授权，保存目标路由 |
|
||
| `completeWeixinAuth()` | 标记授权完成 |
|
||
| `clearPendingRoute()` | 清除待处理路由 |
|
||
| `resetAuthState()` | 重置所有授权状态 |
|
||
| `restoreFromStorage()` | 页面刷新后恢复状态 |
|
||
|
||
---
|
||
|
||
## 🎯 核心特性
|
||
|
||
### **1. 同步流程控制**
|
||
- ❌ **不使用** `watch` 监听 state 的变化
|
||
- ❌ **不使用** 异步的 route guard + next() 来触发授权
|
||
- ✅ **直接** 在 route guard 中调用 `window.location.href` 发起授权
|
||
|
||
**为什么？**
|
||
- Watch 是异步的，可能被路由完成打断
|
||
- next() 后可能路由已经切换，导致授权流程混乱
|
||
- 直接跳转 URL 更加可靠和同步
|
||
|
||
### **2. 状态持久化**
|
||
- 授权开始时保存到 localStorage
|
||
- 页面刷新时自动恢复状态
|
||
- 防止超时（30秒）导致的无限授权循环
|
||
|
||
### **3. URL 参数清理**
|
||
- 每次发起授权前，都清理 URL 中旧的 code/state 参数
|
||
- 防止参数被重复编码进 redirectUri
|
||
- 微信回调时才注入新的 code/state
|
||
|
||
### **4. 目标页面恢复**
|
||
- 路由守卫保存用户尝试访问的页面
|
||
- 授权完成后自动重定向到该页面
|
||
- 用户无感知的完整授权体验
|
||
|
||
---
|
||
|
||
## 🔐 场景处理
|
||
|
||
### **场景 1：无 token + 访问开放页面**
|
||
```
|
||
用户访问 "/" → 微信检测无 token → 发起授权 → 授权完成后回到首页
|
||
```
|
||
|
||
### **场景 2：无 token + 访问推广链接**
|
||
```
|
||
用户访问 "/agent/promotionInquire/abc123"
|
||
→ 微信检测无 token
|
||
→ 保存 pendingRoute = "/agent/promotionInquire/abc123"
|
||
→ 发起授权
|
||
→ 授权完成后回到 "/agent/promotionInquire/abc123"
|
||
```
|
||
|
||
### **场景 3：有效 token + 访问任意页面**
|
||
```
|
||
用户有 token 且未过期 → 路由守卫放行 → 直接加载页面，无授权
|
||
```
|
||
|
||
### **场景 4：Token 过期 + 访问需登录页面**
|
||
```
|
||
用户在非微信环境 → 检测到 token 过期 → 跳转登录页面
|
||
```
|
||
|
||
### **场景 5：授权超时**
|
||
```
|
||
用户授权流程中，30 秒内未完成 → 自动重置状态 → 页面刷新时重新授权
|
||
```
|
||
|
||
---
|
||
|
||
## 🐛 常见问题排查
|
||
|
||
### **Q1：为什么授权后没有跳到原页面？**
|
||
**A：** 检查 authStore 中是否有 pendingRoute
|
||
```javascript
|
||
console.log('pendingRoute:', authStore.pendingRoute);
|
||
```
|
||
|
||
### **Q2：为什么一直在授权页面循环？**
|
||
**A：** 可能是授权回调处理失败。检查：
|
||
1. 后端 `/user/wxh5Auth` 接口是否正确返回 token
|
||
2. Token 是否正确保存到 localStorage
|
||
3. URL 中的 code/state 是否正确清理
|
||
|
||
### **Q3：为什么刷新页面后授权状态丢失？**
|
||
**A：** authStore.restoreFromStorage() 应该在 onMounted 中被调用。检查：
|
||
```javascript
|
||
authStore.restoreFromStorage(); // 这行很重要！
|
||
```
|
||
|
||
### **Q4：在 PC 上测试，为什么无法触发授权？**
|
||
**A：** 授权只在微信环境中触发（isWeChat.value === true）。在 PC 上：
|
||
- 访问需登录的页面 → 跳转登录页
|
||
- 访问开放页面 → 正常加载
|
||
|
||
---
|
||
|
||
## 📝 总结
|
||
|
||
这个重构的核心思想是：
|
||
1. **路由守卫 = 决策者**：检测到需要授权就立即发起
|
||
2. **App.vue = 处理器**：处理授权回调和状态恢复
|
||
3. **AuthStore = 状态管理**：保存和恢复授权相关的状态
|
||
4. **同步流程 = 高可靠性**：避免异步竞态条件
|
||
|
||
通过这个设计，微信授权流程变得：
|
||
- ✅ 清晰易懂
|
||
- ✅ 可靠稳定
|
||
- ✅ 易于测试和调试
|
||
- ✅ 完整的用户体验
|