feat(auth): Implement authentication module foundation

2025-03-31 02:21:04 +08:00
parent 2d0cc592e8
commit 8c4d8e4c6a
37 changed files with 2072 additions and 13 deletions
@@ -0,0 +1,269 @@
+# video-auth模块目录架构、功能及接口文档
+
+## 一、目录架构
+
+```
+video-auth/
+├── src/
+│   ├── main/
+│   │   ├── java/
+│   │   │   └── com/nuaa/video/auth/
+│   │   │       ├── config/              # 配置类
+|   |   |       │   ├── RedisConfig.java       # Redis配置
+│   │   │       │   └── SecurityConfig.java    # 安全配置
+│   │   │       ├── controller/          # 控制器
+│   │   │       │   └── AuthController.java    # 认证控制器
+│   │   │       ├── dto/                 # 数据传输对象
+│   │   │       │   ├── LoginDTO.java         # 登录请求DTO
+│   │   │       │   ├── RegisterDTO.java      # 注册请求DTO
+│   │   │       │   └── TokenInfoDTO.java     # 令牌信息DTO
+│   │   │       ├── entity/              # 实体类
+│   │   │       │   ├── AuthUser.java         # 用户实体
+│   │   │       │   ├── AuthRole.java         # 角色实体
+│   │   │       │   ├── AuthPermission.java   # 权限实体
+│   │   │       │   ├── AuthUserRole.java     # 用户角色关联实体
+│   │   │       │   └── AuthRolePermission.java # 角色权限关联实体
+│   │   │       ├── filter/              # 过滤器
+│   │   │       │   └── JwtAuthenticationFilter.java # JWT认证过滤器
+│   │   │       ├── mapper/              # MyBatis映射接口
+│   │   │       │   ├── AuthUserMapper.java       # 用户Mapper
+│   │   │       │   ├── AuthRoleMapper.java       # 角色Mapper
+│   │   │       │   ├── AuthPermissionMapper.java # 权限Mapper
+│   │   │       │   ├── AuthUserRoleMapper.java   # 用户角色Mapper
+│   │   │       │   └── AuthRolePermissionMapper.java # 角色权限Mapper
+│   │   │       ├── service/             # 服务层
+│   │   │       │   ├── AuthUserService.java      # 用户服务接口
+│   │   │       │   ├── CaptchaService.java       # 验证码服务接口
+│   │   │       │   └── impl/                     # 实现类
+│   │   │       │       ├── AuthUserServiceImpl.java
+│   │   │       │       └── CaptchaServiceImpl.java
+│   │   │       ├── utils/               # 工具类
+│   │   │       │   ├── RedisUtils.java        # Redis工具类
+│   │   │       │   └── JwtUtils.java          # JWT工具类
+│   │   │       └── AuthApplication.java # 启动类
+│   │   └── resources/
+│   │       ├── mapper/                  # MyBatis XML映射文件
+│   │       │   └── AuthUserMapper.xml
+│   │       ├── application.yml          # 配置文件
+│   │       ├── application-dev.yml      # 开发环境配置
+└── pom.xml
+```
+
+## 二、功能概述
+
+### 1. 核心功能
+
+- **用户认证**：登录、注册、令牌刷新、登出
+- **安全管理**：JWT生成与验证、密码加密
+- **角色权限**：用户角色和权限的管理
+- **验证码服务**：生成和验证图形验证码
+
+### 2. 业务流程
+
+1. **用户注册**：用户提交注册信息 → 验证码验证 → 创建用户 → 分配默认角色
+2. **用户登录**：用户提交登录信息 → 验证用户凭证 → 生成JWT令牌 → 缓存用户认证信息
+3. **认证鉴权**：请求携带JWT令牌 → JWT过滤器验证令牌 → 提取用户信息 → 设置安全上下文 → 授权访问
+
+## 三、接口文档
+
+### 1. 用户登录
+
+- **URI**: `/auth/login`
+- **方法**: POST
+- **描述**: 用户登录并获取令牌
+- **请求Body**:
+  ```json
+  {
+    "username": "admin",
+    "password": "admin123",
+    "captcha": "1a2b",
+    "captchaKey": "abcd1234"
+  }
+  ```
+- **响应**:
+  ```json
+  {
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
+      "refreshToken": "nQs6NGPzAJbfw5ddsSVGY2iqAomOmGW9",
+      "tokenType": "Bearer",
+      "expiresIn": 86400,
+      "userId": 1,
+      "username": "admin"
+    }
+  }
+  ```
+- **错误码**:
+  - `400`: 参数错误(如验证码错误)
+  - `401`: 用户名或密码错误
+  - `403`: 账号已被禁用
+
+### 2. 用户注册
+
+- **URI**: `/auth/register`
+- **方法**: POST
+- **描述**: 注册新用户
+- **请求Body**:
+  ```json
+  {
+    "username": "newuser",
+    "password": "password123",
+    "confirmPassword": "password123",
+    "email": "user@example.com",
+    "phone": "13800138000",
+    "captcha": "1a2b",
+    "captchaKey": "abcd1234"
+  }
+  ```
+- **响应**:
+  ```json
+  {
+    "code": 200,
+    "message": "操作成功",
+    "data": "注册成功"
+  }
+  ```
+- **错误码**:
+  - `400`: 参数错误(如密码不匹配、验证码错误)
+  - `1002`: 用户名已存在
+
+### 3. 获取验证码
+
+- **URI**: `/auth/captcha`
+- **方法**: GET
+- **描述**: 生成图形验证码
+- **响应**:
+  ```json
+  {
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "captchaKey": "abcd1234",
+      "captchaImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU..."
+    }
+  }
+  ```
+
+### 4. 刷新令牌
+
+- **URI**: `/auth/refresh`
+- **方法**: POST
+- **描述**: 使用刷新令牌获取新的访问令牌
+- **请求参数**:
+  - `refreshToken`: 刷新令牌字符串
+- **响应**:
+  ```json
+  {
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
+      "refreshToken": "new_refresh_token",
+      "tokenType": "Bearer",
+      "expiresIn": 86400,
+      "userId": 1,
+      "username": "admin"
+    }
+  }
+  ```
+- **错误码**:
+  - `401`: 刷新令牌无效或已过期
+
+### 5. 用户登出
+
+- **URI**: `/auth/logout`
+- **方法**: POST
+- **描述**: 用户登出，清除令牌
+- **请求头**:
+  - `Authorization`: Bearer {accessToken}
+- **响应**:
+  ```json
+  {
+    "code": 200,
+    "message": "操作成功",
+    "data": null
+  }
+  ```
+
+### 6. 获取当前用户信息
+
+- **URI**: `/auth/current`
+- **方法**: GET
+- **描述**: 获取当前登录用户的详细信息
+- **请求头**:
+  - `Authorization`: Bearer {accessToken}
+- **响应**:
+  ```json
+  {
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "id": 1,
+      "username": "admin",
+      "email": "admin@example.com",
+      "phone": "13800138000",
+      "status": 1,
+      "lastLoginTime": "2024-03-30T12:30:45",
+      "lastLoginIp": "192.168.1.1",
+      "roles": ["USER_ADMIN"]
+    }
+  }
+  ```
+- **错误码**:
+  - `401`: 未授权
+  - `404`: 用户不存在
+
+## 四、数据库设计
+
+认证模块涉及的主要数据库表：
+
+### 1. auth_user (用户表)
+- `id`: 用户ID (主键)
+- `username`: 用户名
+- `password`: 加密密码
+- `salt`: 加密盐值
+- `email`: 邮箱
+- `phone`: 手机号
+- `status`: 状态(0:禁用,1:正常)
+- `last_login_time`: 最后登录时间
+- `last_login_ip`: 最后登录IP
+
+### 2. auth_role (角色表)
+- `id`: 角色ID (主键)
+- `name`: 角色名称
+- `code`: 角色编码
+- `description`: 角色描述
+
+### 3. auth_permission (权限表)
+- `id`: 权限ID (主键)
+- `name`: 权限名称
+- `code`: 权限编码
+- `description`: 权限描述
+
+### 4. auth_user_role (用户角色关联表)
+- `id`: 主键
+- `user_id`: 用户ID (外键)
+- `role_id`: 角色ID (外键)
+
+### 5. auth_role_permission (角色权限关联表)
+- `id`: 主键
+- `role_id`: 角色ID (外键)
+- `permission_id`: 权限ID (外键)
+
+## 五、认证流程说明
+
+1. **JWT认证流程**:
+   - 用户登录成功后，服务端生成JWT令牌和刷新令牌
+   - 客户端请求时在请求头中携带JWT令牌
+   - 服务端通过JwtAuthenticationFilter验证令牌
+   - 验证通过后，设置SecurityContext并放行请求
+
+2. **权限校验流程**:
+   - 用户登录时加载其角色和权限
+   - 将权限信息缓存到Redis中
+   - 请求鉴权时从SecurityContext获取用户信息
+   - 根据用户角色和权限决定是否允许访问
+
+video-auth模块提供了完整的用户认证、授权和安全管理功能，为整个视频平台提供统一的身份验证服务。