@pisell/private-materials 6.6.2 → 6.7.2

package/lowcode/login2/TEST_CONFIG.md

@@ -0,0 +1,324 @@
+# Login2 测试配置指南
+
+## 快速测试配置
+
+### 1. 分步骤邮箱登录 + Google + Facebook
+
+```json
+{
+  "config": {
+    "loginMethods": [
+      {
+        "type": "email",
+        "verificationMethods": ["password", "verification_code"],
+        "stepByStep": true
+      },
+      {
+        "type": "google",
+        "clientId": "your-google-client-id"
+      },
+      {
+        "type": "facebook",
+        "appId": "your-facebook-app-id"
+      }
+    ],
+    "ui": {
+      "title": {
+        "show": true,
+        "text": "Welcome to BBPet",
+        "align": "center"
+      },
+      "subtitle": {
+        "show": true,
+        "text": "Log in to your account",
+        "align": "center"
+      },
+      "desc": {
+        "show": true,
+        "text": "Welcome back! Please enter your details.",
+        "align": "center"
+      },
+      "themeColor": "#7F56D9"
+    }
+  }
+}
+```
+
+**预期效果：**
+- 第一步：邮箱输入框 + "Continue with email" 按钮
+- 点击后进入第二步：显示邮箱（只读）+ 密码输入框
+- 底部显示："Email code to xxx" 切换选项
+- OR 分隔符
+- Google 和 Facebook 按钮
+
+### 2. 单步邮箱登录（传统模式）
+
+```json
+{
+  "config": {
+    "loginMethods": [
+      {
+        "type": "email",
+        "verificationMethods": ["password", "verification_code"],
+        "stepByStep": false
+      }
+    ]
+  }
+}
+```
+
+**预期效果：**
+- 邮箱和密码在同一页面
+- Remember me + Forgot password
+- Log in 按钮
+- 底部："Email code to xxx" 切换选项
+
+### 3. 手机分步骤登录
+
+```json
+{
+  "config": {
+    "loginMethods": [
+      {
+        "type": "phone",
+        "verificationMethods": ["password"],
+        "stepByStep": true
+      }
+    ]
+  }
+}
+```
+
+**预期效果：**
+- 第一步：手机号输入框 + "Continue with phone" 按钮
+- 第二步：手机号（只读）+ 密码输入框 + Log in + Back
+
+### 4. 多种登录方式混合
+
+```json
+{
+  "config": {
+    "loginMethods": [
+      {
+        "type": "email",
+        "verificationMethods": ["password", "verification_code"],
+        "stepByStep": true
+      },
+      {
+        "type": "google",
+        "clientId": "xxx"
+      },
+      {
+        "type": "phone",
+        "verificationMethods": ["verification_code", "password"],
+        "stepByStep": false
+      },
+      {
+        "type": "apple",
+        "clientId": "xxx"
+      }
+    ]
+  }
+}
+```
+
+**预期效果：**
+- 主表单：邮箱分步骤登录
+- 底部切换区域：
+  - 📧 Email code to xxx
+  - 📱 Phone login
+  - Google 按钮
+  - Apple 按钮
+
+### 5. 纯第三方登录
+
+```json
+{
+  "config": {
+    "loginMethods": [
+      {
+        "type": "google",
+        "clientId": "xxx"
+      },
+      {
+        "type": "facebook",
+        "appId": "xxx"
+      },
+      {
+        "type": "apple",
+        "clientId": "xxx"
+      }
+    ]
+  }
+}
+```
+
+**预期效果：**
+- 只显示 Google 按钮（主要）
+- OR 分隔符
+- Facebook 和 Apple 按钮
+
+## 在低代码编辑器中测试
+
+### 步骤 1：拖入组件
+
+1. 从组件库拖入 "登录 2.0（推荐配置）"
+2. 默认已配置好分步骤邮箱登录
+
+### 步骤 2：修改配置
+
+在右侧属性面板中：
+
+1. **登录方式配置（推荐）** 组
+   - 点击 "登录方式列表"
+   - 添加/删除/重新排序登录方式
+   - 对邮箱/手机登录方式：
+     - 勾选 "分步骤登录（密码）" 启用分步骤模式
+     - 设置 "验证方式" 数组（第一项为默认）
+
+2. **UI 配置** 组
+   - 修改标题、副标题、描述
+   - 修改主题色
+
+3. **其他配置** 组
+   - 设置 "渠道标识"（可选）
+
+### 步骤 3：绑定事件
+
+在右侧属性面板底部 "事件" 区域：
+
+```javascript
+// onLogin
+function(data, method, channel) {
+  console.log('Login:', data, method, channel);
+  // data = { account, password, verification_code, remember_me }
+}
+
+// onSendVerificationCode
+function(account, type, channel) {
+  console.log('Send code to:', account, type, channel);
+}
+
+// onOAuthLogin
+function(provider, channel) {
+  console.log('OAuth login:', provider, channel);
+}
+
+// onForgotPassword
+function(account, channel) {
+  console.log('Forgot password:', account, channel);
+}
+```
+
+### 步骤 4：预览测试
+
+点击 "预览" 按钮，测试以下场景：
+
+#### 分步骤登录测试
+1. 输入邮箱 → 点击 "Continue with email"
+2. 查看是否进入密码页
+3. 点击 "Back" 按钮
+4. 查看是否返回邮箱输入页
+
+#### 验证方式切换测试
+1. 在邮箱密码页，点击底部 "Email code to xxx"
+2. 查看是否切换到验证码输入模式
+3. 点击 "Password login" 切换回密码模式
+
+#### 登录方式切换测试
+1. 点击底部 "Phone login"
+2. 查看是否切换到手机登录表单
+3. 查看手机登录的默认验证方式是否正确
+
+## 常见问题
+
+### Q1: 分步骤模式不生效？
+**检查：**
+- `stepByStep` 是否设置为 `true`
+- `verificationMethods` 中是否包含 `'password'`
+- 当前是否在密码登录模式（不是验证码模式）
+
+### Q2: 底部切换选项不显示？
+**检查：**
+- `loginMethods` 数组是否有多个项
+- 或邮箱/手机登录方式的 `verificationMethods` 是否有多个
+
+### Q3: 第三方登录按钮不显示？
+**检查：**
+- `type` 是否正确（'google'/'facebook'/'apple'）
+- 是否在 `loginMethods` 数组中
+
+### Q4: 样式不对？
+**检查：**
+- `ui.themeColor` 是否设置
+- 组件是否正确导入样式文件
+
+## 调试技巧
+
+1. **查看 console.log**
+   - 组件内部有多个 `console.log` 用于调试
+   - 检查 `normalizedLoginMethods` 输出
+   - 检查 `currentLoginMethod` 和 `loginStep` 状态
+
+2. **使用 React DevTools**
+   - 查看组件 state
+   - 查看 props 传递是否正确
+
+3. **分步测试**
+   - 先测试单一登录方式
+   - 再测试多种登录方式组合
+   - 最后测试分步骤功能
+
+## 配置模板
+
+### 图片中的配置（分步骤邮箱 + 三方）
+
+```json
+{
+  "config": {
+    "loginMethods": [
+      {
+        "type": "email",
+        "verificationMethods": ["password"],
+        "stepByStep": true
+      },
+      {
+        "type": "google",
+        "clientId": ""
+      },
+      {
+        "type": "facebook",
+        "appId": ""
+      },
+      {
+        "type": "apple",
+        "clientId": ""
+      }
+    ],
+    "ui": {
+      "logo": {
+        "show": true,
+        "url": "https://your-logo-url.png",
+        "position": "center"
+      },
+      "title": {
+        "show": true,
+        "text": "Welcome to BBPet",
+        "align": "center"
+      },
+      "subtitle": {
+        "show": true,
+        "text": "Log in to your account",
+        "align": "center"
+      },
+      "desc": {
+        "show": true,
+        "text": "Welcome back! Please enter your details.",
+        "align": "center"
+      },
+      "themeColor": "#7F56D9"
+    }
+  }
+}
+```
+

package/lowcode/login2/VERIFICATION_METHODS.md

@@ -0,0 +1,364 @@
+# Login2 验证方式配置详解
+
+## 概述
+
+`verificationMethods` 是 Login2 组件中用于配置邮箱/手机登录验证方式的参数。它决定了用户可以使用哪些方式进行登录，以及这些方式如何显示和切换。
+
+## 基本概念
+
+### 支持的验证方式
+
+- `"password"` - 密码登录
+- `"verification_code"` - 验证码登录
+
+### 配置位置
+
+```typescript
+{
+  type: 'email',  // 或 'phone'
+  verificationMethods: ['password', 'verification_code']
+}
+```
+
+### 配置规则
+
+1. **数组第一项为默认方式**
+   - `['password', 'verification_code']` → 默认显示密码登录
+   - `['verification_code', 'password']` → 默认显示验证码登录
+
+2. **可以只配置一种方式**
+   - `['password']` → 只有密码登录
+   - `['verification_code']` → 只有验证码登录
+
+3. **配置多种方式时，用户可以切换**
+   - 界面会显示 "OR" 分隔线
+   - 分隔线下方显示切换按钮
+
+## 使用场景
+
+### 场景 1：密码为主，验证码为辅
+
+**配置：**
+```json
+{
+  "type": "email",
+  "verificationMethods": ["password", "verification_code"]
+}
+```
+
+**用户体验：**
+1. 默认看到密码输入框
+2. 下方有 "Email code to xxx" 选项
+3. 忘记密码时可以切换到验证码登录
+
+**适用于：** 传统网站、后台管理系统
+
+---
+
+### 场景 2：验证码为主，密码为辅
+
+**配置：**
+```json
+{
+  "type": "phone",
+  "verificationMethods": ["verification_code", "password"]
+}
+```
+
+**用户体验：**
+1. 默认看到验证码输入框
+2. 下方有 "Password login" 选项
+3. 收不到验证码时可以切换到密码登录
+
+**适用于：** 移动端 App、金融类应用
+
+---
+
+### 场景 3：仅密码登录
+
+**配置：**
+```json
+{
+  "type": "email",
+  "verificationMethods": ["password"]
+}
+```
+
+**用户体验：**
+1. 只显示密码输入框
+2. 无其他登录方式切换
+3. 界面简洁
+
+**适用于：** 企业内部系统、不支持短信的场景
+
+---
+
+### 场景 4：仅验证码登录
+
+**配置：**
+```json
+{
+  "type": "phone",
+  "verificationMethods": ["verification_code"]
+}
+```
+
+**用户体验：**
+1. 只显示验证码输入框
+2. 无其他登录方式切换
+3. 更安全（无需记忆密码）
+
+**适用于：** 高安全要求场景、临时访问
+
+## 界面展示详解
+
+### 单一验证方式
+
+```
+┌─────────────────────────┐
+│      Logo & Title       │
+├─────────────────────────┤
+│ Email Input             │
+│ Password Input          │
+│ [Remember me] [Forgot?] │
+│ [Log in Button]         │
+└─────────────────────────┘
+```
+
+**特点：**
+- ✅ 界面简洁
+- ✅ 无切换选项
+- ✅ 适合单一登录场景
+
+---
+
+### 多种验证方式（密码默认）
+
+```
+┌─────────────────────────┐
+│      Logo & Title       │
+├─────────────────────────┤
+│ Email Input             │
+│ Password Input          │
+│ [Remember me] [Forgot?] │
+│ [Log in Button]         │
+├─────────────────────────┤
+│         OR              │ ← 分隔线
+├─────────────────────────┤
+│ 📧 Email code to u***@  │ ← 切换到验证码
+└─────────────────────────┘
+```
+
+**用户操作流程：**
+1. 输入邮箱
+2. 输入密码
+3. 点击登录
+4. **或** 点击 "Email code to xxx" 切换到验证码模式
+
+---
+
+### 多种验证方式（验证码默认）
+
+```
+┌─────────────────────────┐
+│      Logo & Title       │
+├─────────────────────────┤
+│ Email Input             │
+│ Verification Code Input │
+│ [Send Code Button]      │
+│ [Log in Button]         │
+├─────────────────────────┤
+│         OR              │ ← 分隔线
+├─────────────────────────┤
+│ 🔑 Password login       │ ← 切换到密码
+└─────────────────────────┘
+```
+
+**用户操作流程：**
+1. 输入邮箱
+2. 点击"发送验证码"
+3. 输入验证码
+4. 点击登录
+5. **或** 点击 "Password login" 切换到密码模式
+
+## 技术实现
+
+### 默认验证方式初始化
+
+```typescript
+// Login2.tsx
+useEffect(() => {
+  if (loginMethods.length > 0 && !currentLoginMethod) {
+    const first = loginMethods[0];
+    setCurrentLoginMethod(first);
+    
+    // 设置默认验证方式（数组第一项）
+    if (first.type === 'email' || first.type === 'phone') {
+      setCurrentVerificationMethod(first.verificationMethods?.[0] || 'password');
+    }
+  }
+}, [loginMethods, currentLoginMethod]);
+```
+
+### 验证方式切换
+
+```typescript
+const switchVerificationMethod = useCallback((method: 'password' | 'verification_code') => {
+  setCurrentVerificationMethod(method);
+  form.resetFields(['password', 'verification_code']);
+}, [form]);
+```
+
+### 渲染切换选项
+
+```typescript
+const renderSwitchOptions = () => {
+  if (!currentLoginMethod) return null;
+  
+  // 获取当前登录方式的其他验证方式
+  if (currentLoginMethod.type === 'email' || currentLoginMethod.type === 'phone') {
+    const otherMethods = (currentLoginMethod.verificationMethods || []).filter(
+      m => m !== currentVerificationMethod
+    );
+    
+    // 为每个其他验证方式渲染切换按钮
+    otherMethods.forEach(method => {
+      if (method === 'verification_code') {
+        // 渲染 "Email code to xxx" 按钮
+      } else {
+        // 渲染 "Password login" 按钮
+      }
+    });
+  }
+  
+  return options;
+};
+```
+
+## API 调用
+
+### 密码登录
+
+```typescript
+// 邮箱密码
+await registerAndLogin.emailPasswordLogin({
+  email: account,
+  password: values.password
+});
+
+// 手机密码
+await registerAndLogin.phonePasswordLogin({
+  phone: account,
+  password: values.password
+});
+```
+
+### 验证码登录
+
+```typescript
+// 发送邮箱验证码
+await registerAndLogin.sendEmailVerificationCode({
+  type: 'email',
+  target: account,
+  purpose: 'login'
+});
+
+// 发送手机验证码
+await registerAndLogin.sendSmsLoginCode({
+  phone: account
+});
+
+// 邮箱验证码登录
+await registerAndLogin.emailCodeLogin({
+  email: account,
+  code: values.verification_code
+});
+
+// 手机验证码登录
+await registerAndLogin.phoneCodeLogin({
+  phone: account,
+  code: values.verification_code
+});
+```
+
+## 常见问题
+
+### Q1: 为什么我配置了两种验证方式，但只显示一种？
+
+**A:** 检查以下几点：
+1. `verificationMethods` 数组是否包含两个元素
+2. 是否在 lowcode 编辑器中正确保存了配置
+3. 刷新页面重新加载配置
+
+### Q2: 切换验证方式后，之前输入的内容会丢失吗？
+
+**A:** 
+- ✅ **账号（邮箱/手机号）** - 保留
+- ❌ **密码** - 清空
+- ❌ **验证码** - 清空
+
+这是为了安全考虑，避免用户混淆不同的验证方式。
+
+### Q3: 可以配置三种或更多验证方式吗？
+
+**A:** 目前只支持 `password` 和 `verification_code` 两种，不支持配置更多。
+
+### Q4: 验证码有效期是多久？
+
+**A:** 这取决于后端 API 的实现，通常为 5-10 分钟。前端组件提供 60 秒的倒计时，防止频繁发送。
+
+### Q5: 可以自定义切换按钮的文案吗？
+
+**A:** 目前文案是国际化的，会根据用户的语言自动切换。如需自定义，可以修改 `locales.ts` 文件。
+
+## 最佳实践
+
+### ✅ 推荐配置
+
+1. **移动端优先场景**
+   ```json
+   ["verification_code", "password"]
+   ```
+   - 验证码更符合移动用户习惯
+   - 密码作为备选方案
+
+2. **桌面端优先场景**
+   ```json
+   ["password", "verification_code"]
+   ```
+   - 密码输入更快速
+   - 验证码作为忘记密码的替代方案
+
+3. **高安全场景**
+   ```json
+   ["verification_code"]
+   ```
+   - 每次都需要验证码
+   - 减少密码泄露风险
+
+### ❌ 不推荐配置
+
+1. **空数组**
+   ```json
+   []
+   ```
+   - 用户无法登录
+
+2. **无效的验证方式**
+   ```json
+   ["invalid_method"]
+   ```
+   - 组件会回退到 `"password"`
+
+## 总结
+
+`verificationMethods` 提供了灵活的登录方式配置：
+
+- 📋 **配置简单** - 只需一个数组
+- 🔄 **切换流畅** - 用户可以自由切换
+- 🎨 **界面清晰** - OR 分隔线明确区分
+- 🔒 **安全可靠** - 支持多因素认证
+- 🌍 **国际化** - 自动适配多语言
+
+通过合理配置 `verificationMethods`，可以为不同场景提供最佳的登录体验！
+