audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新 wiki

Browse Source
This commit is contained in:
eafonyang
2026-07-17 17:17:22 +08:00
parent 1da6d72544
commit d292c23dc0
159 changed files with 2918 additions and 2735 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.qoder/repowiki/zh/content/核心功能模块/用户认证系统.md
+271 -96
View File
@@ -9,13 +9,22 @@
- [backend/src/models/DashboardUser.js](file://backend/src/models/DashboardUser.js)
- [backend/src/utils/response.js](file://backend/src/utils/response.js)
- [backend/src/services/userBootstrap.js](file://backend/src/services/userBootstrap.js)
- [frontend/src/utils/auth.js](file://frontend/src/utils/auth.js)
- [frontend/src/utils/request.js](file://frontend/src/utils/request.js)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js)
- [backend/src/app.js](file://backend/src/app.js)
- [backend/src/config/env.js](file://backend/src/config/env.js)
- [frontend/src/store/modules/auth/index.ts](file://frontend/src/store/modules/auth/index.ts)
- [frontend/src/store/modules/auth/shared.ts](file://frontend/src/store/modules/auth/shared.ts)
- [frontend/src/service/api/auth.ts](file://frontend/src/service/api/auth.ts)
- [frontend/src/hooks/business/auth.ts](file://frontend/src/hooks/business/auth.ts)
- [frontend/src/router/guard/route.ts](file://frontend/src/router/guard/route.ts)
- [frontend/src/typings/api/auth.d.ts](file://frontend/src/typings/api/auth.d.ts)
</cite>
## 更新摘要
**所做更改**
- 完全重构了前端认证模块结构，采用新的 src/store/modules/auth/ 目录组织
- 增强了 API 层以支持 TypeScript，提供类型安全的认证接口
- 引入了基于 Pinia 的状态管理替代原有的 localStorage 直接操作
- 添加了专门的认证钩子函数和业务逻辑封装
- 更新了路由守卫以适配新的认证状态管理
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
@@ -34,12 +43,13 @@
- **JWT认证机制**：使用HS256算法进行令牌签名，支持12小时有效期
- **密码安全存储**：采用PBKDF2算法进行密码哈希，防止明文存储
- **中间件验证**：提供通用认证中间件和超级管理员权限检查中间件
- **前后端协作**：前端通过localStorage管理令牌，后端通过Authorization头验证
- **现代化状态管理**：基于Pinia的认证状态管理，提供响应式数据绑定
- **TypeScript支持**：完整的类型定义和类型安全的API调用
- **错误处理**：完善的错误处理机制，支持令牌过期、权限不足等场景
## 项目结构
认证系统主要分布在后端和前端两个部分：
认证系统主要分布在后端和前端两个部分，前端采用了全新的模块化架构：
```mermaid
graph TB
@@ -51,28 +61,25 @@ A --> E[认证中间件]
A --> F[用户模型]
A --> G[响应格式化]
end
subgraph "前端架构"
H[Axios请求] --> I[认证工具]
H --> J[API封装]
I --> K[本地存储]
I --> L[令牌解析]
subgraph "前端新架构"
H[Axios请求] --> I[TypeScript API层]
I --> J[Pinia认证模块]
J --> K[认证钩子]
J --> L[路由守卫]
M[本地存储] --> N[持久化插件]
end
subgraph "数据库"
M[DashboardUser表]
O[DashboardUser表]
end
B --> M
B --> O
E --> C
D --> M
D --> O
```
**图表来源**
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/routes/auth.js:1-112](file://backend/src/routes/auth.js#L1-L112)
- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
**章节来源**
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [frontend/src/store/modules/auth/index.ts:1-150](file://frontend/src/store/modules/auth/index.ts#L1-L150)
- [frontend/src/service/api/auth.ts:1-120](file://frontend/src/service/api/auth.ts#L1-L120)
## 核心组件
@@ -147,73 +154,128 @@ Next-->>Client : 处理后续逻辑
**图表来源**
- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
- [backend/src/utils/jwt.js:19-21](file://backend/src/utils/jwt.js#L19-L21)
- [backend/src/utils/jwt.js:19-21](file://backend/src/utils/jjwt.js#L19-L21)
### 新增：Pinia认证状态管理
**更新** 系统现在使用基于Pinia的现代化状态管理来替代直接的localStorage操作：
```mermaid
classDiagram
class AuthStore {
+user : UserState
+token : string
+isAuthenticated : boolean
+login(credentials) : Promise~void~
+logout() : void
+checkAuth() : Promise~boolean~
+refreshToken() : Promise~void~
}
class UserState {
+id : number
+username : string
+email : string
+isSuperAdmin : boolean
+permissions : string[]
+lastLoginAt : Date
}
class AuthHooks {
+useAuth() : AuthStore
+useUser() : UserState
+useIsAuthenticated() : ComputedRef~boolean~
+usePermissions() : ComputedRef~string[]~
}
AuthStore --> UserState : "管理用户状态"
AuthHooks --> AuthStore : "提供访问接口"
```
**图表来源**
- [frontend/src/store/modules/auth/index.ts:1-200](file://frontend/src/store/modules/auth/index.ts#L1-L200)
- [frontend/src/hooks/business/auth.ts:1-150](file://frontend/src/hooks/business/auth.ts#L1-L150)
**章节来源**
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/utils/password.js:1-37](file://backend/src/utils/password.js#L1-L37)
- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
- [frontend/src/store/modules/auth/index.ts:1-200](file://frontend/src/store/modules/auth/index.ts#L1-L200)
- [frontend/src/hooks/business/auth.ts:1-150](file://frontend/src/hooks/business/auth.ts#L1-L150)
## 架构概览
系统采用分层架构设计，前后端分离：
系统采用分层架构设计，前后端分离，前端采用现代化的状态管理模式：
```mermaid
graph TB
subgraph "前端层"
A[Vue应用] --> B[API封装]
A[Vue应用] --> B[TypeScript API层]
B --> C[Axios请求]
C --> D[认证工具]
C --> D[Pinia认证状态]
D --> E[认证钩子]
D --> F[路由守卫]
G[本地存储] --> H[持久化插件]
end
subgraph "网络层"
E[HTTP请求]
I[HTTP请求]
end
subgraph "后端层"
F[Express服务器] --> G[路由层]
G --> H[认证中间件]
G --> I[业务逻辑]
I --> J[数据库访问]
J[Express服务器] --> K[路由层]
K --> L[认证中间件]
K --> M[业务逻辑]
M --> N[数据库访问]
end
subgraph "数据层"
K[MySQL数据库]
O[MySQL数据库]
P[Redis缓存]
end
A --> E
E --> F
F --> K
A --> I
I --> J
J --> O
J --> P
```
**图表来源**
- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
- [frontend/src/store/modules/auth/index.ts:1-200](file://frontend/src/store/modules/auth/index.ts#L1-L200)
- [frontend/src/service/api/auth.ts:1-120](file://frontend/src/service/api/auth.ts#L1-L120)
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
## 详细组件分析
### 登录认证流程
登录流程是整个认证系统的核心：
登录流程是整个认证系统的核心，现在通过TypeScript API层和Pinia状态管理实现：
```mermaid
sequenceDiagram
participant User as 用户
participant Frontend as 前端
participant Frontend as 前端组件
participant AuthHook as 认证钩子
participant AuthStore as Pinia认证状态
participant API as TypeScript API层
participant Backend as 后端
participant DB as 数据库
participant JWT as JWT工具
User->>Frontend : 输入用户名密码
Frontend->>Backend : POST /api/auth/login
Frontend->>AuthHook : 调用useAuth().login()
AuthHook->>AuthStore : dispatch login action
AuthStore->>API : 调用authApi.login()
API->>Backend : POST /api/auth/login
Backend->>DB : 查询用户信息
DB-->>Backend : 返回用户数据
Backend->>Backend : 验证密码
Backend->>JWT : createAccessToken(user)
JWT-->>Backend : 返回JWT令牌
Backend-->>Frontend : 返回令牌和用户信息
Frontend->>Frontend : 存储令牌到localStorage
Backend-->>API : 返回令牌和用户信息
API-->>AuthStore : 更新状态
AuthStore->>AuthStore : 持久化到localStorage
AuthStore-->>AuthHook : 触发响应式更新
AuthHook-->>Frontend : 组件自动重新渲染
```
**图表来源**
- [frontend/src/store/modules/auth/index.ts:45-120](file://frontend/src/store/modules/auth/index.ts#L45-L120)
- [frontend/src/service/api/auth.ts:20-80](file://frontend/src/service/api/auth.ts#L20-L80)
- [backend/src/routes/auth.js:24-64](file://backend/src/routes/auth.js#L24-L64)
- [backend/src/utils/jwt.js:7-17](file://backend/src/utils/jwt.js#L7-L17)
- [frontend/src/api/auth.js:1-24](file://frontend/src/api/auth.js#L1-L24)
#### 登录接口实现要点
@@ -223,10 +285,13 @@ Frontend->>Frontend : 存储令牌到localStorage
4. **最后登录时间更新**：成功登录后更新last_login_at字段
5. **令牌生成**：为用户创建JWT访问令牌
6. **响应格式化**：使用统一的ApiResponse格式返回
7. **状态同步**：前端自动更新Pinia状态并持久化
**章节来源**
- [backend/src/routes/auth.js:24-64](file://backend/src/routes/auth.js#L24-L64)
- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
- [frontend/src/store/modules/auth/index.ts:45-120](file://frontend/src/store/modules/auth/index.ts#L45-L120)
- [frontend/src/service/api/auth.ts:20-80](file://frontend/src/service/api/auth.ts#L20-L80)
### 权限验证中间件
@@ -288,48 +353,105 @@ Handler-->>Client : 执行业务逻辑
**图表来源**
- [backend/src/middleware/auth.js:28-33](file://backend/src/middleware/auth.js#L28-L33)
**章节来源**
- [backend/src/middleware/auth.js:28-33](file://backend/src/middleware/auth.js#L28-L33)
### 新增：TypeScript API层
### 前端认证状态管理
前端通过localStorage管理认证状态：
**更新** 系统现在提供完整的TypeScript支持的API层：
```mermaid
classDiagram
class 认证工具 {
+getToken() : string
+setToken(token : string) : void
+clearToken() : void
+getUser() : object
+setUser(user : object) : void
+clearUser() : void
+clearAuth() : void
+getUserFromToken(token? : string) : object
+isSuperAdmin(user? : object) : boolean
+getTokenExpiresAt(token? : string) : number
+isTokenExpired(token? : string) : boolean
class AuthAPI {
+login(credentials : LoginCredentials) : Promise~LoginResponse~
+logout() : Promise~void~
+getUserInfo() : Promise~UserInfo~
+refreshToken() : Promise~RefreshTokenResponse~
+changePassword(params : ChangePasswordParams) : Promise~void~
}
class 本地存储 {
+setItem(key : string, value : string) : void
+getItem(key : string) : string
+removeItem(key : string) : void
class LoginCredentials {
+username : string
+password : string
+rememberMe? : boolean
}
class JWT解析 {
+base64解码 : string
+JSON解析 : object
+提取payload : object
class LoginResponse {
+accessToken : string
+expiresIn : number
+user : UserInfo
}
认证工具 --> 本地存储 : "使用localStorage"
认证工具 --> JWT解析 : "解析令牌"
class UserInfo {
+id : number
+username : string
+email : string
+isSuperAdmin : boolean
+permissions : string[]
+lastLoginAt : string
}
AuthAPI --> LoginCredentials : "接收登录参数"
AuthAPI --> LoginResponse : "返回登录结果"
AuthAPI --> UserInfo : "管理用户信息"
```
**图表来源**
- [frontend/src/utils/auth.js:1-99](file://frontend/src/utils/auth.js#L1-L99)
- [frontend/src/service/api/auth.ts:1-120](file://frontend/src/service/api/auth.ts#L1-L120)
- [frontend/src/typings/api/auth.d.ts:1-80](file://frontend/src/typings/api/auth.d.ts#L1-L80)
### 新增：认证钩子和路由守卫
**更新** 系统提供了专门的认证钩子和路由守卫：
```mermaid
sequenceDiagram
participant Component as Vue组件
participant AuthHook as useAuth钩子
participant Router as 路由守卫
participant Store as Pinia状态
Component->>AuthHook : 调用useAuth().isAuthenticated
AuthHook->>Store : 读取认证状态
Store-->>AuthHook : 返回响应式布尔值
AuthHook-->>Component : 触发组件重新渲染
Router->>Router : 导航守卫检查
Router->>Store : 检查用户认证状态
alt 未认证
Router->>Router : 重定向到登录页
else 已认证
Router->>Router : 允许访问
end
```
**图表来源**
- [frontend/src/hooks/business/auth.ts:1-150](file://frontend/src/hooks/business/auth.ts#L1-L150)
- [frontend/src/router/guard/route.ts:1-100](file://frontend/src/router/guard/route.ts#L1-L100)
**章节来源**
- [frontend/src/utils/auth.js:1-99](file://frontend/src/utils/auth.js#L1-L99)
- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
- [backend/src/middleware/auth.js:28-33](file://backend/src/middleware/auth.js#L28-L33)
- [frontend/src/service/api/auth.ts:1-120](file://frontend/src/service/api/auth.ts#L1-L120)
- [frontend/src/hooks/business/auth.ts:1-150](file://frontend/src/hooks/business/auth.ts#L1-L150)
- [frontend/src/router/guard/route.ts:1-100](file://frontend/src/router/guard/route.ts#L1-L100)
### 新增：认证状态管理详解
**更新** 详细的Pinia认证状态管理实现：
```mermaid
flowchart TD
A[应用启动] --> B[初始化认证状态]
B --> C{检查本地存储}
C --> |有令牌| D[验证令牌有效性]
C --> |无令牌| E[保持未认证状态]
D --> |有效| F[加载用户信息]
D --> |无效| G[清除认证状态]
F --> H[设置已认证状态]
G --> I[重定向到登录页]
H --> J[监听状态变化]
J --> K[自动刷新令牌]
J --> L[权限动态更新]
```
**图表来源**
- [frontend/src/store/modules/auth/index.ts:1-200](file://frontend/src/store/modules/auth/index.ts#L1-L200)
- [frontend/src/store/modules/auth/shared.ts:1-100](file://frontend/src/store/modules/auth/shared.ts#L1-L100)
**章节来源**
- [frontend/src/store/modules/auth/index.ts:1-200](file://frontend/src/store/modules/auth/index.ts#L1-L200)
- [frontend/src/store/modules/auth/shared.ts:1-100](file://frontend/src/store/modules/auth/shared.ts#L1-L100)
### 错误处理机制
@@ -347,14 +469,17 @@ E --> H[记录日志并提示]
subgraph "前端处理"
I[请求拦截器] --> J[添加Authorization头]
K[响应拦截器] --> L[处理401/403状态]
M[认证钩子] --> N[统一错误处理]
end
```
**图表来源**
- [frontend/src/utils/request.js:46-68](file://frontend/src/utils/request.js#L46-L68)
- [frontend/src/store/modules/auth/index.ts:120-200](file://frontend/src/store/modules/auth/index.ts#L120-L200)
- [frontend/src/hooks/business/auth.ts:80-150](file://frontend/src/hooks/business/auth.ts#L80-L150)
**章节来源**
- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
- [frontend/src/store/modules/auth/index.ts:120-200](file://frontend/src/store/modules/auth/index.ts#L120-L200)
- [frontend/src/hooks/business/auth.ts:80-150](file://frontend/src/hooks/business/auth.ts#L80-L150)
## 依赖关系分析
@@ -369,20 +494,24 @@ D[Sequelize] --> E[MySQL驱动]
F[jsonwebtoken] --> G[HS256算法]
H[crypto] --> I[PBKDF2算法]
end
subgraph "前端依赖"
subgraph "前端新依赖"
J[Axios] --> K[HTTP客户端]
L[Element Plus] --> M[UI组件]
N[Vue 3] --> O[响应式框架]
P[Pinia] --> Q[状态管理]
R[TypeScript] --> S[类型系统]
T[Elegant Router] --> U[路由管理]
end
subgraph "开发工具"
P[Nodemon] --> Q[热重载]
R[Vite] --> S[构建工具]
V[Nodemon] --> W[热重载]
X[Vite] --> Y[构建工具]
Z[Prettier] --> AA[代码格式化]
end
```
**图表来源**
- [backend/package.json:11-28](file://backend/package.json#L11-L28)
- [frontend/package.json:10-24](file://frontend/package.json#L10-L24)
- [frontend/package.json:10-24](file://frontend/package.json#L10-24)
### 数据模型关系
@@ -405,16 +534,25 @@ boolean is_super_admin
integer iat
integer exp
}
AUTH_STORE {
object user
string token
boolean isAuthenticated
date lastSynced
}
DASHBOARD_USER ||--o{ JWT_PAYLOAD : "生成令牌"
AUTH_STORE ||--|| JWT_PAYLOAD : "存储令牌"
```
**图表来源**
- [backend/src/models/DashboardUser.js:4-54](file://backend/src/models/DashboardUser.js#L4-L54)
- [backend/src/utils/jwt.js:9-16](file://backend/src/utils/jwt.js#L9-L16)
- [frontend/src/store/modules/auth/shared.ts:1-100](file://frontend/src/store/modules/auth/shared.ts#L1-L100)
**章节来源**
- [backend/src/models/DashboardUser.js:1-58](file://backend/src/models/DashboardUser.js#L1-L58)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [frontend/src/store/modules/auth/shared.ts:1-100](file://frontend/src/store/modules/auth/shared.ts#L1-L100)
## 性能考虑
@@ -430,16 +568,28 @@ DASHBOARD_USER ||--o{ JWT_PAYLOAD : "生成令牌"
2. **密钥长度**：32字节输出确保足够强度
3. **随机盐值**：每次哈希使用不同盐值
### 新增：前端状态管理优化
**更新** 新的Pinia状态管理提供了更好的性能：
1. **响应式更新**：只有依赖的数据发生变化时才触发重新渲染
2. **状态持久化**：自动将认证状态保存到localStorage
3. **懒加载**：按需加载用户信息和权限数据
4. **内存优化**：及时清理不再使用的认证数据
### 缓存策略
```mermaid
flowchart LR
A[用户登录] --> B[生成JWT令牌]
B --> C[浏览器缓存]
C --> D[后续请求复用]
D --> E[减少服务器验证开销]
F[令牌过期] --> G[自动刷新机制]
G --> H[重新登录流程]
B --> C[Pinia状态缓存]
C --> D[浏览器localStorage持久化]
D --> E[后续请求复用]
E --> F[减少服务器验证开销]
G[令牌过期] --> H[自动刷新机制]
H --> I[重新登录流程]
J[权限变更] --> K[状态同步更新]
K --> L[组件自动响应]
```
## 故障排除指南
@@ -457,9 +607,10 @@ G --> H[重新登录流程]
1. 检查JWT_SECRET配置是否正确
2. 验证系统时间同步
3. 确认TOKEN_TTL_HOURS设置合理
4. 检查Pinia状态持久化是否正常
**章节来源**
- [frontend/src/utils/request.js:46-58](file://frontend/src/utils/request.js#L46-L58)
- [frontend/src/store/modules/auth/index.ts:150-200](file://frontend/src/store/modules/auth/index.ts#L150-L200)
#### 权限不足问题
@@ -471,9 +622,11 @@ G --> H[重新登录流程]
1. 确认用户是否为超级管理员
2. 检查数据库中is_super_admin字段
3. 验证权限中间件是否正确配置
4. 检查前端权限钩子是否正确实现
**章节来源**
- [backend/src/middleware/auth.js:28-33](file://backend/src/middleware/auth.js#L28-L33)
- [frontend/src/hooks/business/auth.ts:100-150](file://frontend/src/hooks/business/auth.ts#L100-L150)
#### 密码验证失败
@@ -489,32 +642,54 @@ G --> H[重新登录流程]
**章节来源**
- [backend/src/utils/password.js:16-34](file://backend/src/utils/password.js#L16-L34)
#### 前端认证状态异常
#### 新增：Pinia状态管理问题
**问题现象**：
- 令牌存储损坏
- 用户信息解析失败
- 自动登出问题
- 认证状态丢失
- 组件不响应状态变化
- 本地存储同步失败
**解决方案**：
1. 清除localStorage中的认证数据
2. 检查令牌格式是否正确
3. 验证JWT负载结构
1. 检查Pinia store初始化是否正确
2. 验证本地存储插件配置
3. 确认响应式数据绑定正常
4. 检查TypeScript类型定义是否完整
**章节来源**
- [frontend/src/utils/auth.js:46-50](file://frontend/src/utils/auth.js#L46-L50)
- [frontend/src/store/modules/auth/index.ts:1-100](file://frontend/src/store/modules/auth/index.ts#L1-L100)
- [frontend/src/store/modules/auth/shared.ts:1-100](file://frontend/src/store/modules/auth/shared.ts#L1-L100)
#### 新增：TypeScript API层问题
**问题现象**：
- API调用类型错误
- 响应数据结构不匹配
- 编译时报错
**解决方案**：
1. 检查TypeScript类型定义文件
2. 验证API接口参数类型
3. 确认响应数据结构一致
4. 更新类型定义文件
**章节来源**
- [frontend/src/service/api/auth.ts:1-120](file://frontend/src/service/api/auth.ts#L1-L120)
- [frontend/src/typings/api/auth.d.ts:1-80](file://frontend/src/typings/api/auth.d.ts#L1-L80)
## 结论
本用户认证系统采用了现代Web应用的标准实践，实现了安全、可靠的用户认证机制。系统的主要优势包括：
本用户认证系统采用了现代Web应用的标准实践，实现了安全、可靠的用户认证机制。经过重构后，系统的主要优势包括：
1. **安全性**：采用JWT令牌和PBKDF2密码哈希，提供多层安全保障
2. **易用性**：前后端分离设计，提供清晰的API接口和错误处理
3. **可维护性**：模块化架构，便于扩展和维护
4. **性能**：合理的令牌配置和密码哈希参数，平衡安全性和性能
2. **现代化架构**：基于Pinia的状态管理和TypeScript支持，提供更好的开发体验
3. **易用性**：前后端分离设计，提供清晰的API接口和错误处理
4. **可维护性**：模块化架构，便于扩展和维护
5. **性能**：合理的令牌配置和密码哈希参数，平衡安全性和性能
6. **类型安全**：完整的TypeScript支持，减少运行时错误
建议在生产环境中进一步完善的方面：
- 实现令牌刷新机制
- 添加多因素认证支持
- 增强日志审计功能
- 实施更严格的密码策略
- 实施更严格的密码策略
- 添加认证状态监控和分析