# 常规登录流程

<cite>
**本文档引用文件**  
- [login-form.vue](file://src/views/login/components/login-form.vue)
- [auth.ts](file://src/utils/auth.ts)
- [user.ts](file://src/api/user.ts)
- [index.ts](file://src/store/modules/user/index.ts)
- [kami-api-sys-user-login-v1-user-login-req.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-req.ts)
- [kami-api-sys-user-login-v1-user-login-res.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-res.ts)
</cite>

## 目录

1. [简介](#简介)
2. [登录表单与验证规则](#登录表单与验证规则)
3. [登录接口调用流程](#登录接口调用流程)
4. [JWT令牌管理机制](#jwt令牌管理机制)
5. [登录流程图](#登录流程图)
6. [错误处理机制](#错误处理机制)
7. [安全性考虑](#安全性考虑)
8. [代码实现示例](#代码实现示例)

## 简介

本文档详细描述了kami_frontend项目中用户常规登录的完整流程。从用户输入账号密码开始，经过前端验证、加密处理、HTTP请求发送，到后端认证成功后JWT令牌的存储与使用，全面解析整个认证流程。文档涵盖登录表单设计、接口调用细节、状态管理机制以及安全防护措施，为开发者提供完整的登录功能实现参考。

## 登录表单与验证规则

登录表单包含用户名、密码、两步验证码（可选）和图形验证码四个输入字段。表单在提交前进行客户端验证，确保用户输入符合要求。

- **用户名**：必填项，提示“请输入正确账号”
- **密码**：必填项，提示“请输入密码”（实际密码格式校验在后端完成）
- **两步验证码**：正则校验，必须为6位数字，提示“请输入正确的两步验证码(6位数字)”
- **图形验证码**：必填项，提示“请输入正确验证码”

表单支持“记住密码”功能，通过Base64加密后存储在本地localStorage中，下次登录时自动填充。

**Section sources**

- [login-form.vue](file://src/views/login/components/login-form.vue#L0-L42)
- [login-form.vue](file://src/views/login/components/login-form.vue#L154-L195)

## 登录接口调用流程

登录功能通过调用后端API `/api/sysUserLogin/v1/userLogin` 实现，使用HTTP POST方法。

### 请求配置

- **URL路径**：`/api/sysUserLogin/v1/userLogin`
- **请求方法**：POST
- **请求头**：自动包含Content-Type等标准头信息
- **请求体结构**（KamiApiSysUserLoginV1UserLoginReq）：
  - `username`：用户名（字符串）
  - `password`：密码（字符串）
  - `verifyCode`：图形验证码（字符串）
  - `verifyKey`：验证码唯一标识（字符串）
  - `totpCode`：两步验证码（可选，字符串）

### 响应数据结构

成功响应返回KamiApiSysUserLoginV1UserLoginRes对象，包含：

- `token`：JWT认证令牌（字符串）

### 调用流程

1. 用户点击登录按钮触发handleSubmit函数
2. 表单验证用户名、密码和验证码字段
3. 构造登录参数对象，包含用户名、密码、验证码等信息
4. 调用userStore.login方法发起登录请求
5. 请求成功后跳转至工作台页面，显示“登录成功”提示

**Section sources**

- [kami-api-sys-user-login-v1-user-login-req.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-req.ts#L0-L50)
- [kami-api-sys-user-login-v1-user-login-res.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-res.ts#L0-L26)
- [login-form.vue](file://src/views/login/components/login-form.vue#L194-L235)

## JWT令牌管理机制

认证成功后，系统采用本地存储方式管理JWT令牌，确保用户会话状态的持久化和安全性。

### 令牌存储

- **存储位置**：localStorage
- **存储键名**：`token`
- **来源标记**：`tokenFrom`（值为"login"）

### 令牌操作

- **设置令牌**：调用`setToken(token)`方法将JWT存入localStorage
- **获取令牌**：调用`getToken()`方法从localStorage读取
- **清除令牌**：调用`clearToken()`方法删除localStorage中的令牌及相关信息

### 后续请求

系统通过拦截器自动将JWT令牌添加到后续所有API请求的Authorization头中，实现无缝认证。用户状态由Pinia状态管理库统一维护。

```mermaid
flowchart TD
A[用户登录] --> B{认证成功?}
B --> |是| C[获取JWT令牌]
C --> D[存储到localStorage]
D --> E[设置tokenFrom为login]
E --> F[跳转到工作台]
F --> G[后续请求自动携带JWT]
G --> H[访问受保护资源]
B --> |否| I[清除本地令牌]
I --> J[显示错误信息]
```

**Diagram sources**

- [auth.ts](file://src/utils/auth.ts#L0-L49)
- [index.ts](file://src/store/modules/user/index.ts#L52-L79)

**Section sources**

- [auth.ts](file://src/utils/auth.ts#L0-L49)
- [index.ts](file://src/store/modules/user/index.ts#L0-L80)

## 登录流程图

以下流程图展示了从用户输入到状态更新的完整登录流程：

```mermaid
flowchart TD
Start([用户访问登录页]) --> A[输入用户名密码]
A --> B[输入图形验证码]
B --> C{开启记住密码?}
C --> |是| D[Base64加密存储]
C --> |否| E[不存储]
D --> F[点击登录按钮]
E --> F
F --> G[表单字段验证]
G --> H{验证通过?}
H --> |否| I[显示错误提示]
H --> |是| J[构造登录参数]
J --> K[调用登录API]
K --> L{HTTP 200?}
L --> |否| M[清除本地令牌]
M --> N[显示错误信息]
L --> |是| O[解析响应获取token]
O --> P[存储token到localStorage]
P --> Q[设置token来源]
Q --> R[跳转到工作台]
R --> S[登录成功]
I --> End([等待用户修正])
N --> End
S --> End
```

**Diagram sources**

- [login-form.vue](file://src/views/login/components/login-form.vue#L0-L347)

## 错误处理机制

系统实现了完善的错误处理策略，针对不同异常场景提供相应的处理方案：

- **用户名密码错误**：后端返回认证失败，前端清除本地令牌，显示具体错误信息
- **账户禁用**：后端验证账户状态，若被禁用则拒绝登录，前端提示"账户已被禁用"
- **图形验证码错误**：验证失败后自动刷新验证码图片，提示"验证码错误"
- **网络超时**：请求超时后自动捕获异常，提示"网络连接超时，请检查网络"
- **两步验证错误**：若启用TOTP，验证码错误时提示"两步验证码错误"
- **服务不可用**：检测到服务异常时，提示"服务暂时不可用，请稍后重试"

所有错误处理均在Promise.catch中统一处理，确保用户体验的一致性。

**Section sources**

- [index.ts](file://src/store/modules/user/index.ts#L52-L56)
- [login-form.vue](file://src/views/login/components/login-form.vue#L194-L235)

## 安全性考虑

系统在前端层面实施了多项安全措施，保障用户认证过程的安全性：

### 密码传输安全

- 密码在前端明文传输，依赖HTTPS加密通道保障传输安全
- 未来可考虑增加前端密码加密（如RSA）进一步提升安全性

### 验证码机制

- 图形验证码防止暴力破解攻击
- 每次请求生成新的验证码Key，防止重放攻击
- 验证码与会话关联，增加破解难度

### 存储安全

- "记住密码"功能使用Base64编码存储，虽非加密但避免明文存储
- 推荐在公共设备上不启用"记住密码"功能

### 防暴力破解

- 后端应实现登录失败次数限制
- 连续失败后增加等待时间或锁定账户
- 结合IP地址进行异常登录检测

### 其他安全措施

- 使用Pinia进行状态管理，避免敏感信息泄露
- 路由守卫确保未登录用户无法访问受保护页面
- Token来源标记防止跨站点请求伪造

**Section sources**

- [login-form.vue](file://src/views/login/components/login-form.vue#L154-L195)
- [auth.ts](file://src/utils/auth.ts#L0-L49)

## 代码实现示例

以下是登录功能的核心代码实现示例：

```mermaid
sequenceDiagram
participant 用户
participant LoginForm as 登录表单
participant UserStore as 用户状态管理
participant API as 登录API
participant Auth as 认证工具
用户->>LoginForm : 输入账号密码验证码
LoginForm->>LoginForm : 表单验证
LoginForm->>UserStore : 调用login方法
UserStore->>API : 发送POST请求
API-->>UserStore : 返回JWT令牌
UserStore->>Auth : 调用setToken
Auth->>Auth : 存储到localStorage
UserStore-->>LoginForm : 登录成功
LoginForm->>用户 : 跳转工作台
```

**Diagram sources**

- [login-form.vue](file://src/views/login/components/login-form.vue#L194-L235)
- [index.ts](file://src/store/modules/user/index.ts#L52-L79)
- [auth.ts](file://src/utils/auth.ts#L0-L49)

**Section sources**

- [login-form.vue](file://src/views/login/components/login-form.vue#L194-L235)
- [index.ts](file://src/store/modules/user/index.ts#L52-L79)
- [auth.ts](file://src/utils/auth.ts#L0-L49)
