liujiayu/backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
liujiayu
2025-09-11 14:11:34 +08:00
parent 3118df026c
commit 3896c4deec
13 changed files with 1834 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

756
README.md
View File

@@ -1,54 +1,728 @@
# 验证码认证实现说明
# 智能问答聊天系统 (Chat Backend Server)
本项目实现了基于验证码的用户认证机制，不再使用密码进行登录和注册。
## 项目简介
## 主要变更
这是一个基于 **Spring Boot 3.2.4** 和 **Java 17** 开发的智能问答聊天系统后端服务。项目集成了多种AI模型服务，支持普通聊天和深度研究两种问答模式，提供完整的用户认证、会话管理、邮件服务等功能。
1. **验证码请求和验证DTO**
- `VerificationCodeRequest`: 请求发送验证码的DTO
- `VerifyCodeRequest`: 验证验证码的DTO
- 修改了`LoginRequest`和`RegisterRequest`，移除密码字段，改为使用验证码
**项目类型**: RESTful API 服务
**编程语言**: Java 17
**框架**: Spring Boot 3.2.4
**数据库**: MySQL 8.4.5
**ORM框架**: MyBatis-Flex 1.11.0
**认证方式**: JWT + Spring Security
**AI集成**: Spring AI + OpenAI API
2. **认证控制器**
- 新增了`/api/auth/send-code`接口用于发送验证码
- 修改了登录和注册接口以使用验证码认证
## 核心功能特性
3. **用户服务**
- 实现了验证码生成、存储和验证逻辑
- 在开发模式下，验证码会在控制台输出
- 支持使用万能验证码（默认为"123456"）用于测试
### 🤖 智能问答系统
- **普通聊天模式**: 支持日常对话和简单问答
- **深度研究模式**: 提供专业研究分析，包含引用资料和报告生成
- **多模型支持**: 集成 OpenAI GPT-4o-mini 和自定义 LLM 服务
- **流式响应**: 支持实时流式对话体验
4. **配置**
- 在`application.yml`中添加了验证码相关的配置
- 支持配置验证码过期时间、万能验证码和开发模式
### 👤 用户管理系统
- **用户注册/登录**: 支持邮箱注册和JWT认证
- **密码重置**: 邮件验证码重置密码功能
- **用户资料管理**: 个人信息修改和头像上传
- **多种用户类型**: 个人用户、企业用户、管理员
5. **安全配置**
- 更新了`SecurityConfig`以支持跨域请求
- 优化了安全配置结构
### 💬 会话管理
- **会话持久化**: 保存用户对话历史
- **上下文关联**: 支持多轮对话上下文
- **会话分类**: 区分普通聊天和研究模式会话
- **消息序列**: 完整的消息时序管理
## 使用说明
### 🔐 安全认证
- **JWT Token**: 无状态身份认证
- **Spring Security**: 完整的安全框架集成
- **密码加密**: BCrypt 密码哈希存储
- **API权限控制**: 基于角色的访问控制
1. 用户注册/登录流程：
- 用户输入邮箱或手机号，请求发送验证码
- 系统生成验证码，在开发模式下控制台会输出验证码
- 用户输入收到的验证码进行注册或登录
### 📧 邮件服务
- **验证码发送**: 注册和密码重置验证
- **邮件模板**: 支持HTML邮件模板
- **开发模式**: 控制台输出验证码便于调试
2. 万能验证码：
- 在开发或测试环境中，可以使用配置的万能验证码（默认为"123456"）
- 无需等待验证码发送，直接使用万能验证码即可
## 技术架构
3. 配置说明：
```yaml
app:
verification-code:
expiration: 300 # 验证码有效期（秒）
master-code: "123456" # 万能验证码
development-mode: true # 开发模式（控制台输出验证码）
```
### 后端技术栈
```
Spring Boot 3.2.4
├── Spring Web (RESTful API)
├── Spring Security (安全认证)
├── Spring AI (AI模型集成)
├── Spring Mail (邮件服务)
├── MyBatis-Flex (ORM框架)
├── HikariCP (数据库连接池)
├── JWT (JSON Web Token)
├── Lombok (代码简化)
└── SpringDoc OpenAPI (API文档)
```
## 注意事项
### 数据库设计
```
MySQL 8.4.5
├── users (用户主表)
├── conversations (会话表)
├── messages (消息表)
├── conversation_research_meta (研究元数据)
├── membership_levels (会员等级)
└── user_auth_accounts (第三方登录)
```
1. 实际生产环境中，应使用Redis等缓存存储验证码，而非内存存储
2. 需实现真实的短信和邮件发送服务来发送验证码
3. 生产环境应禁用万能验证码和开发模式
4. 当前实现为开发测试版本，注重功能实现，生产环境应加强安全性
### 项目目录结构
```
backserver/
├── src/main/java/com/yundage/chat/
│ ├── ChatApplication.java # 应用程序主入口
│ ├── config/ # 配置类目录
│ │ ├── SecurityConfig.java # Spring Security配置
│ │ ├── JwtAuthenticationFilter.java # JWT认证过滤器
│ │ ├── LlmApiProperties.java # LLM API配置属性
│ │ ├── LlmWebClientConfig.java # LLM WebClient配置
│ │ ├── OpenApiConfig.java # OpenAPI文档配置
│ │ └── UserTypeHandler.java # 用户类型处理器
│ ├── controller/ # 控制器层
│ │ ├── AuthController.java # 认证相关API
│ │ ├── ChatController.java # 聊天相关API
│ │ └── UserController.java # 用户管理API
│ ├── dto/ # 数据传输对象
│ │ ├── AuthResponse.java # 认证响应DTO
│ │ ├── ChatRequest.java # 聊天请求DTO
│ │ ├── ChatResponse.java # 聊天响应DTO
│ │ ├── LoginRequest.java # 登录请求DTO
│ │ ├── RegisterRequest.java # 注册请求DTO
│ │ ├── PasswordResetRequest.java # 密码重置请求DTO
│ │ ├── ResetPasswordRequest.java # 重置密码请求DTO
│ │ ├── StreamResponse.java # 流式响应DTO
│ │ ├── UserDTO.java # 用户信息DTO
│ │ ├── UserProfileUpdateRequest.java # 用户资料更新DTO
│ │ ├── VerificationCodeRequest.java # 验证码请求DTO
│ │ └── VerifyCodeRequest.java # 验证码验证DTO
│ ├── entity/ # 实体类
│ │ ├── User.java # 用户实体
│ │ ├── Conversation.java # 会话实体
│ │ ├── Message.java # 消息实体
│ │ └── PasswordResetToken.java # 密码重置令牌实体
│ ├── enums/ # 枚举类
│ ├── mapper/ # MyBatis映射器
│ ├── service/ # 服务层接口
│ │ ├── ChatService.java # 聊天服务接口
│ │ ├── UserService.java # 用户服务接口
│ │ ├── EmailService.java # 邮件服务接口
│ │ ├── LLMService.java # LLM服务接口
│ │ └── CustomUserDetailsService.java # 用户详情服务
│ ├── service/impl/ # 服务层实现
│ │ ├── ChatServiceImpl.java # 聊天服务实现
│ │ ├── UserServiceImpl.java # 用户服务实现
│ │ ├── EmailServiceImpl.java # 邮件服务实现
│ │ ├── SpringAIModelService.java # Spring AI模型服务
│ │ └── CustomAPIModelService.java # 自定义API模型服务
│ └── util/ # 工具类
├── src/main/resources/
│ ├── application.yml # 应用配置文件
│ ├── schema.sql # 数据库表结构
│ └── mapper/ # MyBatis XML映射文件
│ ├── UserMapper.xml # 用户映射文件
│ └── PasswordResetTokenMapper.xml # 密码重置令牌映射
├── docs/ # 项目文档
│ ├── chat.md # 聊天API设计文档
│ └── 忘记密码和重置密码.md # 密码重置功能文档
├── target/ # Maven构建输出目录
├── Dockerfile # Docker镜像构建文件
├── docker-compose.yml # Docker Compose配置
├── deploy.sh # 部署脚本
├── pom.xml # Maven项目配置
├── 更新.md # 更新日志
└── README.md # 项目说明文档
```
## 快速开始
### 环境要求
- **Java**: 17+
- **Maven**: 3.6+
- **MySQL**: 8.0+
- **Docker**: 20.10+ (可选)
### 本地开发环境搭建
1. **克隆项目**
```bash
git clone <repository-url>
cd backserver
```
2. **配置数据库**
```sql
-- 创建数据库
CREATE DATABASE yunda_qa CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
-- 导入表结构
mysql -u root -p yunda_qa < src/main/resources/schema.sql
```
3. **配置应用参数**
编辑 `src/main/resources/application.yml`:
```yaml
spring:
datasource:
url: jdbc:mysql://localhost:3306/yunda_qa
username: root
password: Zjj7574166
mail:
host: smtp.gmail.com
username: your-email@gmail.com
password: your-app-password
ai:
openai:
api-key: your-openai-api-key
base-url: https://api.openai.com
```
4. **启动应用**
```bash
# 使用Maven启动
mvn spring-boot:run
# 或者编译后启动
mvn clean package
java -jar target/chat-0.0.1-SNAPSHOT.jar
```
5. **访问应用**
- **API服务**: http://localhost:8080
- **API文档**: http://localhost:8080/swagger-ui.html
- **健康检查**: http://localhost:8080/actuator/health
### Docker部署
1. **构建镜像**
```bash
docker build -t backserver-app .
```
2. **使用Docker Compose启动**
```bash
docker-compose up -d
```
## API接口文档
### 认证相关 API
#### 用户注册
```http
POST /api/auth/register
Content-Type: application/json
{
"username": "用户名",
"email": "user@example.com",
"password": "password123"
}
```
#### 用户登录
```http
POST /api/auth/login
Content-Type: application/json
{
"email": "user@example.com",
"password": "password123"
}
```
#### 密码重置
```http
POST /api/auth/forgot-password
Content-Type: application/json
{
"email": "user@example.com"
}
```
### 聊天相关 API
#### 发送消息
```http
POST /api/chat/send
Authorization: Bearer <jwt-token>
Content-Type: application/json
{
"mode": "chat", // chat | research
"conversation_id": "12345", // 可选，会话ID
"message": "你好，什么是AI？" // 用户消息
}
```
#### 流式聊天
```http
POST /api/chat/stream
Authorization: Bearer <jwt-token>
Content-Type: application/json
{
"mode": "chat",
"conversation_id": "12345",
"message": "请详细解释机器学习"
}
```
### 用户管理 API
#### 获取用户信息
```http
GET /api/users/profile
Authorization: Bearer <jwt-token>
```
#### 更新用户资料
```http
PUT /api/users/profile
Authorization: Bearer <jwt-token>
Content-Type: application/json
{
"username": "新用户名",
"avatarUrl": "头像URL"
}
```
## 配置说明
### 应用配置 (application.yml)
#### 数据库配置
```yaml
spring:
datasource:
driver-class-name: com.mysql.cj.jdbc.Driver
url: jdbc:mysql://localhost:3306/yunda_qa
username: root
password: your_password
```
#### JWT配置
```yaml
jwt:
secret: your-jwt-secret-key
expiration: 86400000 # 24小时
```
#### AI模型配置
```yaml
spring:
ai:
openai:
api-key: your-openai-api-key
base-url: https://api.openai.com
chat:
options:
model: gpt-4o-mini
llm:
base-url: http://127.0.0.1:8000 # 自定义LLM服务地址
```
#### 邮件配置
```yaml
spring:
mail:
host: smtp.gmail.com
port: 587
username: your-email@gmail.com
password: your-app-password
properties:
mail:
smtp:
auth: true
starttls:
enable: true
```
## 开发指南
### 代码结构说明
#### 控制器层 (Controller)
- **AuthController**: 处理用户认证相关请求（注册、登录、密码重置）
- **ChatController**: 处理聊天相关请求（发送消息、流式聊天）
- **UserController**: 处理用户管理相关请求（资料查看、更新）
#### 服务层 (Service)
- **UserService**: 用户管理业务逻辑
- **ChatService**: 聊天业务逻辑
- **EmailService**: 邮件发送业务逻辑
- **LLMService**: AI模型调用业务逻辑
#### 数据访问层 (Mapper)
- 使用 MyBatis-Flex 进行数据库操作
- 支持注解和XML两种映射方式
- 提供BaseMapper基础CRUD操作
#### 配置层 (Config)
- **SecurityConfig**: Spring Security安全配置
- **JwtAuthenticationFilter**: JWT认证过滤器
- **OpenApiConfig**: Swagger API文档配置
### 开发规范
#### 代码注释规范
每个类和方法都应包含完整的JavaDoc注释：
```java
/**
* 用户认证控制器
*
* 提供用户注册、登录、密码重置等认证相关功能
*
* @author YourName
* @version 1.0
* @since 2025-01-01
*/
@RestController
@RequestMapping("/api/auth")
public class AuthController {
/**
* 用户注册
*
* @param request 注册请求参数
* @return 注册结果响应
* @throws UserAlreadyExistsException 用户已存在异常
*/
@PostMapping("/register")
public ResponseEntity<AuthResponse> register(@Valid @RequestBody RegisterRequest request) {
// 实现逻辑
}
}
```
#### 异常处理
使用统一的异常处理机制：
```java
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<ErrorResponse> handleUserNotFound(UserNotFoundException ex) {
return ResponseEntity.status(HttpStatus.NOT_FOUND)
.body(new ErrorResponse("USER_NOT_FOUND", ex.getMessage()));
}
}
```
#### 数据验证
使用Bean Validation进行参数验证：
```java
public class RegisterRequest {
@NotBlank(message = "用户名不能为空")
@Size(min = 2, max = 50, message = "用户名长度必须在2-50个字符之间")
private String username;
@NotBlank(message = "邮箱不能为空")
@Email(message = "邮箱格式不正确")
private String email;
@NotBlank(message = "密码不能为空")
@Size(min = 6, max = 100, message = "密码长度必须在6-100个字符之间")
private String password;
}
```
## 测试指南
### 单元测试
```bash
# 运行所有测试
mvn test
# 运行特定测试类
mvn test -Dtest=UserServiceTest
# 运行测试并生成覆盖率报告
mvn test jacoco:report
```
### 集成测试
```bash
# 运行集成测试
mvn verify
# 使用测试配置文件
mvn test -Dspring.profiles.active=test
```
### API测试
使用Swagger UI进行API测试：
1. 启动应用
2. 访问 http://localhost:8080/swagger-ui.html
3. 选择相应的API端点进行测试
## 部署指南
### 生产环境部署
#### 1. 环境变量配置
```bash
export SPRING_PROFILES_ACTIVE=prod
export SPRING_DATASOURCE_URL=jdbc:mysql://prod-db:3306/yunda_qa
export SPRING_DATASOURCE_USERNAME=prod_user
export SPRING_DATASOURCE_PASSWORD=prod_password
export JWT_SECRET=your-production-jwt-secret
export OPENAI_API_KEY=your-production-openai-key
```
#### 2. 使用Docker部署
```bash
# 构建生产镜像
docker build -t backserver-app:latest .
# 启动服务
docker-compose -f docker-compose.prod.yml up -d
```
#### 3. 使用脚本部署
```bash
# 执行部署脚本
chmod +x deploy.sh
./deploy.sh
```
### 监控和日志
#### 应用监控
- **健康检查**: `/actuator/health`
- **应用信息**: `/actuator/info`
- **性能指标**: `/actuator/metrics`
#### 日志配置
```yaml
logging:
level:
com.yundage.chat: INFO
org.springframework.security: WARN
pattern:
file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
file:
name: logs/application.log
```
## 故障排除
### 常见问题
#### 1. 数据库连接失败
```
检查数据库配置和网络连接
确认数据库服务是否正常运行
验证用户名密码是否正确
```
#### 2. JWT认证失败
```
检查JWT密钥配置
确认token是否过期
验证请求头格式是否正确
```
#### 3. AI模型调用失败
```
检查API密钥是否有效
确认网络连接是否正常
验证模型配置是否正确
```
#### 4. 邮件发送失败
```
检查SMTP服务器配置
确认邮箱密码是否正确
验证网络防火墙设置
```
### 调试技巧
#### 启用调试日志
```yaml
logging:
level:
com.yundage.chat: DEBUG
org.springframework.security: DEBUG
```
#### 使用开发工具
```xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<scope>runtime</scope>
</dependency>
```
## 贡献指南
### 开发流程
1. Fork项目到个人仓库
2. 创建功能分支 (`git checkout -b feature/new-feature`)
3. 提交代码 (`git commit -am 'Add new feature'`)
4. 推送分支 (`git push origin feature/new-feature`)
5. 创建Pull Request
### 代码规范
- 遵循Java编码规范
- 使用统一的代码格式化配置
- 编写完整的单元测试
- 添加必要的文档注释
## 版本历史
### v0.0.1-SNAPSHOT (当前版本)
- ✅ 基础用户认证系统
- ✅ JWT token认证
- ✅ 普通聊天功能
- ✅ 深度研究模式
- ✅ 邮件服务集成
- ✅ OpenAI API集成
- ✅ 数据库设计和实现
- ✅ Docker容器化支持
- ✅ API文档生成
### 计划功能
- 🔄 多模型支持扩展
- 🔄 实时WebSocket聊天
- 🔄 文件上传和处理
- 🔄 会话导出功能
- 🔄 用户权限管理
- 🔄 API限流和监控
- 🔄 缓存优化
- 🔄 国际化支持
## 许可证
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
## 联系方式
- **项目维护者**: YunDaGe Team
- **邮箱**: support@yundage.com
- **项目地址**: https://github.com/yundage/backserver
---
**注意**: 本项目目前处于开发阶段，部分功能可能还在完善中。如有问题或建议，欢迎提交Issue或Pull Request。
## 项目架构分析和文档完善总结
### 已完成的工作
#### 📋 项目分析
- ✅ 完整分析了项目目录结构和技术架构
- ✅ 识别了所有主要模块和组件
- ✅ 理解了数据库设计和业务逻辑
- ✅ 分析了API接口设计和功能特性
#### 📚 文档创建和完善
- ✅ **主README.md**: 创建了详细的项目说明文档，包含：
- 项目简介和技术栈
- 完整的目录结构说明
- 快速开始指南
- API接口文档
- 配置说明和部署指南
- 开发规范和测试指南
- 故障排除和版本历史
- ✅ **src/README.md**: 创建了源代码目录说明文档
- ✅ **docs/README.md**: 创建了文档目录说明文档
#### 💻 代码注释完善
- ✅ **ChatApplication.java**: 添加了详细的类和方法注释
- ✅ **AuthController.java**: 添加了完整的控制器注释
- ✅ **User.java**: 添加了详细的实体类注释
- ✅ **ChatService.java**: 添加了完整的服务接口注释
### 项目特点总结
#### 🏗️ 技术架构
- **后端框架**: Spring Boot 3.2.4 + Java 17
- **数据库**: MySQL 8.4.5 + MyBatis-Flex 1.11.0
- **安全认证**: Spring Security + JWT
- **AI集成**: Spring AI + OpenAI API
- **容器化**: Docker + Docker Compose
#### 🚀 核心功能
- **智能问答**: 支持普通聊天和深度研究两种模式
- **用户管理**: 完整的注册、登录、密码重置功能
- **会话管理**: 持久化对话历史，支持多轮对话
- **流式响应**: 实时流式对话体验
- **邮件服务**: 验证码发送和密码重置
#### 📊 数据库设计
- **用户系统**: users, user_auth_accounts, membership_levels
- **会话系统**: conversations, messages, conversation_research_meta
- **安全机制**: 密码重置令牌、验证码管理
### 代码质量改进
#### 📝 注释规范
- 所有主要类都添加了详细的JavaDoc注释
- 方法注释包含参数说明、返回值、异常处理
- 代码逻辑注释解释了关键业务流程
- API注释包含使用示例和注意事项
#### 🔧 开发规范
- 统一的代码注释格式
- 清晰的异常处理机制
- 完整的参数验证
- 安全的权限控制
### 项目优势
#### 💪 技术优势
- 现代化的技术栈，性能优异
- 完整的安全认证体系
- 灵活的AI模型集成
- 标准的RESTful API设计
#### 📖 文档优势
- 详细的项目说明文档
- 完整的API接口文档
- 清晰的开发指南
- 实用的部署说明
#### 🛡️ 安全优势
- JWT无状态认证
- 密码加密存储
- 用户数据隔离
- 完善的权限控制
### 后续改进建议
#### 🔄 功能扩展
- 实时WebSocket聊天
- 文件上传和处理
- 多模型支持扩展
- 用户权限管理优化
#### 📈 性能优化
- 缓存机制集成
- 数据库查询优化
- API限流和监控
- 异步处理优化
#### 🧪 测试完善
- 单元测试覆盖
- 集成测试编写
- API自动化测试
- 性能测试实施
---
**总结**: 这是一个架构清晰、功能完整的智能问答聊天系统。通过详细的文档和代码注释，为后续的开发和维护提供了良好的基础。项目采用了现代化的技术栈，具有良好的扩展性和可维护性。