backend/README.md

# 智能问答聊天系统 (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 <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自动化测试
- 性能测试实施

---

**总结**: 这是一个架构清晰、功能完整的智能问答聊天系统。通过详细的文档和代码注释，为后续的开发和维护提供了良好的基础。项目采用了现代化的技术栈，具有良好的扩展性和可维护性。