zyh/login_task_web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

添加 vue-router 依赖并配置路由，重构登录组件，完善 HTTP 请求拦截器以支持 token 刷新机制

Browse Source
This commit is contained in:
zyh
2025-08-24 19:49:39 +08:00
parent 69bf5500cd
commit 17a1d4e85a
30 changed files with 2368 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

468
docs/接口文档.md Normal file
View File

@@ -0,0 +1,468 @@
# API 文档
## 用户管理接口
### 创建用户账户
#### 管理员创建用户账户
**接口地址：** `POST /api/admin/accounts`
**请求头：**
```
Content-Type: application/json
Authorization: Bearer {token}
```
**请求参数：**
```json
{
"userType": "ADMIN", // 必填，用户类型：ADMIN 或 AGENT
"username": "newuser", // 必填，用户名，3-64字符，只能包含字母、数字、下划线
"password": "123456", // 必填，密码，6-128字符
"status": "ENABLED", // 可选，状态：ENABLED 或 DISABLED，默认ENABLED
"pointsBalance": 0 // 可选，积分余额（仅AGENT类型），默认0
}
```
**成功响应（200）：**
```json
{
"id": 2,
"userType": "ADMIN",
"username": "newuser",
"status": "ENABLED",
"pointsBalance": 0,
"createdAt": "2025-08-24T18:30:00.000",
"updatedAt": "2025-08-24T18:30:00.000"
}
```
**错误响应：**
**400 Bad Request - 参数验证失败：**
```json
{
"timestamp": "2025-08-24T18:30:00.000",
"status": 400,
"error": "Bad Request",
"message": "Validation failed",
"details": [
{
"field": "username",
"message": "用户名长度必须在3-64字符之间"
},
{
"field": "password",
"message": "密码长度必须在6-128字符之间"
}
]
}
```
**409 Conflict - 用户名已存在：**
```json
{
"timestamp": "2025-08-24T18:30:00.000",
"status": 409,
"error": "Conflict",
"message": "用户名已存在"
}
```
**401 Unauthorized - 未授权：**
```json
{
"timestamp": "2025-08-24T18:30:00.000",
"status": 401,
"error": "Unauthorized",
"message": "访问被拒绝"
}
```
**403 Forbidden - 权限不足：**
```json
{
"timestamp": "2025-08-24T18:30:00.000",
"status": 403,
"error": "Forbidden",
"message": "权限不足，无法创建用户"
}
```
#### 用户自注册接口
**接口地址：** `POST /api/users`
**请求头：**
```
Content-Type: application/json
```
**请求参数：**
```json
{
"userType": "AGENT", // 必填，用户类型：只能为 AGENT
"username": "newagent", // 必填，用户名，3-64字符
"password": "123456", // 必填，密码，6-128字符
"pointsBalance": 0 // 可选，积分余额，默认0
}
```
**成功响应（201）：**
```json
{
"id": 3,
"userType": "AGENT",
"username": "newagent",
"status": "ENABLED",
"pointsBalance": 0,
"createdAt": "2025-08-24T18:30:00.000",
"updatedAt": "2025-08-24T18:30:00.000"
}
```
### 接口说明
#### 权限要求
- **管理员接口** (`/api/admin/accounts`)：需要管理员权限，可以创建ADMIN和AGENT类型用户
- **用户接口** (`/api/users`)：公开接口，只能创建AGENT类型用户
#### 参数说明
**userType（用户类型）：**
- `ADMIN`：管理员用户
- `AGENT`：代理用户
**username（用户名）：**
- 长度：3-64字符
- 格式：只能包含字母、数字、下划线
- 唯一性：系统内必须唯一
**password（密码）：**
- 长度：6-128字符
- 存储：使用BCrypt加密存储
- 安全：建议包含大小写字母、数字和特殊字符
**status（状态）：**
- 可选值：`ENABLED`（启用）、`DISABLED`（禁用）
- 默认值：`ENABLED`
**pointsBalance（积分余额）：**
- 仅AGENT类型用户可以设置
- 类型：整数，不能为负数
- 默认值：0
#### 业务规则
1. 用户名在系统内必须唯一
2. 密码使用BCrypt加密存储，无法解密
3. 创建成功后账户默认状态为ENABLED
4. 只有管理员可以创建ADMIN类型用户
5. 简化的用户模型，去除了角色和显示名称等复杂字段
#### 使用示例
**创建管理员用户：**
```bash
curl -X POST http://localhost:8080/api/admin/accounts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-token" \
-d '{
"userType": "ADMIN",
"username": "admin001",
"password": "Admin123!"
}'
```
**创建代理用户：**
```bash
curl -X POST http://localhost:8080/api/admin/accounts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-token" \
-d '{
"userType": "AGENT",
"username": "agent001",
"password": "Agent123!",
"pointsBalance": 1000
}'
```
**用户自注册：**
```bash
curl -X POST http://localhost:8080/api/users \
-H "Content-Type: application/json" \
-d '{
"userType": "AGENT",
"username": "newuser",
"password": "User123!"
}'
```
### 重置密码接口
**接口地址：** `POST /api/admin/accounts/{id}/reset-password`
**请求头：**
```
Content-Type: application/json
Authorization: Bearer {token}
```
**路径参数：**
- `id`: 账户ID
**请求参数：**
```json
{
"newPassword": "NewPassword123!", // 必填，新密码，6-128字符
"forceLogout": true // 可选，是否强制登出，默认true
}
```
**成功响应（204）：** 无响应体
**错误响应：**
**400 Bad Request - 密码格式错误：**
```json
{
"timestamp": "2025-08-24T18:30:00.000",
"status": 400,
"error": "Bad Request",
"message": "新密码长度必须在6-128字符之间"
}
```
**404 Not Found - 用户不存在：**
```json
{
"timestamp": "2025-08-24T18:30:00.000",
"status": 404,
"error": "Not Found",
"message": "用户不存在"
}
```
### 启用/禁用用户接口
**启用用户：** `POST /api/admin/accounts/{id}/enable`
**禁用用户：** `POST /api/admin/accounts/{id}/disable`
**请求头：**
```
Authorization: Bearer {token}
```
**成功响应（204）：** 无响应体
## 前端接口调用说明
### 用户管理接口 (src/api/users.js)
#### 获取用户列表
```javascript
import { fetchUsers } from '@/api/users'
// 获取用户列表
const params = {
page: 1,
size: 20, // 每页大小，默认20，最大200
keyword: '搜索关键词', // 可选，搜索关键词
userType: 'AGENT', // 可选，用户类型：ADMIN 或 AGENT
status: 'ENABLED' // 可选，账户状态：ENABLED 或 DISABLED
}
const response = await fetchUsers(params)
```
#### 创建用户
```javascript
import { createUser } from '@/api/users'
// 创建管理员用户
const adminPayload = {
userType: 'ADMIN',
username: 'admin001',
password: 'Admin123!',
status: 'ENABLED'
}
// 创建代理用户
const agentPayload = {
userType: 'AGENT',
username: 'agent001',
password: 'Agent123!',
pointsBalance: 1000,
status: 'ENABLED'
}
const response = await createUser(adminPayload)
```
#### 用户自注册（仅限AGENT）
```javascript
import { registerUser } from '@/api/users'
// 用户自注册（公开接口，无需权限）
const agentPayload = {
userType: 'AGENT', // 必填，只能为 AGENT
username: 'newagent', // 必填，用户名，3-64字符
password: 'Agent123!', // 必填，密码，6-128字符
pointsBalance: 0 // 可选，积分余额，默认0
}
const response = await registerUser(agentPayload)
```
#### 更新用户
```javascript
import { updateUser } from '@/api/users'
const payload = {
userType: 'AGENT',
username: 'agent001',
pointsBalance: 2000,
status: 'ENABLED'
}
const response = await updateUser(userId, payload)
```
#### 删除用户
```javascript
import { deleteUser } from '@/api/users'
const response = await deleteUser(userId)
```
#### 设置用户状态
```javascript
import { setUserStatus } from '@/api/users'
// 启用用户
await setUserStatus(userId, true)
// 禁用用户
await setUserStatus(userId, false)
```
#### 重置用户密码
```javascript
import { resetUserPassword } from '@/api/users'
// 重置密码，需要指定新密码
const newPassword = 'NewPassword123!'
const forceLogout = true // 是否强制登出，默认为true
const response = await resetUserPassword(userId, newPassword, forceLogout)
```
### 认证接口 (src/api/auth.js)
#### 用户登录
```javascript
import { login } from '@/api/auth'
const payload = {
username: 'admin',
password: 'admin123'
}
const response = await login(payload)
// 返回包含 accessToken 和 refreshToken 的数据
```
#### 刷新令牌
```javascript
import { refresh } from '@/api/auth'
const payload = {
refreshToken: 'your-refresh-token'
}
const response = await refresh(payload)
```
#### 用户登出
```javascript
import { logout } from '@/api/auth'
const response = await logout()
```
### 前端表单字段映射
#### 用户列表查询参数
- `page`: 页码，默认1
- `size`: 每页大小，默认20，最大200（前端使用pageSize，传参时转换为size）
- `keyword`: 搜索关键词（用户名）
- `userType`: 用户类型筛选 (ADMIN/AGENT)
- `status`: 状态筛选 (ENABLED/DISABLED)
#### 用户创建/编辑表单字段
- `userType`: 用户类型 (ADMIN/AGENT)
- `username`: 用户名
- `password`: 密码 (仅创建时)
- `enabled`: 状态 (true/false，转换为ENABLED/DISABLED)
- `pointsBalance`: 积分余额 (仅AGENT类型)
#### 后端返回数据字段
- `status`: 用户状态 (ENABLED/DISABLED)
- `enabled`: 兼容字段，部分接口可能返回 (true/false)
#### 表单验证规则
- `userType`: 必填
- `username`: 必填，3-64字符
- `password`: 创建时必填，最少6位
- `pointsBalance`: 仅AGENT类型必填，非负整数
### 注意事项
1. **接口路径**: 所有用户管理接口都使用 `/api/admin/accounts` 前缀
2. **权限控制**:
- 需要有效的 Bearer Token
- 只有 ADMIN 类型用户可以访问用户管理功能
- AGENT 类型用户无法访问用户管理页面和接口
3. **状态字段**:
- 前端表单使用 `enabled` (boolean)，提交时转换为 `status` (ENABLED/DISABLED)
- 后端返回使用 `status` (ENABLED/DISABLED)，前端显示时需要转换
4. **积分余额**: 仅AGENT类型用户可以设置积分余额
5. **简化模型**: 去除了角色和显示名称字段，简化了用户管理
6. **错误处理**: 统一使用HTTP状态码和错误消息处理
7. **错误显示**: 前端自动显示后端返回的错误消息，支持字段级错误提示
### 错误处理机制
#### 后端错误响应格式
```json
{
"timestamp": "2025-08-24T18:30:00.000",
"status": 400,
"error": "Bad Request",
"message": "用户名已存在"
}
```
#### 字段验证错误格式
```json
{
"timestamp": "2025-08-24T18:30:00.000",
"status": 400,
"error": "Bad Request",
"message": "Validation failed",
"details": [
{
"field": "username",
"message": "用户名长度必须在3-64字符之间"
},
{
"field": "password",
"message": "密码长度必须在6-128字符之间"
}
]
}
```
#### 前端错误处理
- **全局拦截**: HTTP拦截器自动显示错误消息
- **字段级错误**: 支持显示具体的字段验证错误
- **状态码映射**: 根据HTTP状态码提供友好的错误提示
- **降级处理**: 当无法获取具体错误时，显示默认错误消息

160
docs/权限管理.md Normal file
View File

@@ -0,0 +1,160 @@
# 权限管理文档
## 概述
本系统采用基于角色的权限控制（RBAC）机制，通过用户类型（ADMIN/AGENT）来控制用户的功能访问权限。
## 用户类型
### ADMIN（管理员）
- 拥有系统所有功能的访问权限
- 可以管理用户账户（创建、编辑、删除、启用/禁用）
- 可以管理游戏、订单、报表等所有模块
- 可以访问系统设置
### AGENT（代理商）
- 只能查看游戏、订单、报表等基础信息
- 无法访问用户管理功能
- 无法访问系统设置
- 主要用于业务操作，不具备管理权限
## 权限定义
### 用户管理权限
- `user:view` - 查看用户列表
- `user:create` - 创建用户
- `user:update` - 编辑用户
- `user:delete` - 删除用户
- `user:manage` - 用户管理（包含所有用户相关权限）
### 游戏管理权限
- `game:view` - 查看游戏列表
- `game:create` - 创建游戏
- `game:update` - 编辑游戏
- `game:delete` - 删除游戏
- `game:manage` - 游戏管理（包含所有游戏相关权限）
### 订单管理权限
- `order:view` - 查看订单列表
- `order:manage` - 订单管理
### 报表分析权限
- `report:view` - 查看报表
### 系统设置权限
- `setting:manage` - 系统设置管理
## 角色权限映射
```javascript
const ROLE_PERMISSIONS = {
ADMIN: [
// 管理员拥有所有权限
'user:manage', 'user:create', 'user:update', 'user:delete', 'user:view',
'game:manage', 'game:create', 'game:update', 'game:delete', 'game:view',
'order:manage', 'order:view',
'report:view',
'setting:manage',
],
AGENT: [
// 代理商只有查看权限
'game:view',
'order:view',
'report:view',
]
}
```
## 前端权限控制
### 1. 路由权限控制
- 在路由守卫中检查用户是否有访问权限
- 无权限时自动跳转到仪表盘页面
### 2. 菜单权限控制
- 根据用户权限动态显示/隐藏菜单项
- 代理商用户看不到"用户管理"和"系统设置"菜单
### 3. 页面权限控制
- 在页面组件中检查用户权限
- 无权限时显示权限不足提示
### 4. 操作权限控制
- 根据用户权限显示/隐藏操作按钮
- 代理商用户无法进行用户管理操作
## 权限检查方法
### 1. 权限工具函数
```javascript
import { hasPermission, hasAnyPermission, hasAllPermissions } from '@/utils/permission'
// 检查单个权限
const canCreateUser = hasPermission('user:create')
// 检查多个权限（任一）
const canManageUsers = hasAnyPermission(['user:create', 'user:update', 'user:delete'])
// 检查多个权限（全部）
const canFullManage = hasAllPermissions(['user:create', 'user:update', 'user:delete'])
```
### 2. 权限指令
```vue
<!-- 单个权限 -->
<el-button v-permission="'user:create'">新增用户</el-button>
<!-- 多个权限（OR逻辑） -->
<el-button v-permission="['user:create', 'user:update']">操作</el-button>
<!-- 多个权限（AND逻辑） -->
<el-button v-permission="['user:create', 'user:update', 'AND']">操作</el-button>
<!-- 对象格式 -->
<el-button v-permission="{ permission: ['user:create', 'user:update'], logic: 'OR' }">操作</el-button>
```
### 3. 计算属性
```javascript
const canViewUsers = computed(() => hasPermission('user:view'))
const canCreateUser = computed(() => hasPermission('user:create'))
const canEditUser = computed(() => hasPermission('user:update'))
const canDeleteUser = computed(() => hasPermission('user:delete'))
```
## 后端权限控制
### 1. 接口权限
- 用户管理接口（`/api/admin/accounts`）只允许 ADMIN 用户访问
- 代理商用户访问时返回 403 Forbidden 错误
### 2. 数据权限
- 代理商用户只能查看自己的相关数据
- 管理员可以查看和管理所有数据
## 权限配置
### 添加新权限
1. 在 `src/utils/permission.js` 中的 `PERMISSIONS` 对象中添加新权限
2. 在 `ROLE_PERMISSIONS` 中为不同角色分配权限
3. 在 `ROUTE_PERMISSIONS` 中配置路由权限要求
### 修改角色权限
1. 修改 `ROLE_PERMISSIONS` 中对应角色的权限数组
2. 更新相关的前端权限检查逻辑
## 安全注意事项
1. **前端权限控制仅用于用户体验**，不能作为安全依据
2. **后端必须进行权限验证**，确保数据安全
3. **敏感操作需要二次确认**，如删除用户
4. **权限变更需要重新登录**，确保权限生效
5. **定期审查权限配置**，避免权限泄露
## 测试建议
1. 使用不同用户类型登录，验证权限控制
2. 测试无权限访问时的跳转逻辑
3. 验证菜单和按钮的显示/隐藏
4. 测试后端接口的权限验证
5. 检查权限变更后的效果

193
docs/权限系统配置总结.md Normal file
View File

@@ -0,0 +1,193 @@
# 权限系统配置总结
## 概述
本系统采用基于角色的权限控制（RBAC）机制，通过用户类型（ADMIN/AGENT）来控制用户的功能访问权限。
## 用户类型权限配置
### ADMIN（管理员）
- **权限范围**：拥有系统所有功能的访问权限
- **路由访问**：可以访问所有页面和路由
- **功能权限**：
- 用户管理（创建、编辑、删除、启用/禁用）
- 游戏管理（查看、创建、编辑、删除）
- 订单管理（查看、管理）
- 报表分析（查看）
- 系统设置（管理）
### AGENT（代理商）
- **权限范围**：只能查看基础信息，无管理权限
- **路由访问**：只能访问部分页面
- **功能权限**：
- 游戏查看
- 订单查看
- 报表查看
## 权限检查机制
### 1. 路由权限检查
```javascript
// 管理员可以访问所有路由
export function canAccessRoute(routeName) {
if (isAdmin()) return true
const requiredPermissions = ROUTE_PERMISSIONS[routeName] || []
if (requiredPermissions.length === 0) return true
return hasAnyPermission(requiredPermissions)
}
```
### 2. 功能权限检查
```javascript
// 检查单个权限
const canCreateUser = hasPermission('user:create')
// 检查多个权限（任一）
const canManageUsers = hasAnyPermission(['user:create', 'user:update', 'user:delete'])
// 检查多个权限（全部）
const canFullManage = hasAllPermissions(['user:create', 'user:update', 'user:delete'])
```
### 3. 权限指令使用
```vue
<!-- 单个权限 -->
<el-button v-permission="'user:create'">新增用户</el-button>
<!-- 多个权限（OR逻辑） -->
<el-button v-permission="['user:create', 'user:update']">操作</el-button>
<!-- 多个权限（AND逻辑） -->
<el-button v-permission="['user:create', 'user:update', 'AND']">操作</el-button>
```
## 权限配置详情
### 权限定义
```javascript
export const PERMISSIONS = {
// 用户管理权限
USER_MANAGE: 'user:manage',
USER_CREATE: 'user:create',
USER_UPDATE: 'user:update',
USER_DELETE: 'user:delete',
USER_VIEW: 'user:view',
// 游戏管理权限
GAME_MANAGE: 'game:manage',
GAME_CREATE: 'game:create',
GAME_UPDATE: 'game:update',
GAME_DELETE: 'game:delete',
GAME_VIEW: 'game:view',
// 订单管理权限
ORDER_MANAGE: 'order:manage',
ORDER_VIEW: 'order:view',
// 报表分析权限
REPORT_VIEW: 'report:view',
// 系统设置权限
SETTING_MANAGE: 'setting:manage',
}
```
### 角色权限映射
```javascript
export const ROLE_PERMISSIONS = {
ADMIN: [
// 管理员拥有所有权限
PERMISSIONS.USER_MANAGE, PERMISSIONS.USER_CREATE, PERMISSIONS.USER_UPDATE,
PERMISSIONS.USER_DELETE, PERMISSIONS.USER_VIEW,
PERMISSIONS.GAME_MANAGE, PERMISSIONS.GAME_CREATE, PERMISSIONS.GAME_UPDATE,
PERMISSIONS.GAME_DELETE, PERMISSIONS.GAME_VIEW,
PERMISSIONS.ORDER_MANAGE, PERMISSIONS.ORDER_VIEW,
PERMISSIONS.REPORT_VIEW, PERMISSIONS.SETTING_MANAGE,
],
AGENT: [
// 代理商只有查看权限
PERMISSIONS.GAME_VIEW, PERMISSIONS.ORDER_VIEW, PERMISSIONS.REPORT_VIEW,
]
}
```
### 路由权限映射
```javascript
export const ROUTE_PERMISSIONS = {
'Users': [PERMISSIONS.USER_VIEW],
'Games': [PERMISSIONS.GAME_VIEW],
'Orders': [PERMISSIONS.ORDER_VIEW],
'Reports': [PERMISSIONS.REPORT_VIEW],
'Settings': [PERMISSIONS.SETTING_MANAGE],
}
```
## 权限控制层级
### 1. 路由级权限控制
- 在路由守卫中检查用户是否有访问权限
- 管理员可以访问所有路由
- 代理商只能访问有权限的路由
- 无权限时自动跳转到仪表盘页面
### 2. 菜单级权限控制
- 根据用户权限动态显示/隐藏菜单项
- 代理商用户看不到"用户管理"和"系统设置"菜单
- 管理员可以看到所有菜单项
### 3. 页面级权限控制
- 在页面组件中检查用户权限
- 无权限时显示权限不足提示
- 提供友好的用户体验
### 4. 操作级权限控制
- 根据用户权限显示/隐藏操作按钮
- 代理商用户无法进行用户管理操作
- 使用权限指令控制按钮显示
## 安全注意事项
1. **前端权限控制仅用于用户体验**，不能作为安全依据
2. **后端必须进行权限验证**，确保数据安全
3. **敏感操作需要二次确认**，如删除用户
4. **权限变更需要重新登录**，确保权限生效
5. **定期审查权限配置**，避免权限泄露
## 测试验证
### 权限测试页面
- 访问 `/permission-test` 页面
- 查看当前用户的权限状态
- 测试各种权限检查功能
- 验证路由访问权限
### 测试建议
1. 使用不同用户类型登录，验证权限控制
2. 测试无权限访问时的跳转逻辑
3. 验证菜单和按钮的显示/隐藏
4. 测试后端接口的权限验证
5. 检查权限变更后的效果
## 扩展说明
### 添加新权限
1. 在 `PERMISSIONS` 对象中添加新权限
2. 在 `ROLE_PERMISSIONS` 中为不同角色分配权限
3. 在 `ROUTE_PERMISSIONS` 中配置路由权限要求
4. 更新相关的前端权限检查逻辑
### 修改角色权限
1. 修改 `ROLE_PERMISSIONS` 中对应角色的权限数组
2. 更新相关的前端权限检查逻辑
3. 测试权限变更后的效果
## 总结
当前的权限系统配置确保了：
- **管理员拥有所有权限**，可以访问所有页面和功能
- **代理商只有查看权限**，无法进行管理操作
- **权限检查机制完善**，包括路由、菜单、页面、操作四个层级
- **用户体验友好**，无权限时提供清晰的提示和跳转
- **安全性保障**，前后端都有权限验证机制