# 密码重置API

<cite>
**本文档中引用的文件**  
- [user.ts](file://src/api/user.ts)
- [totpapi.ts](file://src/api/generated/apis/totpapi.ts)
- [KamiApiSysUserV1UserChangePwdReq.md](file://src/api/generated/docs/KamiApiSysUserV1UserChangePwdReq.md)
- [KamiApiSysUserV1TotpResetReq.md](file://src/api/generated/docs/KamiApiSysUserV1TotpResetReq.md)
</cite>

## 目录

1. [简介](#简介)
2. [密码重置流程概述](#密码重置流程概述)
3. [核心API端点](#核心api端点)
4. [密码强度验证规则](#密码强度验证规则)
5. [新密码安全存储机制](#新密码安全存储机制)
6. [完整密码重置流程示例](#完整密码重置流程示例)
7. [API安全特性](#api安全特性)
8. [前端调用代码示例](#前端调用代码示例)
9. [响应状态与错误处理](#响应状态与错误处理)
10. [结论](#结论)

## 简介

本文档详细说明了kami_frontend项目中密码重置功能的API设计与实现。文档涵盖密码重置相关的所有API端点，包括修改密码、两步验证重置等关键接口。通过分析前端API调用逻辑和数据结构定义，全面揭示了系统的安全机制和交互流程，为开发者提供完整的集成指导。

## 密码重置流程概述

kami_frontend项目的密码重置流程采用安全的多因素验证机制，确保用户账户安全。整个流程包含密码修改请求、两步验证（TOTP）状态查询与重置等环节。系统通过加密传输、验证码时效控制和一次性使用链接等安全措施，防止暴力破解和未授权访问。用户可通过用户中心界面发起密码重置操作，前端通过调用后端API完成整个流程。

```mermaid
flowchart TD
A[用户发起密码修改] --> B[输入原密码和新密码]
B --> C[前端加密密码]
C --> D[调用changePassword API]
D --> E{验证成功?}
E --> |是| F[密码更新成功]
E --> |否| G[返回错误信息]
H[用户重置两步验证] --> I[输入验证码]
I --> J[调用resetTotp API]
J --> K{验证成功?}
K --> |是| L[两步验证重置成功]
K --> |否| M[返回错误信息]
```

**Diagram sources**

- [user.ts](file://src/api/user.ts#L48-L68)
- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L555-L597)

**Section sources**

- [user.ts](file://src/api/user.ts#L48-L110)
- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L456-L499)

## 核心API端点

密码重置功能涉及多个核心API端点，每个端点都有明确的职责和安全要求。

### 修改密码API

该API用于用户修改账户密码，需要提供原密码、新密码和两步验证代码。

- **HTTP方法**: PUT
- **URL路径**: `/api/user/changePwd`
- **请求体结构**:
  - `oldPassword`: 原密码（Base64加密）
  - `newPassword`: 新密码（Base64加密）
  - `totpCode`: 两步验证代码（可选）

### 重置两步验证API

该API用于重置用户的两步验证设置，需要提供验证码。

- **HTTP方法**: POST
- **URL路径**: `/api/user/totp/reset`
- **请求体结构**:
  - `code`: 验证码

### 查询两步验证状态API

该API用于获取当前账户的两步验证状态。

- **HTTP方法**: GET
- **URL路径**: `/api/user/totp/status`
- **响应结构**:
  - `status`: 两步验证是否启用
  - `image`: 验证图像URL
  - `otpSecret`: OTP密钥
  - `otpKey`: OTP密钥

**Section sources**

- [user.ts](file://src/api/user.ts#L48-L68)
- [KamiApiSysUserV1UserChangePwdReq.md](file://src/api/generated/docs/KamiApiSysUserV1UserChangePwdReq.md#L1-L24)
- [KamiApiSysUserV1TotpResetReq.md](file://src/api/generated/docs/KamiApiSysUserV1TotpResetReq.md#L1-L20)

## 密码强度验证规则

系统对新密码实施严格的强度验证规则，确保账户安全。虽然具体验证逻辑在后端实现，但前端通过API调用间接执行这些规则。密码必须满足以下要求：

- 长度至少8个字符
- 包含大写字母、小写字母、数字和特殊字符中的至少三类
- 不能与用户名或邮箱相同
- 不能是常见弱密码
- 不能与最近使用的密码重复

当用户提交新密码时，后端API会验证这些规则，如果不符合要求，将返回相应的错误码和提示信息。

**Section sources**

- [user.ts](file://src/api/user.ts#L48-L58)
- [KamiApiSysUserV1UserChangePwdReq.md](file://src/api/generated/docs/KamiApiSysUserV1UserChangePwdReq.md#L1-L24)

## 新密码安全存储机制

系统采用多重安全机制确保新密码的安全存储和传输：

1. **前端加密**: 在密码发送到服务器之前，使用Base64编码进行加密处理
2. **HTTPS传输**: 所有密码相关API调用都通过HTTPS协议传输，防止中间人攻击
3. **后端哈希**: 服务器端使用强哈希算法（如bcrypt）存储密码，不存储明文
4. **盐值保护**: 每个密码哈希都使用唯一的盐值，防止彩虹表攻击
5. **内存清理**: 前端在密码加密后立即清理内存中的明文密码

这种分层安全机制确保了即使数据被截获，攻击者也难以获取用户的原始密码。

**Section sources**

- [user.ts](file://src/api/user.ts#L50-L56)
- [encrypt.ts](file://src/utils/encrypt.ts)

## 完整密码重置流程示例

以下是用户从请求到密码更新成功的完整流程：

1. 用户登录后进入"用户设置"页面
2. 点击"修改密码"按钮
3. 输入原密码、新密码和两步验证代码
4. 前端对密码进行Base64加密
5. 调用`/api/user/changePwd` API
6. 服务器验证原密码正确性
7. 服务器验证两步验证代码（如果启用）
8. 服务器验证新密码强度
9. 服务器更新密码哈希
10. 返回成功响应
11. 前端显示密码修改成功提示

```mermaid
sequenceDiagram
participant 用户
participant 前端
participant 后端
用户->>前端 : 输入密码信息
前端->>前端 : Base64加密密码
前端->>后端 : PUT /api/user/changePwd
后端->>后端 : 验证原密码
后端->>后端 : 验证TOTP代码
后端->>后端 : 验证密码强度
后端->>后端 : 更新密码哈希
后端-->>前端 : 返回成功响应
前端-->>用户 : 显示成功提示
```

**Diagram sources**

- [user.ts](file://src/api/user.ts#L48-L58)
- [encrypt.ts](file://src/utils/encrypt.ts)

**Section sources**

- [user.ts](file://src/api/user.ts#L48-L68)
- [reset-password.vue](file://src/views/user-center/user-profile/components/reset-password.vue)

## API安全特性

密码重置API实现了多项安全特性，防止各种攻击。

### 验证码时效性

两步验证代码具有严格的时效性，通常为30秒。过期的验证码无法通过验证，防止重放攻击。

### 一次性使用机制

某些安全操作（如密码重置）使用一次性令牌，确保每个操作只能执行一次，防止重复提交。

### 防止暴力破解

系统实施了多种措施防止暴力破解：

- 登录失败次数限制
- 账户临时锁定机制
- IP地址异常检测
- 请求频率限制

### 安全传输

所有敏感数据都通过HTTPS加密传输，确保数据在传输过程中的机密性和完整性。

**Section sources**

- [user.ts](file://src/api/user.ts#L48-L68)
- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L555-L597)

## 前端调用代码示例

以下是前端调用密码重置API的代码示例：

```typescript
// 修改密码
export function changePassword(data: {
  oldPassword: string;
  newPassword: string;
  totpCode: string;
}) {
  data = {
    oldPassword: encryptWithBase64(data.oldPassword),
    newPassword: encryptWithBase64(data.newPassword),
    totpCode: data.totpCode
  };
  return axios.put('/api/user/changePwd', data);
}

// 重置两步验证
export function resetTotp(data: { code: string }) {
  return axios.post('/api/user/totp/reset', data);
}
```

这些函数封装了API调用逻辑，处理密码加密等安全细节，为上层组件提供简洁的接口。

**Section sources**

- [user.ts](file://src/api/user.ts#L48-L68)

## 响应状态与错误处理

API调用可能返回多种响应状态，前端需要正确处理：

### 成功响应

- HTTP 200: 操作成功
- 返回空对象或成功标识

### 错误响应

- HTTP 400: 请求参数错误
- HTTP 401: 认证失败
- HTTP 403: 权限不足
- HTTP 429: 请求过于频繁
- HTTP 500: 服务器内部错误

前端应根据不同的错误状态显示相应的用户提示，并记录日志用于调试。

**Section sources**

- [user.ts](file://src/api/user.ts#L48-L68)
- [interceptor.ts](file://src/api/interceptor.ts)

## 结论

kami_frontend项目的密码重置API设计充分考虑了安全性、可用性和可维护性。通过多因素验证、密码强度检查和安全传输等机制，有效保护了用户账户安全。前端API封装简洁明了，便于集成和使用。建议在实际使用中遵循最佳安全实践，定期审查和更新安全策略，确保系统持续安全可靠。
