本篇纪实将介绍我们在项目中编写的后端模型接口方法（AI相关）

---

一、实体类型介绍

在本章节中，我们主要介绍系统中用于构建 AI 聊天功能的两大核心数据实体 —— ChatSession 与 ChatMessage。它们分别承担了“会话管理”与“消息存储”的职责，构成整个对话记录模块的基础。

---

✅ 1. ChatSession：聊天会话实体

该实体类用于表示一次完整的聊天会话，包含了会话的标题、所属用户、创建与更新时间等信息。每一个会话下可包含多条用户与 AI 的消息记录。

字段名	说明	示例
id	会话主键 ID	1001
title	会话标题	"与GPT的早间对话"
userId	所属用户 ID	1024
createTime	会话创建时间	2024-06-01 09:30:00
updateTime	会话最后更新时间	2024-06-01 10:12:05
isDelete	逻辑删除标志	0（正常）或 1（删除）

📌 说明：系统支持用户多轮对话，每个会话都可以命名与独立管理。通过 userId 进行归属绑定，确保数据隔离。

---

✅ 2. ChatMessage：聊天消息实体

该实体类用于记录一次对话中的一条具体消息，包含角色（如用户或 AI）、消息内容、所属会话 ID 及时间信息。

字段名	说明	示例
id	消息主键 ID	8888
sessionId	所属会话 ID（外键）	1001
role	消息角色（user / assistant）	"user" / "assistant"
content	消息内容文本	"请帮我写一段Java代码"
createTime	消息发送时间	2024-06-01 09:31:22
updateTime	更新时间（一般无需手动改）	2024-06-01 09:31:22
isDelete	是否逻辑删除	0 / 1

💡 说明：通过 sessionId 实现消息与会话的一对多关联关系，系统可根据会话 ID 快速获取完整消息列表，支持上下文连续性处理。

二、Mapper介绍

ChatMessageMapper 和 ChatSessionMapper 分别对应 ChatMessage 和 ChatSession 实体类的数据访问层接口，均继承自 MyBatis-Plus 提供的 BaseMapper。通过继承 BaseMapper，这两个接口无需手动编写 SQL，即可拥有常用的增删改查能力（如 insert、selectById、updateById 等）。它们作为持久层的核心桥梁，负责将聊天消息和会话数据与数据库进行高效交互，简化了开发流程并提高了代码的可维护性。

三、Service介绍

在聊天模块的业务核心中，ChatServiceImpl 作为服务实现类，负责管理会话的创建、删除、重命名、历史记录查询与 AI 消息生成等关键功能。该类继承自 ServiceImpl<ChatSessionMapper, ChatSession>，并实现了 ChatService 接口，是业务逻辑与数据库交互之间的重要桥梁。

1. 会话管理功能

• getSessionList(Long userId)：根据用户 ID 查询其所有未删除的会话记录，并按更新时间降序排列，用于首页展示会话列表。

• createSession(Long userId)：创建一个默认标题为“新会话”的聊天会话。方法加上了 @Transactional 注解，确保在保存失败时事务回滚，保障数据一致性。

• deleteSession(Long sessionId, Long userId)：删除指定的会话，同时清除该会话下的所有消息。为确保用户只能删除自己的会话，删除前会进行用户身份校验。

• renameSession(Long sessionId, Long userId, String newTitle)：支持用户自定义修改会话标题。该操作需验证权限并更新数据库记录。

2. 消息记录功能

• getHistory(Long sessionId, Long userId)：返回指定会话下按时间正序排列的全部消息内容。会话访问前会校验是否属于当前用户。

• sendMessage(Long sessionId, Long userId, String content)：用户发送消息后，系统将先保存用户消息，再调用 AI 模型生成回复，并同步保存 AI 回复信息。方法同样使用事务控制，确保过程中任一环节失败都可完整回滚。

3. AI 模型调用逻辑

为了支持 AI 自动回复，系统集成了多种模型接口，分别用于不同场景下的调用：

• callDeepSeekApi：调用阿里云提供的 DeepSeek 模型（deepseek-r1-distill-qwen-7b），传入用户输入后生成自然语言回复。此方法主要用于生产环境中的快速响应场景。

• callOfficialDeepSeekApi：调用 DeepSeek 官方提供的 HTTP 接口，通过构造标准 OpenAI 格式的 messages 实现对 deepseek-chat 或 deepseek-reasoner 模型的调用，适用于结构化对话需求。

• callOllamaApi：支持与本地部署的 LLM（如 Ollama）进行通信，作为轻量级替代方案存在。若云服务不可用，该接口能提供兜底支持。

4. 异常与日志处理

所有服务方法均配合 BusinessException 和 ErrorCode 使用，确保在业务异常发生时给予前端明确的反馈。同时，关键步骤都配有详细日志记录（log.info），方便开发者在部署或运行时进行调试和问题追踪。

四、Controller介绍

本模块主要包含两个控制器类，分别为 ChatController 与 AiController，分别用于管理用户的聊天会话交互以及提供智能判题辅助服务。控制器层承担前后端接口桥梁的职责，完成参数校验、用户权限验证与业务服务调用等关键流程。

ChatController 聊天控制器

ChatController 提供了完整的用户聊天交互管理接口，包括：

• 获取会话列表 /chat/sessions：根据当前登录用户 ID 查询其所有历史会话，并按照更新时间倒序排列，便于用户快速查看最近对话。

• 创建会话 /chat/session/create：为当前用户新建一个标题为“新会话”的空对话，初始化后续对话内容。

• 删除会话 /chat/session/delete：在确认用户身份基础上删除对应会话数据，并一并清除会话下所有消息记录。

• 获取历史消息 /chat/history：返回某个会话的历史消息记录，按创建时间正序排列，支持聊天窗口回显。

• 发送消息 /chat：接收用户输入内容并保存，同时调用大模型接口生成 AI 回复并落库保存，最终返回回复内容。

• 修改会话名 /chat/session/rename：允许用户为已有会话自定义标题，便于分类管理。

• 题目结构分析 /chat/question-analyse：结合 LLM 模型能力，分析题目的简化描述与数学模型，输出结构化内容用于进一步处理。

该控制器严格校验用户身份与参数合法性，通过调用 ChatService 中封装的具体业务逻辑，确保操作的原子性与一致性。

---

AiController 智能分析控制器

AiController 控制器聚焦于判题相关的智能增强功能，依托于大模型的推理与文本生成能力，主要提供以下几个接口：

• 题目简化 /ai/question-simplify：接收完整题目内容，通过构造合适提示词（Prompt）调用模型，使其去除冗余背景，仅保留核心要点。

• 数学建模描述 /ai/question-math-model：进一步抽象题目逻辑结构，生成简洁数学语言表述，帮助用户理解建模方向。

• 评测分析 /ai/judge-analysis：根据某次提交 ID，结合原题内容、用户代码与评测反馈，让大模型分析本次提交失败原因并给出优化建议。

• 代码修复 /ai/code-fix：用户上传错误代码与原题描述后，模型直接输出修复后的完整代码，不含解释说明，便于直接测试。

该控制器聚焦服务“判题结果解释”和“编程智能改错”两个典型使用场景，帮助学生提升编程效率，降低理解成本。

五、接口文档

ChatController 接口文档

接口名称	请求方式	接口路径	描述	请求参数/体	返回值说明
获取会话列表	GET	/chat/sessions	获取当前用户的会话列表	无（从 session 获取用户信息）	List<ChatSession>，按更新时间倒序排序
创建会话	POST	/chat/session/create	创建一个新的会话	无（从 session 获取用户信息）	ChatSession 对象，包含会话 ID、标题、创建时间等
删除会话	POST	/chat/session/delete	删除会话及其所有消息	sessionId：Long，作为请求参数	是否成功（Boolean）
获取历史记录	GET	/chat/history	获取某个会话的消息历史	sessionId：Long，作为请求参数	List<ChatMessage>，包括每条消息的角色、内容、时间等
发送消息	POST	/chat	发送用户消息，获取 AI 回复	sessionId：String，message：String，context（可选）	AI 回复文本（String）
修改会话名称	POST	/chat/session/rename	修改指定会话的标题	sessionId：Long，newTitle：String	是否成功（Boolean）
题目简析	POST	/chat/question-analyse	简化题目描述并生成数学模型	content：String（题目内容）	simplifiedDescription：简化描述，mathModel：数学建模

AiController 接口文档

接口名称	请求方式	接口路径	描述	请求参数/体	返回值说明
简化题目内容	POST	/ai/question-simplify	对题目内容进行简化，去除冗余背景信息	content：String（题目原始描述）	Map<String, String>，键为 "result"，值为简化后的题面
提取数学模型	POST	/ai/question-math-model	分析题目中的数学模型	content：String（题目原始描述）	Map<String, String>，键为 "result"，值为分析得到的数学模型
判题结果分析	POST	/ai/judge-analysis	分析某次代码提交的评测信息，诊断问题	submitId：Long	Map<String, String>，键为 "result"，值为模型生成的诊断反馈
修复用户代码	POST	/ai/code-fix	根据题目与原始代码自动修复并返回新代码	questionContent：String，code：String	Map<String, String>，键为 "fixedCode"，值为修复后的代码（无代码框格式）