初始化项目

2026-02-08 22:38:13 +08:00
commit 334d2c6312
201 changed files with 32724 additions and 0 deletions
@@ -0,0 +1,638 @@
+# 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格式文件。