639 lines
14 KiB
Markdown
639 lines
14 KiB
Markdown
# Auth 基础模块文档
|
||
|
||
## 概述
|
||
|
||
Auth 基础模块提供了完整的后台管理系统的认证授权功能，包括用户管理、角色管理、权限管理、部门管理等功能。
|
||
|
||
## 控制器结构
|
||
|
||
```
|
||
app/Http/Controllers/Auth/
|
||
└── Admin/
|
||
├── Auth.php # 认证控制器
|
||
├── User.php # 用户管理控制器
|
||
├── Role.php # 角色管理控制器
|
||
├── Permission.php # 权限管理控制器
|
||
└── Department.php # 部门管理控制器
|
||
```
|
||
|
||
**命名空间**: `App\Http\Controllers\Auth\Admin`
|
||
|
||
**路由前缀**: `/admin`
|
||
|
||
**中间件**: `auth.check:admin` (后台管理认证)
|
||
|
||
## 技术栈
|
||
|
||
- PHP 8.1+
|
||
- Laravel 11
|
||
- JWT 认证 (tymon/jwt-auth)
|
||
- Redis 缓存
|
||
- Laravel Excel (maatwebsite/excel)
|
||
|
||
## 数据库表结构
|
||
|
||
### auth_users (用户表)
|
||
- `id`: 主键
|
||
- `username`: 用户名（唯一）
|
||
- `password`: 密码（加密）
|
||
- `real_name`: 真实姓名
|
||
- `email`: 邮箱
|
||
- `phone`: 手机号
|
||
- `avatar`: 头像
|
||
- `department_id`: 部门ID
|
||
- `status`: 状态（0:禁用, 1:启用）
|
||
- `last_login_at`: 最后登录时间
|
||
- `last_login_ip`: 最后登录IP
|
||
- `last_active_at`: 最后活跃时间
|
||
- `created_at`, `updated_at`: 时间戳
|
||
|
||
### auth_roles (角色表)
|
||
- `id`: 主键
|
||
- `name`: 角色名称
|
||
- `code`: 角色编码（唯一）
|
||
- `description`: 角色描述
|
||
- `sort`: 排序
|
||
- `status`: 状态
|
||
- `created_at`, `updated_at`: 时间戳
|
||
|
||
### auth_permissions (权限表)
|
||
- `id`: 主键
|
||
- `name`: 权限名称
|
||
- `code`: 权限编码（唯一，格式：模块.功能.操作）
|
||
- `type`: 类型（menu:菜单, api:接口, button:按钮）
|
||
- `route`: 路由
|
||
- `component`: 组件路径
|
||
- `icon`: 图标
|
||
- `parent_id`: 父级ID
|
||
- `meta`: 元数据（JSON格式）
|
||
- `sort`: 排序
|
||
- `status`: 状态
|
||
- `created_at`, `updated_at`: 时间戳
|
||
|
||
### auth_role_permission (角色权限关联表)
|
||
- `id`: 主键
|
||
- `role_id`: 角色ID
|
||
- `permission_id`: 权限ID
|
||
|
||
### auth_user_role (用户角色关联表)
|
||
- `id`: 主键
|
||
- `user_id`: 用户ID
|
||
- `role_id`: 角色ID
|
||
|
||
### auth_departments (部门表)
|
||
- `id`: 主键
|
||
- `name`: 部门名称
|
||
- `parent_id`: 父级ID
|
||
- `leader`: 负责人
|
||
- `phone`: 联系电话
|
||
- `sort`: 排序
|
||
- `status`: 状态
|
||
- `created_at`, `updated_at`: 时间戳
|
||
|
||
## API 接口文档
|
||
|
||
### 中间件说明
|
||
|
||
### AuthCheckMiddleware
|
||
|
||
这是一个通用的认证中间件，支持通过参数指定不同的路由守卫和权限验证。
|
||
|
||
#### 基本用法
|
||
|
||
**1. 只进行登录认证（不检查权限）**
|
||
|
||
```php
|
||
// 使用 admin 守卫
|
||
Route::middleware(['auth.check:admin'])->group(function () {
|
||
Route::get('/users', [UserController::class, 'index']);
|
||
});
|
||
|
||
// 使用 api 守卫
|
||
Route::middleware(['auth.check:api'])->group(function () {
|
||
Route::get('/profile', [UserController::class, 'profile']);
|
||
});
|
||
```
|
||
|
||
**2. 登录认证 + 权限验证**
|
||
|
||
```php
|
||
// 验证用户是否有特定权限
|
||
Route::middleware(['auth.check:admin,system.user.list'])->group(function () {
|
||
Route::get('/users', [UserController::class, 'index']);
|
||
});
|
||
|
||
// 验证多个权限
|
||
Route::middleware(['auth.check:admin,system.user.create'])->group(function () {
|
||
Route::post('/users', [UserController::class, 'store']);
|
||
});
|
||
```
|
||
|
||
**3. 单个路由应用中间件**
|
||
|
||
```php
|
||
Route::middleware('auth.check:admin,system.user.delete')->delete('/users/{id}', [UserController::class, 'destroy']);
|
||
```
|
||
|
||
#### 参数说明
|
||
|
||
- `guard`: 认证守卫名称（必需），例如：`admin`、`api`
|
||
- `permission`: 权限编码（可选），如果指定则会验证用户是否有该权限
|
||
|
||
#### 功能特性
|
||
|
||
- ✅ 支持多个路由守卫（admin、api等）
|
||
- ✅ 支持登录状态检查
|
||
- ✅ 支持用户状态检查（禁用用户无法访问）
|
||
- ✅ 支持权限验证
|
||
- ✅ 自动将用户信息注入到请求中（$request->auth_user）
|
||
- ✅ 自动更新用户最后活跃时间
|
||
|
||
#### 认证相关
|
||
|
||
#### 登录
|
||
- **接口**: `POST /admin/auth/login`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
- **返回**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "登录成功",
|
||
"data": {
|
||
"token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
|
||
"user": {...},
|
||
"menu": {...},
|
||
"permissions": {...}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 登出
|
||
- **接口**: `POST /admin/auth/logout`
|
||
- **Header**: `Authorization: Bearer {token}`
|
||
|
||
#### 刷新Token
|
||
- **接口**: `POST /admin/auth/refresh`
|
||
- **Header**: `Authorization: Bearer {token}`
|
||
|
||
#### 获取当前用户信息
|
||
- **接口**: `GET /admin/auth/me`
|
||
- **Header**: `Authorization: Bearer {token}`
|
||
|
||
#### 修改密码
|
||
- **接口**: `POST /admin/auth/change-password`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"old_password": "123456",
|
||
"new_password": "654321"
|
||
}
|
||
```
|
||
|
||
### 用户管理
|
||
|
||
#### 获取用户列表
|
||
- **接口**: `GET /admin/users`
|
||
- **参数**:
|
||
- `page`: 页码（默认1）
|
||
- `page_size`: 每页数量（默认20）
|
||
- `keyword`: 搜索关键词（用户名/真实姓名/邮箱）
|
||
- `status`: 状态（0:禁用, 1:启用）
|
||
- `department_id`: 部门ID
|
||
- `role_id`: 角色ID
|
||
- `order_by`: 排序字段（默认id）
|
||
- `order_direction`: 排序方向（asc/desc，默认asc）
|
||
|
||
#### 获取用户详情
|
||
- **接口**: `GET /admin/users/{id}`
|
||
|
||
#### 创建用户
|
||
- **接口**: `POST /admin/users`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"username": "test001",
|
||
"password": "123456",
|
||
"real_name": "测试用户",
|
||
"email": "test@example.com",
|
||
"phone": "13800138000",
|
||
"department_id": 1,
|
||
"role_ids": [1, 2],
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### 更新用户
|
||
- **接口**: `PUT /admin/users/{id}`
|
||
- **参数**: 同创建用户（所有字段都是可选的）
|
||
|
||
#### 删除用户
|
||
- **接口**: `DELETE /admin/users/{id}`
|
||
|
||
#### 批量删除用户
|
||
- **接口**: `POST /admin/users/batch-delete`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"ids": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
#### 批量更新用户状态
|
||
- **接口**: `POST /admin/users/batch-status`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"ids": [1, 2, 3],
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### 批量分配部门
|
||
- **接口**: `POST /admin/users/batch-department`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"ids": [1, 2, 3],
|
||
"department_id": 1
|
||
}
|
||
```
|
||
|
||
#### 批量分配角色
|
||
- **接口**: `POST /admin/users/batch-roles`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"ids": [1, 2, 3],
|
||
"role_ids": [1, 2]
|
||
}
|
||
```
|
||
|
||
#### 导出用户
|
||
- **接口**: `POST /admin/users/export`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"ids": [1, 2, 3] // 可选，不传则导出所有用户
|
||
}
|
||
```
|
||
|
||
#### 导入用户
|
||
- **接口**: `POST /admin/users/import`
|
||
- **参数**: `file` (multipart/form-data, xlsx/xls文件)
|
||
- **返回**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "导入完成，成功 10 条，失败 0 条",
|
||
"data": {
|
||
"success_count": 10,
|
||
"error_count": 0,
|
||
"errors": []
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 下载用户导入模板
|
||
- **接口**: `GET /admin/users/download-template`
|
||
|
||
### 在线用户管理
|
||
|
||
#### 获取在线用户数量
|
||
- **接口**: `GET /admin/online-users/count`
|
||
|
||
#### 获取在线用户列表
|
||
- **接口**: `GET /admin/online-users`
|
||
- **参数**:
|
||
- `limit`: 数量限制（默认100）
|
||
|
||
#### 获取用户的所有会话
|
||
- **接口**: `GET /admin/online-users/{userId}/sessions`
|
||
|
||
#### 强制用户下线（单个会话）
|
||
- **接口**: `POST /admin/online-users/{userId}/offline`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"token": "用户token"
|
||
}
|
||
```
|
||
|
||
#### 强制用户所有设备下线
|
||
- **接口**: `POST /admin/online-users/{userId}/offline-all`
|
||
|
||
### 角色管理
|
||
|
||
#### 获取角色列表
|
||
- **接口**: `GET /admin/roles`
|
||
- **参数**:
|
||
- `page`, `page_size`, `keyword`, `status`, `order_by`, `order_direction`
|
||
|
||
#### 获取所有角色（不分页）
|
||
- **接口**: `GET /admin/roles/all`
|
||
|
||
#### 获取角色详情
|
||
- **接口**: `GET /admin/roles/{id}`
|
||
|
||
#### 创建角色
|
||
- **接口**: `POST /admin/roles`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"name": "编辑",
|
||
"code": "editor",
|
||
"description": "编辑角色",
|
||
"sort": 1,
|
||
"status": 1,
|
||
"permission_ids": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
#### 更新角色
|
||
- **接口**: `PUT /admin/roles/{id}`
|
||
|
||
#### 删除角色
|
||
- **接口**: `DELETE /admin/roles/{id}`
|
||
|
||
#### 批量删除角色
|
||
- **接口**: `POST /admin/roles/batch-delete`
|
||
|
||
#### 批量更新角色状态
|
||
- **接口**: `POST /admin/roles/batch-status`
|
||
|
||
#### 分配权限
|
||
- **接口**: `POST /admin/roles/{id}/permissions`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"permission_ids": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
#### 获取角色的权限列表
|
||
- **接口**: `GET /admin/roles/{id}/permissions`
|
||
|
||
#### 复制角色
|
||
- **接口**: `POST /admin/roles/{id}/copy`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"name": "新角色名称",
|
||
"code": "new_role_code",
|
||
"description": "新角色描述",
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### 批量复制角色
|
||
- **接口**: `POST /admin/roles/batch-copy`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"ids": [1, 2, 3],
|
||
"name": "新角色名称（可选）",
|
||
"code": "new_code（可选）"
|
||
}
|
||
```
|
||
|
||
### 权限管理
|
||
|
||
#### 获取权限列表
|
||
- **接口**: `GET /admin/permissions`
|
||
- **参数**:
|
||
- `page`, `page_size`, `keyword`, `type`, `status`, `order_by`, `order_direction`
|
||
|
||
#### 获取权限树
|
||
- **接口**: `GET /admin/permissions/tree`
|
||
|
||
#### 获取菜单树
|
||
- **接口**: `GET /admin/permissions/menu`
|
||
- **返回**: 当前登录用户的菜单树
|
||
|
||
#### 获取权限详情
|
||
- **接口**: `GET /admin/permissions/{id}`
|
||
|
||
#### 创建权限
|
||
- **接口**: `POST /admin/permissions`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"name": "用户列表",
|
||
"code": "system.user.list",
|
||
"type": "api",
|
||
"route": "/admin/users",
|
||
"component": "",
|
||
"icon": "user",
|
||
"parent_id": 0,
|
||
"sort": 1,
|
||
"status": 1,
|
||
"meta": {
|
||
"title": "用户列表",
|
||
"keepAlive": true
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 更新权限
|
||
- **接口**: `PUT /admin/permissions/{id}`
|
||
|
||
#### 删除权限
|
||
- **接口**: `DELETE /admin/permissions/{id}`
|
||
|
||
#### 批量删除权限
|
||
- **接口**: `POST /admin/permissions/batch-delete`
|
||
|
||
#### 批量更新权限状态
|
||
- **接口**: `POST /admin/permissions/batch-status`
|
||
|
||
### 部门管理
|
||
|
||
#### 获取部门列表
|
||
- **接口**: `GET /admin/departments`
|
||
- **参数**:
|
||
- `page`, `page_size`, `keyword`, `status`, `order_by`, `order_direction`
|
||
|
||
#### 获取部门树
|
||
- **接口**: `GET /admin/departments/tree`
|
||
|
||
#### 获取所有部门（不分页）
|
||
- **接口**: `GET /admin/departments/all`
|
||
|
||
#### 获取部门详情
|
||
- **接口**: `GET /admin/departments/{id}`
|
||
|
||
#### 创建部门
|
||
- **接口**: `POST /admin/departments`
|
||
- **参数**:
|
||
```json
|
||
{
|
||
"name": "技术部",
|
||
"parent_id": 0,
|
||
"leader": "张三",
|
||
"phone": "13800138000",
|
||
"sort": 1,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### 更新部门
|
||
- **接口**: `PUT /admin/departments/{id}`
|
||
|
||
#### 删除部门
|
||
- **接口**: `DELETE /admin/departments/{id}`
|
||
|
||
#### 批量删除部门
|
||
- **接口**: `POST /admin/departments/batch-delete`
|
||
|
||
#### 批量更新部门状态
|
||
- **接口**: `POST /admin/departments/batch-status`
|
||
|
||
#### 导出部门
|
||
- **接口**: `POST /admin/departments/export`
|
||
|
||
#### 导入部门
|
||
- **接口**: `POST /admin/departments/import`
|
||
- **参数**: `file` (multipart/form-data, xlsx/xls文件)
|
||
|
||
#### 下载部门导入模板
|
||
- **接口**: `GET /admin/departments/download-template`
|
||
|
||
## 权限设计
|
||
|
||
### 权限编码规则
|
||
|
||
权限编码采用 `模块.功能.操作` 的格式，例如：
|
||
- `system.user.list` - 系统管理-用户-列表
|
||
- `system.user.create` - 系统管理-用户-创建
|
||
- `system.user.update` - 系统管理-用户-更新
|
||
- `system.user.delete` - 系统管理-用户-删除
|
||
|
||
### 权限类型
|
||
|
||
- **menu**: 菜单类型，用于前端路由配置
|
||
- **api**: API接口类型，用于后端权限验证
|
||
- **button**: 按钮类型，用于前端按钮权限控制
|
||
|
||
## 缓存机制
|
||
|
||
### 用户在线状态缓存
|
||
|
||
- **缓存键**: `user_online:{userId}:{tokenHash}`
|
||
- **过期时间**: 5分钟
|
||
- **用途**: 跟踪用户在线状态、最后活跃时间、登录设备信息
|
||
|
||
### 权限缓存
|
||
|
||
- **用户权限列表**: `permission:user:{userId}:permissions` (60分钟)
|
||
- **用户权限编码**: `permission:user:{userId}:permission_codes` (60分钟)
|
||
- **用户菜单树**: `permission:user:{userId}:menu_tree` (60分钟)
|
||
- **角色权限**: `permission:role:{roleId}:permissions` (60分钟)
|
||
|
||
### 缓存更新时机
|
||
|
||
- 用户登录/刷新token时，更新在线状态
|
||
- 用户角色变化时，清除用户权限缓存
|
||
- 角色权限变化时，清除角色和所有关联用户的权限缓存
|
||
- 权限本身变化时，清除所有权限缓存
|
||
|
||
## 导入导出
|
||
|
||
### 用户导入模板字段
|
||
|
||
- 用户名*（必填）
|
||
- 密码*（必填）
|
||
- 真实姓名*（必填）
|
||
- 邮箱
|
||
- 手机号
|
||
- 部门名称
|
||
- 角色名称（多个用逗号分隔）
|
||
- 备注
|
||
|
||
### 部门导入模板字段
|
||
|
||
- 部门名称*（必填）
|
||
- 上级部门名称
|
||
- 负责人
|
||
- 联系电话
|
||
- 排序
|
||
- 备注
|
||
|
||
### 导出功能
|
||
|
||
- 支持导出全部数据
|
||
- 支持按选中的ID导出
|
||
- 导出文件为Excel格式
|
||
- 下载后自动删除临时文件
|
||
|
||
## 初始化数据
|
||
|
||
运行数据库迁移和填充命令：
|
||
|
||
```bash
|
||
# 执行迁移
|
||
php artisan migrate
|
||
|
||
# 填充初始数据
|
||
php artisan db:seed --class=AuthSeeder
|
||
```
|
||
|
||
初始数据包括：
|
||
- 超级管理员账号（username: admin, password: 123456）
|
||
- 基础角色（超级管理员、管理员）
|
||
- 完整的权限菜单
|
||
- 默认部门
|
||
|
||
## 注意事项
|
||
|
||
1. **Swoole环境注意事项**:
|
||
- 避免使用静态变量存储状态
|
||
- 避免使用全局变量
|
||
- 正确管理数据库连接
|
||
- 使用Redis缓存时注意连接池配置
|
||
|
||
2. **安全注意事项**:
|
||
- 所有密码必须加密存储
|
||
- 使用JWT进行身份认证
|
||
- 敏感操作需要记录日志
|
||
- 定期清理过期的导出文件
|
||
|
||
3. **性能优化**:
|
||
- 使用Redis缓存权限数据
|
||
- 大批量操作使用队列处理
|
||
- 分页查询避免一次性加载过多数据
|
||
|
||
4. **权限验证**:
|
||
- 在中间件中验证用户权限
|
||
- 前端根据权限控制按钮显示
|
||
- 使用权限缓存减少数据库查询
|
||
|
||
## 扩展建议
|
||
|
||
1. **日志审计**: 添加操作日志记录
|
||
2. **数据权限**: 实现基于部门的数据权限控制
|
||
3. **多租户**: 支持多租户场景
|
||
4. **SSO登录**: 支持第三方单点登录
|
||
5. **动态权限**: 支持运行时动态添加权限
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何添加新的权限模块？
|
||
A: 在Seed文件中添加新的权限数据，或者通过API创建新的权限节点。
|
||
|
||
### Q: 导入大量数据时超时怎么办？
|
||
A: 使用队列处理导入任务，分批导入数据。
|
||
|
||
### Q: 如何清理权限缓存？
|
||
A: 调用 `PermissionCacheService::clearAllPermissionCache()` 方法。
|
||
|
||
### Q: Swoole环境下如何热重载？
|
||
A: 运行 `php bin/laravels reload` 命令进行平滑重启。
|
||
|
||
### Q: Excel文件支持哪些格式？
|
||
A: 支持.xlsx和.xls格式文件。
|