# 聊天会话管理

## 相关源文件

- [ChatMessageAddRequest.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/chat/ChatMessageAddRequest.java)
- [ChatMessageQueryRequest.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/chat/ChatMessageQueryRequest.java)
- [ChatMessageVO.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/ChatMessageVO.java)
- [ChatSessionVO.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/ChatSessionVO.java)
- [UserAiAvatarVO.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/UserAiAvatarVO.java)
- [AiAvatarChatHistoryService.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/AiAvatarChatHistoryService.java)
- [DifyService.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/DifyService.java)
- [UserAiAvatarService.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/UserAiAvatarService.java)

## 目的与范围

本文档描述了 SmartClass 后端中的聊天会话管理系统。该子系统负责在用户和 AI 人物之间创建、维护和终止聊天会话，并存储和检索聊天消息历史记录。它涵盖了支持持久化对话的核心数据结构、API 和工作流程。

有关 AI 人物系统的详细信息，请参见 [AI 人物管理](https://deepwiki.com/Ubanillx/smartclass-backend/2.3-ai-avatar-management)。有关 Dify API 集成的详细信息，请参见 [Dify 集成](https://deepwiki.com/Ubanillx/smartclass-backend/2.1-dify-integration)，该集成提供了实际的 AI 回复。

来源：[AiAvatarChatHistoryService.java 16-142](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/AiAvatarChatHistoryService.java#L16-L142)

## 系统概述

聊天会话管理系统为用户提供了一种与 AI 人物进行持续对话的方式。每段对话都被组织成一个“会话”，其中包含用户和 AI 之间交换的消息的时间顺序序列。会话可以命名、检索并在多次用户交互中管理。

来源：[AiAvatarChatHistoryService.java 16-142](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/AiAvatarChatHistoryService.java#L16-L142) [DifyService.java 12-158](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/DifyService.java#L12-L158)

## 聊天会话数据模型

系统使用以下几种数据结构来表示聊天会话和消息：

来源：[ChatSessionVO.java 1-55](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/ChatSessionVO.java#L1-L55) [ChatMessageVO.java 1-75](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/ChatMessageVO.java#L1-L75)

## 会话生命周期管理

### 会话创建

当用户第一次与特定的 AI 人物互动时，会创建一个聊天会话。系统会创建一个新的会话或检索现有的会话。

数据库"AiAvatarChatHistoryService"控制器"用户"数据库"AiAvatarChatHistoryService"控制器"用户发送消息（无 sessionId）createNewSession(userId, aiAvatarId)生成并存储新的 sessionId返回 sessionId返回新的 sessionId返回后续消息的 sessionId"

来源：[AiAvatarChatHistoryService.java 29-37](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/AiAvatarChatHistoryService.java#L29-L37)

### 消息处理

当用户在会话中发送消息时，系统按如下方式处理：

外部数据库"DifyService""AiAvatarChatHistoryService"用户外部数据库"DifyService""AiAvatarChatHistoryService"用户saveMessage(userId, aiAvatarId, sessionId, "user", content)存储用户消息sendChatMessage() 或 sendChatMessageStreaming()调用 Dify API返回 AI 响应saveMessage(userId, aiAvatarId, sessionId, "ai", aiResponse)存储 AI 响应返回完整对话

来源：[AiAvatarChatHistoryService.java 18-28](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/AiAvatarChatHistoryService.java#L18-L28) [DifyService.java 14-57](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/DifyService.java#L14-L57)

### 会话检索与管理

系统提供以下几种方式来检索和管理聊天会话：

| 方法 | 目的 | 参数 |
|---|---|---|
| `getUserSessions` | 获取具有特定 AI 人物的所有用户会话 | userId, aiAvatarId |
| `getSessionHistory` | 获取特定会话中的所有消息 | sessionId |
| `getSessionHistoryPage` | 获取分页的会话消息 | sessionId, current, size |
| `updateSessionName` | 更改会话名称 | sessionId, sessionName |
| `getRecentSessions` | 获取用户的最近聊天会话 | userId, limit |
| `updateSessionSummary` | 更新会话摘要（通常是 AI 生成） | sessionId, summary |

来源：[AiAvatarChatHistoryService.java 39-131](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/AiAvatarChatHistoryService.java#L39-L131)

### 会话删除

会话可以通过两种方式删除：

1. **本地删除**：仅从本地数据库中移除会话记录
2. **完全删除**：同时移除本地记录和 Dify 上的对话历史

Dify API 数据库"DifyService""AiAvatarChatHistoryService"用户Dify API 数据库"DifyService""AiAvatarChatHistoryService"用户完全会话删除deleteSessionCompletely(sessionId, userId, baseUrl, avatarAuth)deleteSession(sessionId, userId)移除本地会话记录deleteConversation(userId, sessionId, baseUrl, avatarAuth)在 Dify 上删除对话确认删除返回结果删除结果

来源：[AiAvatarChatHistoryService.java 92-104](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/AiAvatarChatHistoryService.java#L92-L104) [DifyService.java 94-95](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/DifyService.java#L94-L95)

# 消息处理组件

## 消息请求与响应流程

系统使用不同的 DTO 来处理聊天消息操作：

来源：[ChatMessageAddRequest.java 1-45](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/chat/ChatMessageAddRequest.java#L1-L45) [ChatMessageQueryRequest.java 1-37](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/chat/ChatMessageQueryRequest.java#L1-L37)

## 请求参数

添加新消息时，使用以下参数：

| 参数 | 类型 | 描述 |
|---|---|---|
| `aiAvatarId` | Long | 聊天的 AI 人物 ID |
| `sessionId` | String | 会话 ID（可选 - 如果为空，则创建新会话） |
| `messageType` | String | 消息类型（"user" 或 "ai"） |
| `content` | String | 消息的文本内容 |
| `fileIds` | List<String> | 可选文件 ID 用于多模态对话 |
| `endChat` | boolean | 是否结束聊天并获取摘要 |

来源：[ChatMessageAddRequest.java 12-44](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/chat/ChatMessageAddRequest.java#L12-L44)

## 与 Dify API 的集成

聊天会话管理系统通过 `DifyService` 集成 Dify API。该服务负责：

1. **消息转发**：将用户消息发送到 Dify
2. **响应检索**：获取 AI 响应（包括阻塞和流模式）
3. **多模态支持**：处理带有图像/文件的消息
4. **会话管理**：在 Dify 上创建和删除会话

### 流式 vs 阻塞响应

系统支持两种与 Dify API 交互的模式：

Dify API "DifyService""AiAvatarChatHistoryService"客户端Dify API "DifyService""AiAvatarChatHistoryService"客户端循环[对于每个响应块]alt[阻塞模式][流式模式]发送消息sendChatMessage()完整请求等待完整响应返回完整响应发送完整响应发送消息sendChatMessageStreaming()流式请求流式响应块通过回调处理块流式传输到客户端

来源：[DifyService.java 24-74](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/DifyService.java#L24-L74) [DifyService.java 138-157](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/DifyService.java#L138-L157)

## 常见使用模式

### 开始新对话

1. 客户端发送一个没有 `sessionId` 的新消息
2. 系统创建一个新会话
3. 处理消息并获得 AI 回复
4. 两条消息都存储在会话历史中
5. 客户端收到新的 `sessionId` 以继续对话

### 继续现有对话

1. 客户端发送带有现有 `sessionId` 的消息
2. 系统检索会话
3. 处理消息并获得 AI 回复
4. 两条消息都添加到现有会话历史中
5. 客户端收到更新后的对话

### 管理会话

客户端可以：

- 检索所有会话列表
- 重命名会话以便更好地组织
- 获取会话历史
- 在不再需要时删除会话

## 性能考虑

聊天会话管理系统在所有列表检索方法中实现分页，以确保在处理大量聊天会话或消息时具有良好的性能。`getSessionHistoryPage` 和 `getUserHistoryPage` 方法专门支持对聊天历史的分页访问。

来源：[AiAvatarChatHistoryService.java 56-75](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/AiAvatarChatHistoryService.java#L56-L75)

## 相关服务

### 用户 AI 人物服务

`UserAiAvatarService` 跟踪用户和 AI 人物之间的关系，包括：

- 用户使用了哪些人物
- 用户喜欢的人物
- 使用次数和评分

该服务与聊天会话管理系统紧密协作，以提供个性化的聊天体验。

来源：[UserAiAvatarService.java 16-60](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/UserAiAvatarService.java#L16-L60)