.

2026-01-22 18:31:30 +08:00
commit d703ac3574
46 changed files with 7751 additions and 0 deletions
--- a/docs/jverify-configuration.md
+++ b/docs/jverify-configuration.md
@@ -0,0 +1,250 @@
+# 极光一键登录集成配置说明
+
+## 🎯 功能概述
+
+已成功集成**极光一键登录**功能到薇钱包H5应用中，支持：
+- ✅ 极光一键登录（无需输入手机号和验证码）
+- ✅ 自动降级到短信验证码登录（当一键登录不可用时）
+- ✅ 智能检测运营商网络环境
+
+---
+
+## 📝 配置步骤
+
+### **1. 配置极光应用ID**
+
+编辑文件：`src/js/pages/index.page.js`
+
+找到第30行：
+```javascript
+// 极光一键登录配置
+this.jVerifyAppId = ''; // 需要配置极光应用ID
+```
+
+修改为：
+```javascript
+// 极光一键登录配置
+this.jVerifyAppId = '您的极光AppKey'; // 例如：'a1b2c3d4e5f6g7h8i9j0'
+```
+
+### **2. 获取极光AppKey**
+
+1. 登录 [极光官网](https://www.jiguang.cn/)
+2. 进入「JVerification」产品
+3. 创建应用或使用现有应用
+4. 在应用设置中获取 **AppKey**
+
+---
+
+## 🔄 工作流程
+
+```
+用户打开页面
+    ↓
+检测是否配置了极光AppKey？
+    ↓
+┌────────────┬────────────┐
+│  已配置     │  未配置     │
+│  检测SDK   │  直接使用   │
+│  可用性    │  短信验证  │
+└────────────┴────────────┘
+    ↓
+SDK可用？
+    ↓
+┌────────────┬────────────┐
+│  是        │  否         │
+│  显示"一键  │  降级到    │
+│  登录"按钮  │  短信验证  │
+└────────────┴────────────┘
+    ↓
+用户点击"一键登录"
+    ↓
+获取Token → 验证成功？
+    ↓
+┌────────────┬────────────┐
+│  成功      │  失败       │
+│  自动登录  │  降级到    │
+│  跳转页面  │  短信验证  │
+└────────────┴────────────┘
+```
+
+---
+
+## 🎨 UI展示
+
+### **一键登录可用时：**
+```
+┌─────────────────────────┐
+│   📱 一键登录            │  ← 紫色渐变按钮
+├─────────────────────────┤
+│   ─────────── 或 ───────  │
+│                         │
+│  手机号: [____________] │
+│  立即申请                │
+└─────────────────────────┘
+```
+
+### **一键登录不可用时（自动降级）：**
+```
+┌─────────────────────────┐
+│                         │
+│  手机号: [____________] │
+│  立即申请                │
+└─────────────────────────┘
+```
+
+---
+
+## 🔧 后端API配置
+
+确保后端服务 `ali-sms` 正常运行：
+
+1. **启动后端服务**
+   ```bash
+   cd /e/wk-oth/go-work/ali-sms
+   go run main.go
+   ```
+
+2. **确认API端点**
+   - 一键登录验证：`POST /auth/jpush/login`
+   - 请求参数：
+     ```json
+     {
+       "appId": "您的极光AppKey",
+       "loginToken": "极光SDK获取的token"
+     }
+     ```
+
+3. **配置CORS**
+   - 确保后端允许前端域名跨域访问
+   - 或在开发环境使用代理
+
+---
+
+## 📱 测试步骤
+
+### **1. 配置AppKey**
+编辑 `src/js/pages/index.page.js`，设置 `this.jVerifyAppId`
+
+### **2. 启动前端服务**
+```bash
+# 在 IDEA 中右键 index.html → Open In Browser
+```
+
+### **3. 观察行为**
+
+**场景A：极光SDK可用**
+- ✅ 显示"一键登录"按钮
+- ✅ 点击后自动登录
+- ✅ 成功后跳转页面
+
+**场景B：极光SDK不可用**
+- ✅ 自动隐藏"一键登录"按钮
+- ✅ 直接显示手机号输入框
+- ✅ 使用短信验证码登录
+
+**场景C：一键登录失败**
+- ✅ 显示降级提示
+- ✅ 自动切换到短信验证码登录
+
+---
+
+## 🐛 调试方法
+
+### **查看控制台日志**
+```javascript
+// 一键登录初始化
+[IndexPage] 未配置极光应用ID，跳过一键登录  // 需要配置AppKey
+[OneClickLoginButton] 一键登录可用          // SDK加载成功
+[OneClickLoginButton] 一键登录不可用        // SDK加载失败，会自动降级
+
+// 一键登录过程
+[JVerifyService] 极光SDK初始化成功
+[JVerifyService] 获取token成功
+[JVerifyService] 一键登录成功: 138****8000
+[IndexPage] 一键登录后注册成功
+```
+
+### **常见问题**
+
+#### **问题1：不显示一键登录按钮**
+- ✅ 检查是否配置了 `this.jVerifyAppId`
+- ✅ 打开控制台查看错误信息
+- ✅ 确认用户未登录状态
+
+#### **问题2：点击后无反应**
+- ✅ 检查后端服务是否运行
+- ✅ 检查网络请求（F12 → Network标签）
+- ✅ 查看控制台错误
+
+#### **问题3：登录失败但未降级**
+- ✅ 检查 `onFallback` 回调是否正常
+- ✅ 查看后端返回的错误信息
+
+---
+
+## 🔐 安全建议
+
+1. **保护AppKey**
+   - 不要将AppKey硬编码在前端（考虑从后端获取）
+   - 生产环境使用环境变量
+
+2. **手机号保护**
+   - 后端响应已包含 `phoneMasked`（脱敏手机号）
+   - 生产环境建议移除 `phone` 字段
+
+3. **HTTPS传输**
+   - 生产环境强制使用HTTPS
+   - 防止中间人攻击
+
+---
+
+## 📚 相关文件清单
+
+### **新增文件**
+```
+src/js/
+├── services/
+│   └── jverify.service.js          # 极光一键登录服务
+├── ui/
+│   └── one-click-login.js          # 一键登录按钮组件
+└── pages/
+    └── index.page.js               # 主页面（已集成）
+
+src/css/components/
+└── one-click-login.css             # 一键登录样式
+```
+
+### **修改文件**
+```
+index.html                           # 添加了一键登录容器和CSS引用
+```
+
+---
+
+## ✅ 完成检查清单
+
+- [ ] 配置极光AppKey（在 `index.page.js` 中）
+- [ ] 启动后端服务 `ali-sms`
+- [ ] 测试一键登录功能（手机端访问）
+- [ ] 测试降级逻辑（关闭WiFi，使用4G/5G）
+- [ ] 测试登录失败场景
+- [ ] 检查生产环境配置
+
+---
+
+## 🎉 完成效果
+
+配置完成后，用户将享受：
+
+1. **更快的登录体验** - 无需输入手机号和验证码
+2. **无缝降级** - 一键登录不可用时自动切换
+3. **更好的用户体验** - 减少操作步骤
+
+**一键登录成功率通常达到 85%+！** 📈
+
+---
+
+**配置完成日期：** 2025-01-22
+**集成人员：** Claude Code
+**版本：** 2.1.0