# 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格式文件。