# 智能问答聊天系统 (Chat Backend Server) ## 项目简介 这是一个基于 **Spring Boot 3.2.4** 和 **Java 17** 开发的智能问答聊天系统后端服务。项目集成了多种AI模型服务，支持普通聊天和深度研究两种问答模式，提供完整的用户认证、会话管理、邮件服务等功能。 **项目类型**: 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 ## 核心功能特性 ### 🤖 智能问答系统 - **普通聊天模式**: 支持日常对话和简单问答 - **深度研究模式**: 提供专业研究分析，包含引用资料和报告生成 - **多模型支持**: 集成 OpenAI GPT-4o-mini 和自定义 LLM 服务 - **流式响应**: 支持实时流式对话体验 ### 👤 用户管理系统 - **用户注册/登录**: 支持邮箱注册和JWT认证 - **密码重置**: 邮件验证码重置密码功能 - **用户资料管理**: 个人信息修改和头像上传 - **多种用户类型**: 个人用户、企业用户、管理员 ### 💬 会话管理 - **会话持久化**: 保存用户对话历史 - **上下文关联**: 支持多轮对话上下文 - **会话分类**: 区分普通聊天和研究模式会话 - **消息序列**: 完整的消息时序管理 ### 🔐 安全认证 - **JWT Token**: 无状态身份认证 - **Spring Security**: 完整的安全框架集成 - **密码加密**: BCrypt 密码哈希存储 - **API权限控制**: 基于角色的访问控制 ### 📧 邮件服务 - **验证码发送**: 注册和密码重置验证 - **邮件模板**: 支持HTML邮件模板 - **开发模式**: 控制台输出验证码便于调试 ## 技术架构 ### 后端技术栈 ``` 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 (第三方登录) ``` ### 项目目录结构 ``` 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 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 Content-Type: application/json { "mode": "chat", // chat | research "conversation_id": "12345", // 可选，会话ID "message": "你好，什么是AI？" // 用户消息 } ``` #### 流式聊天 ```http POST /api/chat/stream Authorization: Bearer Content-Type: application/json { "mode": "chat", "conversation_id": "12345", "message": "请详细解释机器学习" } ``` ### 用户管理 API #### 获取用户信息 ```http GET /api/users/profile Authorization: Bearer ``` #### 更新用户资料 ```http PUT /api/users/profile Authorization: Bearer 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 register(@Valid @RequestBody RegisterRequest request) { // 实现逻辑 } } ``` #### 异常处理 使用统一的异常处理机制： ```java @ControllerAdvice public class GlobalExceptionHandler { @ExceptionHandler(UserNotFoundException.class) public ResponseEntity 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 org.springframework.boot spring-boot-devtools runtime ``` ## 贡献指南 ### 开发流程 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自动化测试 - 性能测试实施 --- **总结**: 这是一个架构清晰、功能完整的智能问答聊天系统。通过详细的文档和代码注释，为后续的开发和维护提供了良好的基础。项目采用了现代化的技术栈，具有良好的扩展性和可维护性。