# Fido2Login SDK API 文档

## 概述

`Fido2UIManager.renderLogin()` 是一个用于渲染登录组件的API，支持：
- Fido2/Passkey 自动登录
- 密码登录回退
- 密码重试次数限制
- 完全的回调驱动（SDK不跳转页面）

## 使用方法

### 1. 引入依赖

```html
<script src="files/jquery.js"></script>
<script src="files/bootstrap.js"></script>
<script src="files/dfido2-lib.js"></script>
<script src="files/fido2-ui-sdk.js"></script>
```

### 2. 添加容器

```html
<div id="login-container"></div>
```

### 3. 初始化登录组件

```javascript
const loginManager = Fido2UIManager.renderLogin({
  container: '#login-container',
  features: {
    autoAuth: true,
    enablePasswordLogin: true,
    maxPasswordAttempts: 3,
    showRemainingAttempts: true
  },
  callbacks: {
    onFido2Success: (userId, session) => {
      // 处理Fido2登录成功
    },
    onFido2Error: (error) => {
      // 处理Fido2登录失败
    },
    onPasswordLogin: (userId, password) => {
      // 返回 Promise<boolean>
    },
    onPasswordExhausted: (userId, attempts, maxAttempts) => {
      // 密码重试次数耗尽
    },
    onLoginClosed: () => {
      // UI被关闭
    }
  }
});
```

## 配置参数

### container
- **类型**: `string | Element`
- **必填**: 是
- **说明**: 模态框容器元素

### features
- **类型**: `Object`
- **默认值**: 见下方

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `autoAuth` | boolean | true | 有注册设备时自动Fido2登录 |
| `enablePasswordLogin` | boolean | true | 是否启用密码登录功能 |
| `autoShowPassword` | boolean | false | Fido2失败后是否自动显示密码框 |
| `maxPasswordAttempts` | number | 3 | 密码最大重试次数 |
| `showRemainingAttempts` | boolean | true | 是否显示剩余尝试次数 |

### theme
- **类型**: `Object`
- **说明**: 复用 `renderDeviceManager` 的theme配置

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `logo` | string | null | Logo图片URL |
| `primaryColor` | string | '#696cff' | 主色调 |
| `backgroundColor` | string | '#ffffff' | 背景色 |
| `textColor` | string | '#333333' | 文字颜色 |
| `borderRadius` | string | '8px' | 边框圆角 |

### language
- **类型**: `string`
- **默认值**: `'zh-CN'`
- **说明**: 支持9种语言

### callbacks

#### onFido2Success(userId, session)
- **触发时机**: Fido2登录认证成功
- **参数**:
  - `userId`: string - 用户ID
  - `session`: object - 会话信息
- **注意**: SDK不跳转页面，由调用端处理跳转

#### onFido2Error(error)
- **触发时机**: Fido2登录失败或取消
- **参数**: `error` 对象
  - `code`: string - 错误码
  - `message`: string - 错误信息
  - `originalError`: object - 原始错误

**error.code 值**:
| code | 说明 |
|------|------|
| `CANCELED` | 用户取消认证 |
| `AUTH_FAILED` | 认证失败 |
| `NO_REGISTRATION` | 无注册设备且未启用密码登录 |
| `NOT_SUPPORTED` | 浏览器不支持WebAuthn |

#### onPasswordLogin(userId, password)
- **触发时机**: 用户点击密码登录按钮
- **参数**:
  - `userId`: string - 用户ID
  - `password`: string - 密码
- **返回值**: `Promise<boolean>`
  - `true`: 登录成功
  - `false`: 登录失败

#### onPasswordExhausted(userId, attempts, maxAttempts)
- **触发时机**: 密码重试次数耗尽
- **参数**:
  - `userId`: string - 用户ID
  - `attempts`: number - 已尝试次数
  - `maxAttempts`: number - 最大允许次数
- **注意**: UI已自动关闭

#### onLoginClosed()
- **触发时机**: 用户关闭模态框（点击×或调用hide()）

## 实例方法

### show()
显示登录模态框

### hide()
隐藏登录模态框，触发 `onLoginClosed` 回调

### destroy()
销毁登录组件实例，不触发任何回调

### setMode(mode)
切换登录模式
- `mode`: `'fido2'` 或 `'password'`

### getUserId()
获取当前输入的用户ID

### getState()
获取当前状态
- 返回值: `'loading'` | `'fido2'` | `'password'` | `'closed'`

### getMode()
获取当前模式
- 返回值: `'fido2'` | `'password'`

### getAttemptCount()
获取当前密码尝试次数

### getRemainingAttempts()
获取剩余尝试次数

### resetPasswordAttempts()
重置密码尝试计数器

## 国际化支持

默认支持9种语言：
- `en-US` (英语)
- `zh-CN` (简体中文)
- `ja` (日语)
- `es` (西班牙语)
- `de` (德语)
- `fr` (法语)
- `pt` (葡萄牙语)
- `ko` (韩语)
- `ru` (俄语)
- `it` (意大利语)

可通过 `customI18n` 配置自定义文本：
```javascript
Fido2UIManager.renderLogin({
  customI18n: {
    'title_login': {
      'en-US': 'Custom Login',
      'zh-CN': '自定义登录'
    }
  }
});
```

## 完整示例

```html
<!DOCTYPE html>
<html>
<head>
  <title>Login Example</title>
  <link rel="stylesheet" href="files/bootstrap.css">
  <script src="files/jquery.js"></script>
  <script src="files/bootstrap.js"></script>
  <script src="files/dfido2-lib.js"></script>
  <script src="files/fido2-ui-sdk.js"></script>
</head>
<body>
  <div id="login-container"></div>

  <script>
    const loginManager = Fido2UIManager.renderLogin({
      container: '#login-container',
      features: {
        autoAuth: true,
        enablePasswordLogin: true,
        maxPasswordAttempts: 3,
        showRemainingAttempts: true
      },
      callbacks: {
        onFido2Success: (userId, session) => {
          // 保存登录状态
          localStorage.setItem('userId', userId);
          localStorage.setItem('session', JSON.stringify(session));
          // 跳转页面
          window.location.href = '/dashboard';
        },
        onFido2Error: (error) => {
          switch (error.code) {
            case 'CANCELED':
              console.log('用户取消登录');
              break;
            case 'AUTH_FAILED':
              console.log('认证失败:', error.message);
              break;
            case 'NO_REGISTRATION':
              alert('暂未注册设备，请联系管理员');
              break;
          }
        },
        onPasswordLogin: (userId, password) => {
          return fetch('/api/login', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ userId, password })
          }).then(r => r.ok);
        },
        onPasswordExhausted: (userId, attempts, maxAttempts) => {
          alert('尝试次数过多，请稍后重试');
        },
        onLoginClosed: () => {
          console.log('登录窗口已关闭');
        }
      }
    });
  </script>
</body>
</html>
```

## 版本信息

- **FIDO2 UI SDK**: v1.0.0+
- **文件**: `files/fido2-ui-sdk.js`
- **新增功能**: `Fido2UIManager.renderLogin()`
