first commit

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "java.compile.nullAnalysis.mode": "automatic"
+}

Dockerfile

@@ -17,8 +17,8 @@ COPY src ./src
 # Build the application
 RUN ./mvnw clean package -DskipTests
 
-# Expose port 8080
+# Expose port 9090
-EXPOSE 8080
+EXPOSE 9090
 
 # Run the jar file
 CMD ["java", "-jar", "target/chat-0.0.1-SNAPSHOT.jar"]

README.md

@@ -1,54 +1,728 @@
-# 验证码认证实现说明
+# 智能问答聊天系统 (Chat Backend Server)
 
-本项目实现了基于验证码的用户认证机制，不再使用密码进行登录和注册。
+## 项目简介
 
-## 主要变更
+这是一个基于 **Spring Boot 3.2.4** 和 **Java 17** 开发的智能问答聊天系统后端服务。项目集成了多种AI模型服务，支持普通聊天和深度研究两种问答模式，提供完整的用户认证、会话管理、邮件服务等功能。
 
-1. **验证码请求和验证DTO**
+**项目类型**: RESTful API 服务
-   - `VerificationCodeRequest`: 请求发送验证码的DTO
+**编程语言**: Java 17
-   - `VerifyCodeRequest`: 验证验证码的DTO
+**框架**: Spring Boot 3.2.4
-   - 修改了`LoginRequest`和`RegisterRequest`，移除密码字段，改为使用验证码
+**数据库**: 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:
+Spring Boot 3.2.4
-     verification-code:
+├── Spring Web (RESTful API)
-       expiration: 300 # 验证码有效期（秒）
+├── Spring Security (安全认证)
-       master-code: "123456" # 万能验证码
+├── Spring AI (AI模型集成)
-       development-mode: true # 开发模式（控制台输出验证码）
+├── 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自动化测试
+- 性能测试实施
+
+---
+
+**总结**: 这是一个架构清晰、功能完整的智能问答聊天系统。通过详细的文档和代码注释，为后续的开发和维护提供了良好的基础。项目采用了现代化的技术栈，具有良好的扩展性和可维护性。

docker-compose.yml

@@ -5,7 +5,7 @@ services:
     build: .
     container_name: backserver-app
     ports:
-      - "8080:8080"
+      - "9090:8080"
     environment:
       - SPRING_PROFILES_ACTIVE=prod
       - SPRING_DATASOURCE_URL=jdbc:mysql://101.200.154.78:3306/yunda_qa?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai

docs/README.md

@@ -0,0 +1,163 @@
+# 项目文档目录 (docs/)
+
+## 模块简介
+
+`docs/` 目录包含项目的所有技术文档、API设计文档、功能说明文档等。这些文档为开发者提供详细的功能说明、使用指南和设计思路。
+
+## 目录结构
+
+```
+docs/
+├── README.md                    # 文档目录说明
+├── chat.md                      # 聊天API设计文档
+└── 忘记密码和重置密码.md          # 密码重置功能文档
+```
+
+## 主要文件说明
+
+### chat.md - 聊天API设计文档
+**功能描述**: 详细描述智能问答接口的设计规范和使用方法
+
+**主要内容**:
+- 🤖 **问答模式**: 普通聊天(chat)和深度研究(research)两种模式
+- 📥 **请求格式**: POST /api/qa/ask 接口的请求参数说明
+- 📤 **响应格式**: 返回数据的结构和字段说明
+- 💡 **使用示例**: 包含完整的请求和响应示例
+- 🔧 **字段说明**: 每个参数的类型、必填性和用途
+
+**核心接口**:
+```http
+POST /api/qa/ask
+{
+  "mode": "chat|research",
+  "conversation_id": "可选会话ID",
+  "message": "用户问题"
+}
+```
+
+**适用场景**:
+- API接口开发参考
+- 前端对接指南
+- 测试用例编写
+- 产品功能说明
+
+### 忘记密码和重置密码.md - 密码重置功能文档
+**功能描述**: 详细说明用户密码重置功能的实现流程和技术细节
+
+**主要内容**:
+- 🔐 **安全机制**: 验证码生成和验证流程
+- 📧 **邮件服务**: 邮件发送配置和模板设计
+- ⏰ **时效控制**: 验证码过期时间和重试机制
+- 🛡️ **安全防护**: 防止暴力破解和恶意攻击
+- 🔄 **完整流程**: 从申请重置到密码更新的全流程
+
+**核心流程**:
+1. 用户申请密码重置
+2. 系统发送验证码邮件
+3. 用户输入验证码
+4. 验证通过后设置新密码
+
+**适用场景**:
+- 密码重置功能开发
+- 安全机制设计参考
+- 邮件服务配置指南
+- 用户体验优化
+
+## 如何使用文档
+
+### 开发者使用指南
+
+#### 1. API开发参考
+```bash
+# 查看聊天API设计
+cat docs/chat.md
+
+# 了解密码重置流程
+cat docs/忘记密码和重置密码.md
+```
+
+#### 2. 接口测试
+- 参考`chat.md`中的示例进行API测试
+- 使用Swagger UI: http://localhost:8080/swagger-ui.html
+- 使用Postman导入API文档进行测试
+
+#### 3. 功能实现
+- 按照文档中的设计规范实现功能
+- 遵循文档中的数据格式和错误处理机制
+- 参考安全机制设计相关功能
+
+### 文档维护规范
+
+#### 1. 文档更新
+- 功能变更时及时更新相关文档
+- 保持文档与代码实现的一致性
+- 添加版本号和更新日期
+
+#### 2. 文档格式
+- 使用Markdown格式编写
+- 包含清晰的标题和目录结构
+- 提供完整的示例代码
+
+#### 3. 文档审查
+- 新增文档需要代码审查
+- 定期检查文档的准确性
+- 收集用户反馈并改进文档
+
+## 文档扩展计划
+
+### 待添加文档
+
+#### 技术文档
+- **数据库设计文档**: 详细的表结构和关系说明
+- **架构设计文档**: 系统整体架构和模块关系
+- **部署指南**: 详细的生产环境部署步骤
+- **性能优化指南**: 系统性能调优建议
+
+#### API文档
+- **用户管理API**: 用户注册、登录、资料管理接口
+- **会话管理API**: 会话创建、查询、删除接口
+- **系统管理API**: 系统配置、监控、日志接口
+
+#### 开发文档
+- **开发环境搭建**: 详细的本地开发环境配置
+- **代码规范**: Java代码编写规范和最佳实践
+- **测试指南**: 单元测试、集成测试编写指南
+- **故障排除**: 常见问题和解决方案
+
+#### 用户文档
+- **用户使用手册**: 面向最终用户的功能说明
+- **管理员指南**: 系统管理和配置说明
+- **FAQ**: 常见问题解答
+
+### 文档工具
+
+#### 文档生成
+- **Swagger/OpenAPI**: 自动生成API文档
+- **JavaDoc**: 生成代码文档
+- **GitBook**: 在线文档平台
+
+#### 文档管理
+- **版本控制**: 使用Git管理文档版本
+- **协作编辑**: 支持多人协作编辑
+- **自动发布**: 文档自动部署和更新
+
+## 重要注意事项
+
+### 文档质量
+- 确保文档内容准确无误
+- 提供完整的示例和说明
+- 保持文档结构清晰易读
+
+### 安全考虑
+- 不在文档中暴露敏感信息
+- 密钥和密码使用占位符
+- 生产环境配置单独管理
+
+### 维护更新
+- 定期检查文档的时效性
+- 及时更新过时的信息
+- 收集用户反馈并改进
+
+---
+
+**提示**: 如需查看具体文档内容，请直接打开对应的.md文件。所有文档都使用Markdown格式编写，支持在GitHub、GitLab等平台上直接预览。

src/README.md

@@ -0,0 +1,119 @@
+# 源代码目录 (src/)
+
+## 模块简介
+
+`src/` 目录包含项目的所有源代码，采用标准的Maven项目结构。主要分为主代码(`main/`)和测试代码(`test/`)两个部分。
+
+## 目录结构
+
+```
+src/
+├── main/                           # 主要源代码
+│   ├── java/                       # Java源代码
+│   │   └── com/yundage/chat/       # 主包路径
+│   │       ├── ChatApplication.java    # 应用程序入口
+│   │       ├── config/             # 配置类
+│   │       ├── controller/         # 控制器层
+│   │       ├── dto/                # 数据传输对象
+│   │       ├── entity/             # 实体类
+│   │       ├── enums/              # 枚举类
+│   │       ├── mapper/             # 数据访问层
+│   │       ├── service/            # 服务层
+│   │       └── util/               # 工具类
+│   └── resources/                  # 资源文件
+│       ├── application.yml         # 应用配置
+│       ├── schema.sql              # 数据库表结构
+│       └── mapper/                 # MyBatis映射文件
+└── test/                           # 测试代码 (待创建)
+    ├── java/                       # Java测试代码
+    └── resources/                  # 测试资源文件
+```
+
+## 主要文件说明
+
+### 应用程序入口
+- **ChatApplication.java**: Spring Boot应用程序主入口，包含main方法和基础配置注解
+
+### 配置类 (config/)
+- **SecurityConfig.java**: Spring Security安全配置，定义认证和授权规则
+- **JwtAuthenticationFilter.java**: JWT认证过滤器，处理token验证
+- **LlmApiProperties.java**: LLM API配置属性类
+- **LlmWebClientConfig.java**: LLM服务WebClient配置
+- **OpenApiConfig.java**: Swagger/OpenAPI文档配置
+- **UserTypeHandler.java**: 用户类型枚举处理器
+
+### 控制器层 (controller/)
+- **AuthController.java**: 认证相关API端点（注册、登录、密码重置）
+- **ChatController.java**: 聊天相关API端点（发送消息、流式聊天）
+- **UserController.java**: 用户管理API端点（资料查看、更新）
+
+### 数据传输对象 (dto/)
+- **AuthResponse.java**: 认证响应数据结构
+- **ChatRequest.java**: 聊天请求数据结构
+- **ChatResponse.java**: 聊天响应数据结构
+- **LoginRequest.java**: 登录请求数据结构
+- **RegisterRequest.java**: 注册请求数据结构
+- **StreamResponse.java**: 流式响应数据结构
+- **UserDTO.java**: 用户信息数据传输对象
+
+### 实体类 (entity/)
+- **User.java**: 用户实体，对应users表
+- **Conversation.java**: 会话实体，对应conversations表
+- **Message.java**: 消息实体，对应messages表
+- **PasswordResetToken.java**: 密码重置令牌实体
+
+### 服务层 (service/)
+- **ChatService.java**: 聊天业务逻辑接口
+- **UserService.java**: 用户管理业务逻辑接口
+- **EmailService.java**: 邮件服务接口
+- **LLMService.java**: LLM模型调用接口
+- **CustomUserDetailsService.java**: Spring Security用户详情服务
+
+### 服务实现 (service/impl/)
+- **ChatServiceImpl.java**: 聊天服务具体实现
+- **UserServiceImpl.java**: 用户服务具体实现
+- **EmailServiceImpl.java**: 邮件服务具体实现
+- **SpringAIModelService.java**: Spring AI模型服务实现
+- **CustomAPIModelService.java**: 自定义API模型服务实现
+
+## 如何使用
+
+### 开发新功能
+1. **创建实体类**: 在`entity/`目录下定义数据模型
+2. **创建DTO**: 在`dto/`目录下定义API数据传输对象
+3. **创建Mapper**: 在`mapper/`目录下定义数据访问接口
+4. **创建Service**: 在`service/`目录下定义业务逻辑接口和实现
+5. **创建Controller**: 在`controller/`目录下定义API端点
+
+### 配置管理
+- 修改`application.yml`进行应用配置
+- 在`config/`目录下添加新的配置类
+- 使用`@ConfigurationProperties`绑定配置属性
+
+### 数据库操作
+- 使用MyBatis-Flex进行数据库操作
+- 在`mapper/`目录下定义接口
+- 在`resources/mapper/`目录下编写XML映射文件
+
+## 重要注意事项
+
+### 代码规范
+- 所有类都应包含完整的JavaDoc注释
+- 遵循Spring Boot最佳实践
+- 使用Lombok简化代码
+- 统一异常处理机制
+
+### 安全考虑
+- 敏感信息不要硬编码在代码中
+- 使用配置文件或环境变量管理密钥
+- 所有API都应进行适当的权限验证
+
+### 性能优化
+- 合理使用缓存机制
+- 数据库查询优化
+- 异步处理长时间操作
+
+### 依赖管理
+- 通过Maven管理项目依赖
+- 避免直接修改pom.xml中的版本号
+- 使用Spring Boot的依赖管理机制

src/main/java/com/yundage/chat/ChatApplication.java

@@ -6,12 +6,66 @@ import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 
-@SpringBootApplication
+/**
-@MapperScan("com.yundage.chat.mapper")
+ * 智能问答聊天系统应用程序主入口
-@EnableConfigurationProperties(LlmApiProperties.class)
+ *
+ * 这是一个基于Spring Boot 3.2.4的智能问答聊天系统后端服务，
+ * 集成了多种AI模型服务，支持普通聊天和深度研究两种问答模式。
+ *
+ * 主要功能特性：
+ * - 🤖 智能问答系统：支持普通聊天和深度研究模式
+ * - 👤 用户管理系统：注册、登录、密码重置等完整用户管理
+ * - 💬 会话管理：持久化对话历史，支持多轮对话上下文
+ * - 🔐 安全认证：JWT token认证，Spring Security安全框架
+ * - 📧 邮件服务：验证码发送，密码重置等邮件功能
+ * - 🚀 AI集成：Spring AI + OpenAI API，支持多种LLM模型
+ *
+ * 技术栈：
+ * - Spring Boot 3.2.4 (Web框架)
+ * - Spring Security (安全认证)
+ * - Spring AI (AI模型集成)
+ * - MyBatis-Flex 1.11.0 (ORM框架)
+ * - MySQL 8.4.5 (数据库)
+ * - JWT (身份认证)
+ * - HikariCP (数据库连接池)
+ *
+ * @author YunDaGe Team
+ * @version 0.0.1-SNAPSHOT
+ * @since 2025-01-01
+ */
+@SpringBootApplication  // Spring Boot自动配置注解
+@MapperScan("com.yundage.chat.mapper")  // MyBatis Mapper接口扫描路径
+@EnableConfigurationProperties(LlmApiProperties.class)  // 启用LLM API配置属性
 public class ChatApplication {
 
+    /**
+     * 应用程序主入口方法
+     *
+     * 启动Spring Boot应用程序，初始化所有必要的组件和服务：
+     * - Web服务器 (默认Tomcat，端口8080)
+     * - 数据库连接池
+     * - Spring Security安全配置
+     * - MyBatis数据访问层
+     * - AI模型服务
+     * - 邮件服务
+     *
+     * 启动后可访问：
+     * - API服务: http://localhost:8080
+     * - API文档: http://localhost:8080/swagger-ui.html
+     * - 健康检查: http://localhost:8080/actuator/health
+     *
+     * @param args 命令行参数，支持Spring Boot标准参数
+     *             如：--server.port=8081 修改端口
+     *                --spring.profiles.active=prod 指定环境
+     */
     public static void main(String[] args) {
+        // 启动Spring Boot应用程序
+        // SpringApplication.run()方法会：
+        // 1. 创建ApplicationContext应用上下文
+        // 2. 加载所有配置类和组件
+        // 3. 启动嵌入式Web服务器
+        // 4. 初始化数据库连接
+        // 5. 启动所有自动配置的服务
         SpringApplication.run(ChatApplication.class, args);
     }
 }

src/main/java/com/yundage/chat/controller/AuthController.java

@@ -14,14 +14,75 @@ import org.springframework.web.bind.annotation.*;
 import java.util.HashMap;
 import java.util.Map;
 
-@RestController
+/**
-@RequestMapping("/api/auth")
+ * 用户认证控制器
-@Tag(name = "认证管理", description = "用户认证相关接口")
+ *
+ * 提供完整的用户认证相关功能，包括：
+ * - 📱 验证码发送和验证
+ * - 👤 用户注册和登录
+ * - 🔐 密码重置和找回
+ * - 🚪 用户登出
+ *
+ * 安全特性：
+ * - JWT Token认证机制
+ * - 验证码防刷机制
+ * - 密码加密存储
+ * - 邮件验证码重置密码
+ *
+ * API路径前缀: /api/auth
+ *
+ * @author YunDaGe Team
+ * @version 1.0
+ * @since 2025-01-01
+ */
+@RestController  // 标识为REST控制器，自动序列化返回值为JSON
+@RequestMapping("/api/auth")  // 设置控制器的基础路径
+@Tag(name = "认证管理", description = "用户认证相关接口")  // Swagger文档标签
 public class AuthController {
-    
+
+    /**
+     * 用户服务接口
+     *
+     * 注入UserService来处理具体的业务逻辑：
+     * - 用户注册和登录验证
+     * - 验证码生成和验证
+     * - 密码重置流程
+     * - JWT Token生成和管理
+     */
     @Autowired
     private UserService userService;
     
+    /**
+     * 发送验证码接口
+     *
+     * 向用户的手机号或邮箱发送验证码，用于注册、登录或密码重置。
+     *
+     * 功能特性：
+     * - 📱 支持手机短信验证码（预留功能）
+     * - 📧 支持邮箱验证码
+     * - ⏰ 验证码有效期5分钟
+     * - 🛡️ 防刷机制：同一联系方式1分钟内只能发送一次
+     * - 🔧 开发模式：控制台输出验证码便于调试
+     *
+     * @param request 验证码请求参数，包含联系方式（手机号或邮箱）
+     * @return ApiResponse 包含发送结果，开发模式下返回验证码
+     *
+     * @apiNote 请求示例：
+     * POST /api/auth/send-code
+     * {
+     *   "contact": "user@example.com"
+     * }
+     *
+     * @apiNote 响应示例：
+     * {
+     *   "success": true,
+     *   "message": "验证码发送成功",
+     *   "data": {
+     *     "message": "验证码已发送",
+     *     "code": "123456"  // 仅开发模式返回
+     *   }
+     * }
+     */
     @PostMapping("/send-code")
     @Operation(summary = "发送验证码", description = "向手机或邮箱发送验证码")
     @ApiResponses(value = {
@@ -30,19 +91,72 @@ public class AuthController {
     })
     public ApiResponse<?> sendVerificationCode(@Valid @RequestBody VerificationCodeRequest request) {
         try {
+            // 调用用户服务发送验证码
+            // 返回值：开发模式下返回验证码，生产模式返回null
             String code = userService.sendVerificationCode(request.getContact());
+
+            // 构建响应数据
             Map<String, String> data = new HashMap<>();
             data.put("message", "验证码已发送");
-            // 仅在开发模式下返回验证码
+
+            // 仅在开发模式下返回验证码，便于测试
+            // 生产环境中不会暴露验证码
             if (code != null) {
                 data.put("code", code);
             }
+
             return ApiResponse.success("验证码发送成功", data);
         } catch (Exception e) {
+            // 捕获所有异常，返回统一错误响应
+            // 常见异常：邮件发送失败、联系方式格式错误、发送频率限制等
             return ApiResponse.error(ErrorCode.VERIFICATION_CODE_SEND_FAILED, e.getMessage());
         }
     }
     
+    /**
+     * 用户注册接口
+     *
+     * 创建新用户账号，需要验证码验证。注册成功后自动登录并返回JWT token。
+     *
+     * 注册流程：
+     * 1. 📧 先调用发送验证码接口获取验证码
+     * 2. 📝 填写注册信息（用户名、邮箱、密码、验证码）
+     * 3. ✅ 系统验证验证码有效性
+     * 4. 🔐 密码使用BCrypt加密存储
+     * 5. 🎫 生成JWT token并返回用户信息
+     *
+     * 安全机制：
+     * - 邮箱唯一性检查
+     * - 手机号唯一性检查（预留）
+     * - 验证码时效性验证
+     * - 密码强度要求（6-100字符）
+     *
+     * @param request 注册请求参数，包含用户名、邮箱、密码、验证码
+     * @return ApiResponse<AuthResponse> 包含JWT token和用户基本信息
+     *
+     * @apiNote 请求示例：
+     * POST /api/auth/register
+     * {
+     *   "username": "张三",
+     *   "email": "zhangsan@example.com",
+     *   "password": "password123",
+     *   "verificationCode": "123456"
+     * }
+     *
+     * @apiNote 响应示例：
+     * {
+     *   "success": true,
+     *   "message": "注册成功",
+     *   "data": {
+     *     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+     *     "user": {
+     *       "id": 1,
+     *       "username": "张三",
+     *       "email": "zhangsan@example.com"
+     *     }
+     *   }
+     * }
+     */
     @PostMapping("/register")
     @Operation(summary = "用户注册", description = "注册新用户账号")
     @ApiResponses(value = {
@@ -51,9 +165,12 @@ public class AuthController {
     })
     public ApiResponse<AuthResponse> register(@Valid @RequestBody RegisterRequest request) {
         try {
+            // 调用用户服务进行注册
+            // 内部会验证验证码、检查邮箱唯一性、加密密码、生成JWT token
             AuthResponse response = userService.register(request);
             return ApiResponse.success("注册成功", response);
         } catch (RuntimeException e) {
+            // 根据异常信息返回具体的错误码和消息
             String message = e.getMessage();
             if (message.contains("邮箱已被注册")) {
                 return ApiResponse.error(ErrorCode.EMAIL_ALREADY_REGISTERED, message);
@@ -65,6 +182,7 @@ public class AuthController {
                 return ApiResponse.error(ErrorCode.REGISTER_FAILED, message);
             }
         } catch (Exception e) {
+            // 捕获其他未预期的异常
             return ApiResponse.error(ErrorCode.REGISTER_FAILED, "注册失败");
         }
     }

src/main/java/com/yundage/chat/entity/User.java

@@ -13,80 +13,277 @@ import java.time.LocalDateTime;
 import java.util.Collection;
 import java.util.Collections;
 
-@Table("users")
+/**
-public class User implements UserDetails {
+ * 用户实体类
-    
+ *
-    @Id(keyType = KeyType.Auto)
+ * 对应数据库中的users表，存储用户的基本信息和认证相关数据。
+ * 实现了Spring Security的UserDetails接口，用于身份认证和授权。
+ *
+ * 数据库表结构：
+ * - 主键：id (自增长)
+ * - 基本信息：username, email, phone, avatar_url
+ * - 认证信息：password_hash
+ * - 用户类型：user_type (personal/enterprise/admin)
+ * - 会员等级：membership_level_id
+ * - 状态管理：status (1=正常, 0=封禁)
+ * - 时间戳：created_at, updated_at, last_login_at
+ *
+ * 安全特性：
+ * - 密码使用BCrypt加密存储
+ * - 支持邮箱和手机号登录
+ * - 集成Spring Security权限管理
+ * - 账户状态控制（启用/禁用）
+ *
+ * @author YunDaGe Team
+ * @version 1.0
+ * @since 2025-01-01
+ */
+@Table("users")  // MyBatis-Flex注解，指定对应的数据库表名
+public class User implements UserDetails {  // 实现Spring Security的UserDetails接口
+
+    /**
+     * 用户唯一标识ID
+     *
+     * 数据库主键，自动递增。
+     * 用于唯一标识每个用户，在关联表中作为外键使用。
+     */
+    @Id(keyType = KeyType.Auto)  // 主键，自动生成
     private Long id;
-    
+
+    /**
+     * 用户显示名称
+     *
+     * 用户的昵称或显示名，用于界面展示。
+     * 可以重复，不作为登录凭证使用。
+     * 长度限制：2-50个字符
+     */
     private String username;
-    
+
+    /**
+     * 密码哈希值
+     *
+     * 使用BCrypt算法加密后的密码，不存储明文密码。
+     * 对应数据库字段：password_hash
+     *
+     * 安全要求：
+     * - 原始密码长度：6-100个字符
+     * - 使用BCrypt加密，强度为10
+     * - 支持密码重置功能
+     */
     @Column("password_hash")
     private String passwordHash;
-    
+
+    /**
+     * 手机号码
+     *
+     * 用户的手机号，可作为登录凭证（预留功能）。
+     * 在数据库中具有唯一性约束。
+     * 格式：支持国内11位手机号
+     */
     private String phone;
+
+    /**
+     * 邮箱地址
+     *
+     * 用户的邮箱地址，主要登录凭证。
+     * 在数据库中具有唯一性约束。
+     * 用途：登录认证、密码重置、系统通知
+     */
     private String email;
-    
+
+    /**
+     * 用户头像URL
+     *
+     * 用户头像图片的存储地址。
+     * 对应数据库字段：avatar_url
+     * 支持：本地存储、云存储（OSS/CDN）
+     */
     @Column("avatar_url")
     private String avatarUrl;
-    
+
+    /**
+     * 用户类型
+     *
+     * 定义用户的类型和权限级别：
+     * - PERSONAL: 个人用户（默认）
+     * - ENTERPRISE: 企业用户
+     * - ADMIN: 管理员用户
+     *
+     * 使用自定义TypeHandler处理枚举与数据库的映射。
+     */
     @Column(value = "user_type", typeHandler = com.yundage.chat.config.UserTypeHandler.class)
     private UserType userType;
-    
+
+    /**
+     * 会员等级ID
+     *
+     * 关联membership_levels表的外键。
+     * 用于控制用户的功能权限和使用限制：
+     * - 每日消息数量限制
+     * - 可用功能范围
+     * - 优先级等级
+     *
+     * 默认值：1（基础会员）
+     */
     @Column("membership_level_id")
     private Integer membershipLevelId;
-    
+
+    /**
+     * 用户状态
+     *
+     * 控制用户账户的可用性：
+     * - 1: 正常状态，可以正常使用所有功能
+     * - 0: 封禁状态，禁止登录和使用系统
+     *
+     * 默认值：1（正常状态）
+     */
     private Integer status;
-    
+
+    /**
+     * 创建时间
+     *
+     * 用户账户的创建时间戳。
+     * 数据库字段：created_at
+     * 自动设置为当前时间（CURRENT_TIMESTAMP）
+     */
     @Column("created_at")
     private LocalDateTime createdAt;
-    
+
+    /**
+     * 更新时间
+     *
+     * 用户信息的最后更新时间戳。
+     * 数据库字段：updated_at
+     * 自动更新为当前时间（ON UPDATE CURRENT_TIMESTAMP）
+     */
     @Column("updated_at")
     private LocalDateTime updatedAt;
-    
+
+    /**
+     * 最后登录时间
+     *
+     * 用户最后一次成功登录的时间戳。
+     * 数据库字段：last_login_at
+     * 用于统计用户活跃度和安全监控
+     */
     @Column("last_login_at")
     private LocalDateTime lastLoginAt;
     
+    /**
+     * 默认构造函数
+     *
+     * 初始化用户对象的默认值：
+     * - 用户类型：个人用户（PERSONAL）
+     * - 会员等级：基础会员（ID=1）
+     * - 用户状态：正常状态（1）
+     *
+     * 这些默认值确保新用户具有基本的系统访问权限。
+     */
     public User() {
-        this.userType = UserType.PERSONAL;
+        this.userType = UserType.PERSONAL;      // 默认为个人用户
-        this.membershipLevelId = 1;
+        this.membershipLevelId = 1;             // 默认为基础会员
-        this.status = 1;
+        this.status = 1;                        // 默认为正常状态
     }
-    
+
-    // UserDetails implementation
+    // ==================== Spring Security UserDetails 接口实现 ====================
+
+    /**
+     * 获取用户权限列表
+     *
+     * Spring Security权限管理方法。
+     * 根据用户类型返回对应的角色权限：
+     * - PERSONAL -> ROLE_PERSONAL
+     * - ENTERPRISE -> ROLE_ENTERPRISE
+     * - ADMIN -> ROLE_ADMIN
+     *
+     * @return Collection<GrantedAuthority> 用户权限集合
+     */
     @Override
     public Collection<? extends GrantedAuthority> getAuthorities() {
+        // 将用户类型转换为Spring Security的权限格式
         return Collections.singletonList(new SimpleGrantedAuthority("ROLE_" + userType.name()));
     }
-    
+
+    /**
+     * 获取用户密码
+     *
+     * Spring Security认证方法。
+     * 返回加密后的密码哈希值，用于密码验证。
+     *
+     * @return String 加密后的密码哈希值
+     */
     @Override
     public String getPassword() {
         return passwordHash;
     }
-    
+
+    /**
+     * 获取用户名（登录凭证）
+     *
+     * Spring Security认证方法。
+     * 优先使用邮箱作为用户名，邮箱为空时使用手机号。
+     *
+     * @return String 用户登录凭证（邮箱或手机号）
+     */
     @Override
     public String getUsername() {
         return email != null ? email : phone;
     }
-    
+
+    /**
+     * 账户是否未过期
+     *
+     * Spring Security账户状态检查方法。
+     * 当前实现：账户永不过期。
+     *
+     * @return boolean true表示账户未过期
+     */
     @Override
     public boolean isAccountNonExpired() {
-        return true;
+        return true;  // 账户永不过期
     }
-    
+
+    /**
+     * 账户是否未锁定
+     *
+     * Spring Security账户状态检查方法。
+     * 根据用户状态判断账户是否被锁定：
+     * - status = 1: 账户正常，未锁定
+     * - status = 0: 账户被封禁，已锁定
+     *
+     * @return boolean true表示账户未锁定
+     */
     @Override
     public boolean isAccountNonLocked() {
-        return status == 1;
+        return status == 1;  // 状态为1表示正常，非1表示被锁定
     }
-    
+
+    /**
+     * 凭证是否未过期
+     *
+     * Spring Security凭证状态检查方法。
+     * 当前实现：凭证永不过期。
+     *
+     * @return boolean true表示凭证未过期
+     */
     @Override
     public boolean isCredentialsNonExpired() {
-        return true;
+        return true;  // 凭证永不过期
     }
-    
+
+    /**
+     * 账户是否启用
+     *
+     * Spring Security账户状态检查方法。
+     * 根据用户状态判断账户是否启用：
+     * - status = 1: 账户启用
+     * - status = 0: 账户禁用
+     *
+     * @return boolean true表示账户已启用
+     */
     @Override
     public boolean isEnabled() {
-        return status == 1;
+        return status == 1;  // 状态为1表示启用
     }
     
     // Getters and Setters

src/main/java/com/yundage/chat/service/ChatService.java

@@ -11,45 +11,202 @@ import java.util.List;
 
 /**
  * 聊天服务接口
+ *
+ * 提供智能问答聊天系统的核心业务逻辑接口定义。
+ * 支持两种问答模式和完整的会话管理功能。
+ *
+ * 核心功能：
+ * - 🤖 智能问答处理：普通聊天和深度研究模式
+ * - 🔄 流式响应：实时流式对话体验
+ * - 💬 会话管理：会话创建、查询、删除
+ * - 📝 消息历史：完整的对话记录管理
+ * - 🔐 权限控制：用户级别的数据隔离
+ *
+ * 支持的问答模式：
+ * - chat: 普通聊天模式，适用于日常对话和简单问答
+ * - research: 深度研究模式，提供专业分析和引用资料
+ *
+ * 技术特性：
+ * - 集成多种AI模型（OpenAI GPT、自定义LLM）
+ * - 支持上下文关联的多轮对话
+ * - 实时流式响应（Server-Sent Events）
+ * - 消息持久化存储
+ * - 用户会话隔离
+ *
+ * @author YunDaGe Team
+ * @version 1.0
+ * @since 2025-01-01
  */
 public interface ChatService {
-    
+
     /**
      * 处理流式聊天请求
-     * @param request 聊天请求
+     *
-     * @param user 当前用户
+     * 使用Server-Sent Events (SSE) 技术提供实时流式对话体验。
-     * @return SSE发射器
+     * AI模型的响应会以流的形式逐步返回，用户可以实时看到回答内容。
+     *
+     * 处理流程：
+     * 1. 🔍 验证用户权限和请求参数
+     * 2. 📝 创建或获取会话上下文
+     * 3. 🤖 调用AI模型进行流式生成
+     * 4. 📡 通过SSE实时推送响应内容
+     * 5. 💾 保存用户消息和AI回复到数据库
+     * 6. 📊 记录token使用量和响应时间
+     *
+     * 支持的模式：
+     * - chat: 普通聊天，快速响应
+     * - research: 深度研究，包含引用和分析
+     *
+     * @param request 聊天请求参数，包含消息内容、模式、会话ID等
+     * @param user 当前登录用户，用于权限验证和数据隔离
+     * @return SseEmitter SSE发射器，用于推送流式响应数据
+     *
+     * @throws IllegalArgumentException 请求参数无效
+     * @throws SecurityException 用户权限不足
+     * @throws RuntimeException AI模型调用失败或其他系统错误
+     *
+     * @apiNote 使用示例：
+     * ChatRequest request = new ChatRequest();
+     * request.setMode("chat");
+     * request.setMessage("什么是人工智能？");
+     * SseEmitter emitter = chatService.processChatStream(request, currentUser);
      */
     SseEmitter processChatStream(ChatRequest request, User user);
-    
+
     /**
      * 处理普通聊天请求
-     * @param request 聊天请求
+     *
-     * @param user 当前用户
+     * 传统的请求-响应模式，等待AI模型完成回答后一次性返回完整结果。
-     * @return 聊天响应
+     * 适用于不需要实时反馈的场景或客户端不支持SSE的情况。
+     *
+     * 处理流程：
+     * 1. 🔍 验证用户权限和请求参数
+     * 2. 📝 创建或获取会话上下文
+     * 3. 🤖 调用AI模型生成完整回答
+     * 4. 💾 保存用户消息和AI回复到数据库
+     * 5. 📊 记录token使用量和响应时间
+     * 6. 📤 返回完整的聊天响应
+     *
+     * 响应内容：
+     * - 完整的AI回答文本
+     * - 会话ID和消息ID
+     * - token使用统计
+     * - 响应时间统计
+     * - 引用资料（research模式）
+     *
+     * @param request 聊天请求参数，包含消息内容、模式、会话ID等
+     * @param user 当前登录用户，用于权限验证和数据隔离
+     * @return ChatResponse 完整的聊天响应，包含AI回答和元数据
+     *
+     * @throws IllegalArgumentException 请求参数无效
+     * @throws SecurityException 用户权限不足
+     * @throws RuntimeException AI模型调用失败或其他系统错误
+     *
+     * @apiNote 使用示例：
+     * ChatRequest request = new ChatRequest();
+     * request.setMode("research");
+     * request.setMessage("分析区块链技术的发展趋势");
+     * ChatResponse response = chatService.processChat(request, currentUser);
      */
     ChatResponse processChat(ChatRequest request, User user);
-    
+
     /**
      * 获取用户的会话列表
-     * @param userId 用户ID
+     *
-     * @return 会话列表
+     * 查询指定用户的所有会话记录，按最后更新时间倒序排列。
+     * 支持数据隔离，用户只能查看自己的会话。
+     *
+     * 返回信息：
+     * - 会话ID和标题
+     * - 会话模式（chat/research）
+     * - 创建和更新时间
+     * - 会话状态（活跃/归档）
+     * - 消息数量统计
+     *
+     * 数据安全：
+     * - 严格的用户权限验证
+     * - 只返回当前用户的会话
+     * - 过滤已删除的会话
+     *
+     * @param userId 用户ID，必须是有效的用户标识
+     * @return List<Conversation> 用户的会话列表，按更新时间倒序
+     *
+     * @throws IllegalArgumentException 用户ID无效
+     * @throws SecurityException 用户权限不足
+     *
+     * @apiNote 使用示例：
+     * List<Conversation> conversations = chatService.getUserConversations(userId);
+     * conversations.forEach(conv -> System.out.println(conv.getTitle()));
      */
     List<Conversation> getUserConversations(Long userId);
-    
+
     /**
      * 获取会话消息历史
-     * @param conversationId 会话ID
+     *
-     * @param userId 用户ID
+     * 查询指定会话的所有消息记录，按时间顺序排列。
-     * @return 消息列表
+     * 包含用户消息和AI回复的完整对话历史。
+     *
+     * 返回信息：
+     * - 消息ID和序号
+     * - 消息角色（user/assistant/system）
+     * - 消息内容和时间戳
+     * - token使用量和响应时间
+     * - 消息状态和元数据
+     *
+     * 权限控制：
+     * - 验证会话归属权
+     * - 只允许查看自己的会话消息
+     * - 过滤已删除的消息
+     *
+     * @param conversationId 会话ID，必须是有效的会话标识
+     * @param userId 用户ID，用于权限验证
+     * @return List<Message> 会话的消息列表，按时间顺序排列
+     *
+     * @throws IllegalArgumentException 会话ID或用户ID无效
+     * @throws SecurityException 用户无权访问该会话
+     * @throws RuntimeException 数据库查询失败
+     *
+     * @apiNote 使用示例：
+     * List<Message> messages = chatService.getConversationMessages(conversationId, userId);
+     * messages.forEach(msg -> System.out.println(msg.getRole() + ": " + msg.getContent()));
      */
     List<Message> getConversationMessages(Long conversationId, Long userId);
-    
+
     /**
      * 删除用户会话
-     * @param conversationId 会话ID
+     *
-     * @param userId 用户ID
+     * 软删除指定的会话及其所有相关消息。
-     * @return 是否删除成功
+     * 实际上是将会话状态标记为非活跃，而不是物理删除数据。
+     *
+     * 删除操作：
+     * - 🗑️ 标记会话为非活跃状态
+     * - 📝 保留消息数据用于审计
+     * - 🔒 立即生效，用户无法再访问
+     * - 📊 更新用户统计信息
+     *
+     * 权限验证：
+     * - 验证会话归属权
+     * - 只允许删除自己的会话
+     * - 管理员可删除任意会话（预留）
+     *
+     * 数据安全：
+     * - 软删除机制，数据可恢复
+     * - 操作日志记录
+     * - 事务性操作，确保数据一致性
+     *
+     * @param conversationId 会话ID，必须是有效的会话标识
+     * @param userId 用户ID，用于权限验证
+     * @return boolean 删除是否成功，true表示删除成功
+     *
+     * @throws IllegalArgumentException 会话ID或用户ID无效
+     * @throws SecurityException 用户无权删除该会话
+     * @throws RuntimeException 数据库操作失败
+     *
+     * @apiNote 使用示例：
+     * boolean success = chatService.deleteConversation(conversationId, userId);
+     * if (success) {
+     *     System.out.println("会话删除成功");
+     * }
      */
     boolean deleteConversation(Long conversationId, Long userId);
 }

src/main/resources/application.yml

@@ -1,79 +1,107 @@
+# Spring Boot 主配置文件
 spring:
+  # 数据源配置 - 用于连接MySQL数据库
   datasource:
-    driver-class-name: com.mysql.cj.jdbc.Driver
+    driver-class-name: com.mysql.cj.jdbc.Driver  # MySQL 8.0 驱动类
+    # 数据库连接URL - 包含服务器地址、端口、数据库名和连接参数
+    # useUnicode=true&characterEncoding=utf8: 启用Unicode并设置字符编码为UTF-8
+    # serverTimezone=Asia/Shanghai: 设置服务器时区为上海（东八区）
     url: jdbc:mysql://101.200.154.78:3306/yunda_qa?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
-    username: root
+    username: root          # 数据库用户名
-    password: mysql_Jt3yzh
+    password: mysql_Jt3yzh  # 数据库密码
 
-  # Mail configuration
+  # 邮件服务配置 - 用于发送验证码和密码重置邮件
   mail:
-    host: smtp.gmail.com
+    host: smtp.gmail.com          # SMTP服务器地址（注意：当前配置不匹配，QQ邮箱应使用smtp.qq.com）
-    port: 587
+    port: 587                     # SMTP端口号（587是TLS加密端口）
-    username: your-email@gmail.com
+    username: 487594186@qq.com    # 发送邮件的邮箱地址
-    password: your-app-password
+    password: rqpbeqtirspsbhaa     # 邮箱授权码（不是邮箱登录密码，需要在邮箱设置中开启并获取）
     properties:
       mail:
         smtp:
-          auth: true
+          auth: true              # 启用SMTP身份验证
           starttls:
-            enable: true
+            enable: true          # 启用STARTTLS安全传输（邮件加密）
+            
+  # AI人工智能服务配置 - 用于聊天机器人功能
   ai:
     openai:
-      api-key: sk-5gAxnpuwJ9KIsea51cD05e21F1Ac4b6a99C8A97278C1F837
+      # OpenAI API密钥 - 用于访问AI模型服务
-      base-url: https://www.jzhengda-api.com
+      api-key: sk-VXQjKSH5ZTwfGjJl58Af3f5dCa3746A99200D365D7Dc31Ff  
+      # API基础URL - 使用代理服务而非官方OpenAI地址
+      base-url: https://jzd.itya.xyz                                    
       chat:
         options:
-          model: gpt-4o-mini
+          model: qwen-plus        # 使用的AI模型：通义千问Plus
+  
+  # Spring Security 安全框架配置
   security:
-    debug: true
+    debug: true                   # 开启安全调试模式（生产环境建议关闭）
+
+# 自定义大语言模型服务配置 - 本地部署的LLM服务
 llm:
-  base-url: http://127.0.0.1:8000   # 可以是服务名或完整URL
+  base-url: http://127.0.0.1:8000   # 本地LLM服务地址（localhost:8000）
-  # api-key: sk-xxxx             # 预留认证字段
+  # api-key: sk-xxxx                # 预留的API认证密钥字段（暂未启用）
-# MyBatis-Flex configuration
+
+# MyBatis-Flex 数据库框架配置 - 用于数据库操作和SQL映射
 mybatis-flex:
-  # Enable SQL logging
   configuration:
+    # 启用SQL日志输出到控制台（开发环境用于调试SQL语句）
     log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
-  # Mapper XML location (optional)
+  # Mapper XML文件位置配置（可选）
-
+  # classpath*:mapper/*.xml 表示扫描所有jar包中mapper目录下的xml文件
   mapper-locations: classpath*:mapper/*.xml
-# JWT configuration
+
+# JWT令牌配置 - 用于用户身份认证和授权
 jwt:
+  # JWT签名密钥 - 用于生成和验证JWT令牌的安全密钥
   secret: mySecretKeyForJWTTokenGenerationAndValidation
-  expiration: 86400000 # 24 hours in milliseconds
+  # JWT令牌过期时间（毫秒）- 86400000毫秒 = 24小时
+  expiration: 86400000
 
-# App configuration
+# 应用程序自定义配置
 app:
+  # 密码重置页面URL - 前端重置密码页面地址
   reset-password-url: http://localhost:3000/reset-password
+  # 验证码相关配置
   verification-code:
-    expiration: 300 # 5 minutes in seconds
+    expiration: 300 # 验证码过期时间（秒）- 300秒 = 5分钟
-    master-code: "123456" # Master code for testing
+    master-code: "123456" # 万能验证码（仅用于测试环境）
-    development-mode: true # Enable printing code to console in development mode
+    development-mode: true # 开发模式 - 启用后会在控制台打印验证码
 
-# Server configuration
+# 服务器配置
 server:
-  port: 8080
+  port: 8080  # 应用程序运行端口号
 
-# SpringDoc OpenAPI configuration
+# SpringDoc OpenAPI 文档配置 - 用于生成和展示API文档
 springdoc:
   api-docs:
-    path: /api-docs
+    path: /api-docs  # API文档JSON格式访问路径
   swagger-ui:
-    path: /swagger-ui.html
+    path: /swagger-ui.html  # Swagger UI界面访问路径
-    try-it-out-enabled: true
+    try-it-out-enabled: true  # 启用"试用"功能，可直接在文档中测试API
-    operationsSorter: method
+    operationsSorter: method  # API操作按HTTP方法排序
-    tagsSorter: alpha
+    tagsSorter: alpha  # API标签按字母顺序排序
 
-# Logging configuration
+# 日志配置 - 控制不同组件的日志输出级别
 logging:
   level:
-    org.mybatis: warn
+    # MyBatis相关日志级别
-    org.apache.ibatis: warn
+    org.mybatis: warn                    # MyBatis框架日志级别设为警告
-    org.apache.ibatis.logging: off
+    org.apache.ibatis: warn              # Apache iBatis日志级别设为警告
-    org.mybatis.spring.SqlSessionUtils: warn
+    org.apache.ibatis.logging: off       # 关闭iBatis详细日志输出
-    com.yundage.chat: debug
+    org.mybatis.spring.SqlSessionUtils: warn  # MyBatis Spring集成日志级别
-    com.mybatisflex: warn
+    
-    org.springframework.security: DEBUG
+    # 应用程序自定义日志
-    reactor.netty.http.client: DEBUG
+    com.yundage.chat: debug              # 聊天模块日志级别设为调试（显示详细信息）
-#    org.springframework: DEBUG
+    com.mybatisflex: warn                # MyBatis-Flex框架日志级别
+    
+    # Spring框架相关日志
+    org.springframework.security: DEBUG  # Spring Security安全框架调试日志
+    reactor.netty.http.client: DEBUG    # Reactor Netty HTTP客户端调试日志
+    
+    # 可选的全局调试配置（已注释）
+    #    org.springframework: DEBUG      # 整个Spring框架调试日志（慎用，日志量大）
+    
+# 全局调试模式开关（已注释，谨慎启用）
 #debug: true

个人环境配置.md

@@ -0,0 +1,123 @@
+
+环境	版本	状态	验证结果
+Java	21.0.7	✅ 符合要求	满足17+要求
+Maven	3.6.1	✅ 符合要求	满足3.6+要求
+MySQL	8.0.27	✅ 符合要求	满足8.0+要求
+Docker	28.0.1	✅ 符合要求	满足20.10+要求
+
+
+netstat -ano | findstr LISTEN
+
+查看端口
+
+tasklist | findstr java
+
+查看java进程
+
+netsh interface ipv4 show excludedportrange protocol=tcp
+
+查看保留端口
+
+# 项目维护者运行一次，提交到Git
+mvn wrapper:wrapper
+git add .mvn/ mvnw mvnw.cmd
+git commit -m "Add Maven Wrapper"
+
+## 开发启动
+1. 克隆项目
+2. 运行 `mvn spring-boot:run`
+3. 访问 http://localhost:8083
+
+## 生产部署
+1. 运行 `docker build -t backserver-app .`
+2. 运行 `docker run -p 8083:8083 backserver-app`
+
+建议创建不同环境的配置：
+application.yml - 默认配置
+application-dev.yml - 开发环境
+application-prod.yml - 生产环境
+
+# application-dev.yml
+server:
+  port: 8083
+logging:
+  level:
+    com.yundage.chat: debug
+
+
+    日常开发：都使用 mvn spring-boot:run
+快速启动
+便于调试
+环境一致
+提交前测试：使用 mvn clean package + java -jar
+确保打包正常
+模拟生产环境
+部署：使用Docker
+环境隔离
+便于迁移
+
+
+# 添加单个文件
+git add git_test.txt
+
+# 或者添加所有修改的文件
+git add .
+# 提交并添加提交信息
+git commit -m "添加 git_test.txt 文件"
+
+# 或者更详细的提交信息
+git commit -m "test: 添加测试文件 git_test.txt"
+
+一次上传：
+git push origin master
+
+一次拉取
+
+git pull origin master
+
+
+# 1. 获取最新的远程更改（不合并）
+git fetch origin
+
+# 2. 查看有哪些更新
+git log HEAD..origin/master --oneline
+
+# 3. 合并远程更改到本地
+git merge origin/master
+
+
+
+# 查看最近的提交记录
+git log --oneline -5
+
+# 查看当前工作区状态
+git status
+
+# 查看最后一次提交的详细信息
+git show HEAD
+
+# 查看提交历史
+git log
+
+# 查看简洁的提交历史
+git log --oneline
+
+# 查看特定文件的提交历史
+git log git_test.txt
+
+# 查看提交的详细变更
+git show <commit-hash>
+
+# 查看远程仓库地址
+git remote -v
+
+# 查看所有配置信息
+git config --list
+
+# 查看当前分支信息
+git branch -vv
+
+# 查看仓库基本信息
+git remote show origin
+
+

更新.md

@@ -0,0 +1,54 @@
+# 验证码认证实现说明
+
+本项目实现了基于验证码的用户认证机制，不再使用密码进行登录和注册。
+
+## 主要变更
+
+1. **验证码请求和验证DTO**
+   - `VerificationCodeRequest`: 请求发送验证码的DTO
+   - `VerifyCodeRequest`: 验证验证码的DTO
+   - 修改了`LoginRequest`和`RegisterRequest`，移除密码字段，改为使用验证码
+
+2. **认证控制器**
+   - 新增了`/api/auth/send-code`接口用于发送验证码
+   - 修改了登录和注册接口以使用验证码认证
+
+3. **用户服务**
+   - 实现了验证码生成、存储和验证逻辑
+   - 在开发模式下，验证码会在控制台输出
+   - 支持使用万能验证码（默认为"123456"）用于测试
+
+4. **配置**
+   - 在`application.yml`中添加了验证码相关的配置
+   - 支持配置验证码过期时间、万能验证码和开发模式
+
+5. **安全配置**
+   - 更新了`SecurityConfig`以支持跨域请求
+   - 优化了安全配置结构
+
+## 使用说明
+
+1. 用户注册/登录流程：
+   - 用户输入邮箱或手机号，请求发送验证码
+   - 系统生成验证码，在开发模式下控制台会输出验证码
+   - 用户输入收到的验证码进行注册或登录
+
+2. 万能验证码：
+   - 在开发或测试环境中，可以使用配置的万能验证码（默认为"123456"）
+   - 无需等待验证码发送，直接使用万能验证码即可
+
+3. 配置说明：
+   ```yaml
+   app:
+     verification-code:
+       expiration: 300 # 验证码有效期（秒）
+       master-code: "123456" # 万能验证码
+       development-mode: true # 开发模式（控制台输出验证码）
+   ```
+
+## 注意事项
+
+1. 实际生产环境中，应使用Redis等缓存存储验证码，而非内存存储
+2. 需实现真实的短信和邮件发送服务来发送验证码
+3. 生产环境应禁用万能验证码和开发模式
+4. 当前实现为开发测试版本，注重功能实现，生产环境应加强安全性