flux-web/docs/jverify-configuration.md

# 极光一键登录集成配置说明

## 🎯 功能概述

已成功集成**极光一键登录**功能到薇钱包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配置

后端服务部署在服务器上（非本地开发环境）

1. **API端点**
   - 一键登录验证：`POST /zcore/jpush/login`
   - 请求参数：
     ```json
     {
       "appId": "您的极光AppKey",
       "loginToken": "极光SDK获取的token"
     }
     ```

2. **本地开发配置**
   - 如需本地调试前端，请在 `src/js/config/index.js` 中配置 API 代理
   - 或直接修改 `src/js/services/jverify.service.js` 中的 `apiUrl` 指向服务器地址

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