@pisell/private-materials 3.4.69 → 3.4.70

package/lowcode/login2/VERIFICATION_METHODS.md

@@ -1,364 +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`，可以为不同场景提供最佳的登录体验！
-
+# 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`，可以为不同场景提供最佳的登录体验！
+