交接文档
This commit is contained in:
yahaozhang
168
交接文档.md
Normal file
168
交接文档.md
Normal file
@@ -0,0 +1,168 @@
|
|||||||
|
# 云大智能问答系统 - 项目交接文档
|
||||||
|
|
||||||
|
## 项目概述
|
||||||
|
|
||||||
|
云大智能问答系统(backserver)是一个基于Spring Boot 3.2.4的后端服务，主要功能是提供智能问答和深度研究服务。系统采用前后端分离架构，支持用户注册、登录、聊天会话管理和AI问答等功能。
|
||||||
|
|
||||||
|
### 技术栈
|
||||||
|
- **框架**: Spring Boot 3.2.4 + Spring Security + Spring AI
|
||||||
|
- **数据层**: MyBatis-Flex + MySQL
|
||||||
|
- **认证**: JWT Token
|
||||||
|
- **AI集成**: Spring AI OpenAI (使用GPT-4o-mini模型)
|
||||||
|
- **文档**: SpringDoc OpenAPI 3.0 + Swagger UI
|
||||||
|
- **构建工具**: Maven
|
||||||
|
|
||||||
|
## 已实现功能
|
||||||
|
|
||||||
|
### 1. 用户认证模块 (`com.yundage.chat.controller.AuthController`)
|
||||||
|
- **用户注册**: 支持邮箱验证码注册
|
||||||
|
- **用户登录**: JWT Token认证
|
||||||
|
- **密码重置**: 邮件验证码重置密码
|
||||||
|
- **登录状态检查**: 验证用户登录状态
|
||||||
|
|
||||||
|
**核心文件**:
|
||||||
|
- `src/main/java/com/yundage/chat/controller/AuthController.java`
|
||||||
|
- `src/main/java/com/yundage/chat/service/UserService.java`
|
||||||
|
- `src/main/java/com/yundage/chat/util/JwtUtil.java`
|
||||||
|
|
||||||
|
### 2. 智能问答模块 (`com.yundage.chat.controller.ChatController`)
|
||||||
|
- **智能问答**: `/qa/ask` - 支持普通聊天和深度研究两种模式
|
||||||
|
- **流式输出**: `/qa/ask/stream` - 支持Server-Sent Events的流式回复
|
||||||
|
- **会话管理**: 获取用户会话列表和消息历史
|
||||||
|
|
||||||
|
**功能特点**:
|
||||||
|
- 支持两种问答模式: `chat`(普通聊天) 和 `research`(深度研究)
|
||||||
|
- 会话持久化存储
|
||||||
|
- 消息序列化管理
|
||||||
|
- Token使用统计
|
||||||
|
|
||||||
|
**核心文件**:
|
||||||
|
- `src/main/java/com/yundage/chat/controller/ChatController.java:24`
|
||||||
|
- `src/main/java/com/yundage/chat/service/ChatService.java:30`
|
||||||
|
- `src/main/java/com/yundage/chat/dto/ChatRequest.java`
|
||||||
|
- `src/main/java/com/yundage/chat/dto/ChatResponse.java`
|
||||||
|
|
||||||
|
### 3. 用户管理模块 (`com.yundage.chat.controller.UserController`)
|
||||||
|
- **个人信息**: 获取和更新用户基本信息
|
||||||
|
- **用户类型**: 支持普通用户和高级用户类型
|
||||||
|
|
||||||
|
### 4. 数据模型
|
||||||
|
- **User**: 用户信息表，包含认证提供商、用户类型等字段
|
||||||
|
- **Conversation**: 会话表，支持不同聊天模式
|
||||||
|
- **Message**: 消息表，支持用户和助手消息
|
||||||
|
- **PasswordResetToken**: 密码重置令牌表
|
||||||
|
|
||||||
|
## 数据库配置
|
||||||
|
|
||||||
|
当前使用MySQL数据库，连接信息在 `application.yml:4` 中配置:
|
||||||
|
```yaml
|
||||||
|
spring:
|
||||||
|
datasource:
|
||||||
|
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||||
|
url: jdbc:mysql://101.200.154.78:3306/yunda_qa
|
||||||
|
username: root
|
||||||
|
password: mysql_Jt3yzh
|
||||||
|
```
|
||||||
|
|
||||||
|
## AI模型配置
|
||||||
|
|
||||||
|
当前使用第三方OpenAI API服务，配置在 `application.yml:20-26`:
|
||||||
|
```yaml
|
||||||
|
spring:
|
||||||
|
ai:
|
||||||
|
openai:
|
||||||
|
api-key: sk-5gAxnpuwJ9KIsea51cD05e21F1Ac4b6a99C8A97278C1F837
|
||||||
|
base-url: https://www.jzhengda-api.com
|
||||||
|
chat:
|
||||||
|
options:
|
||||||
|
model: gpt-4o-mini
|
||||||
|
```
|
||||||
|
|
||||||
|
## 需要优化的部分
|
||||||
|
|
||||||
|
### 1. 🔴 Token管理优化 (高优先级)
|
||||||
|
|
||||||
|
**现状问题**:
|
||||||
|
- JWT Token存储在内存中，无法跨实例共享
|
||||||
|
- 缺乏Token黑名单机制
|
||||||
|
- 无法实现用户强制下线功能
|
||||||
|
|
||||||
|
**建议方案**:
|
||||||
|
```xml
|
||||||
|
<!-- 在pom.xml中添加Redis依赖 -->
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.springframework.boot</groupId>
|
||||||
|
<artifactId>spring-boot-starter-data-redis</artifactId>
|
||||||
|
</dependency>
|
||||||
|
```
|
||||||
|
|
||||||
|
**需要修改的文件**:
|
||||||
|
- `src/main/java/com/yundage/chat/util/JwtUtil.java:39` - 添加Redis Token存储
|
||||||
|
- `src/main/java/com/yundage/chat/config/JwtAuthenticationFilter.java` - 增加Token验证逻辑
|
||||||
|
- `application.yml` - 添加Redis配置
|
||||||
|
|
||||||
|
### 2. 🟡 AI响应优化 (中优先级)
|
||||||
|
|
||||||
|
**现状问题**:
|
||||||
|
- `ChatService.java:234-238` 中AI响应生成逻辑过于简单
|
||||||
|
- 缺乏错误重试机制
|
||||||
|
- Token统计不准确
|
||||||
|
|
||||||
|
**需要改进**:
|
||||||
|
- 完善AI响应生成逻辑
|
||||||
|
- 添加响应缓存机制
|
||||||
|
- 实现更精确的Token计算
|
||||||
|
|
||||||
|
### 3. 🟡 数据库连接池优化 (中优先级)
|
||||||
|
|
||||||
|
**建议**:
|
||||||
|
- 配置HikariCP连接池参数
|
||||||
|
- 添加数据库连接监控
|
||||||
|
- 实现读写分离
|
||||||
|
|
||||||
|
### 4. 🟢 邮件服务配置 (低优先级)
|
||||||
|
|
||||||
|
**现状**: `application.yml:8-19` 中邮件配置使用的是示例配置
|
||||||
|
**需要**: 配置真实的SMTP服务
|
||||||
|
|
||||||
|
### 5. 🟢 日志和监控 (低优先级)
|
||||||
|
|
||||||
|
**建议**:
|
||||||
|
- 添加业务日志记录
|
||||||
|
- 集成APM监控
|
||||||
|
- 添加健康检查端点
|
||||||
|
|
||||||
|
## API接口文档
|
||||||
|
|
||||||
|
系统已集成Swagger UI，可通过以下地址访问:
|
||||||
|
- Swagger UI: `http://localhost:8080/swagger-ui.html`
|
||||||
|
- OpenAPI文档: `http://localhost:8080/api-docs`
|
||||||
|
|
||||||
|
详细的接口设计说明请参考 `docs/chat.md`
|
||||||
|
|
||||||
|
## 部署信息
|
||||||
|
|
||||||
|
项目包含Docker配置:
|
||||||
|
- `Dockerfile` - 容器化配置
|
||||||
|
- `docker-compose.yml` - 本地开发环境
|
||||||
|
- `deploy.sh` - 部署脚本
|
||||||
|
|
||||||
|
## 开发环境启动
|
||||||
|
|
||||||
|
1. 确保MySQL服务运行
|
||||||
|
2. 配置 `application.yml` 中的数据库连接
|
||||||
|
3. 运行 `mvn spring-boot:run` 启动服务
|
||||||
|
4. 访问 `http://localhost:8080/swagger-ui.html` 查看API文档
|
||||||
|
|
||||||
|
## 安全注意事项
|
||||||
|
|
||||||
|
⚠️ **重要**: 当前配置中包含敏感信息，生产环境需要:
|
||||||
|
- 使用环境变量替换硬编码的密码和API密钥
|
||||||
|
- 更新JWT密钥为更安全的值
|
||||||
|
- 配置HTTPS访问
|
||||||
|
- 限制数据库访问权限
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*文档生成时间: 2025-07-28*
|
||||||
|
*当前版本: 0.0.1-SNAPSHOT*
|
||||||
Reference in New Issue
Block a user