第十五章：数据模型

15 - 数据模型

一、Entity 持久化对象

1.1 AiSession（会话表）

entity/AiSession.java → ai_session

字段	类型	字段名	说明
id	Long	id	主键（ASSIGN_ID）
sessionId	String	session_id	会话业务 ID
agentType	String	agent_type	websearch/file/pptx/plan-execute/skills
question	String	question	用户问题
answer	String	answer	AI 回复
tools	String	tools	使用的工具（逗号分隔）
reference	String	reference	参考链接 JSON
firstResponseTime	Long	first_response_time	首字响应时间（ms）
totalResponseTime	Long	total_response_time	总响应时间（ms）
createTime	LocalDateTime	create_time	创建时间
updateTime	LocalDateTime	update_time	更新时间
thinking	String	thinking	思考过程
fileid	String	fileid	关联文件 ID
recommend	String	recommend	推荐问题 JSON

Service：AiSessionService / AiSessionServiceImpl

Mapper：AiSessionMapper (含 selectSessionListWithFirstRecord)

1.2 AiFileInfo（文件信息表）

entity/AiFileInfo.java → ai_file_info

与 FileInfo 业务模型的区别：

• AiFileInfo：MyBatis-Plus 实体，对应数据库表
• entity/record/FileInfo：业务模型（FileManageService 使用）

1.3 AiPptInst（PPT 实例表）

entity/record/pptx/AiPptInst.java → ai_ppt_inst

字段	类型	字段名	说明
id	Long	id	主键
conversationId	String	conversation_id	会话 ID
templateCode	String	template_code	模板编码
status	String	status	当前状态（字符串）
query	String	query	用户原始需求
requirement	String	requirement	需求澄清结果
searchInfo	String	search_info	搜索结果
outline	String	outline	PPT 大纲
pptSchema	String	ppt_schema	最终 Schema JSON
fileUrl	String	file_url	渲染后的 PPT URL
errorMsg	String	error_msg	错误信息（用于断点重连）
createTime	LocalDateTime	create_time	创建时间
updateTime	LocalDateTime	update_time	更新时间

方法：getStatusEnum() / setStatusEnum(PptInstStatus) 用于状态枚举转换

Service：AiPptInstService

1.4 AiPptTemplate（PPT 模板表）

entity/record/pptx/AiPptTemplate.java → ai_ppt_template

字段	类型	说明
templateCode	String	模板编码（业务唯一）
templateName	String	模板名称
templateSchema	String	模板 Schema JSON（定义字段）

Service：AiPptTemplateService

二、Record 业务模型

2.1 FileInfo

entity/record/FileInfo.java：

@Data @Builder
public class FileInfo {
    private String fileId;
    private String fileName;
    private String fileType;
    private Long fileSize;
    private String minioPath;
    private String extractedText;     // 解析后的文本
    private LocalDateTime createdAt;
    private String conversationId;
    private FileStatus status;        // PENDING/PROCESSING/SUCCESS/FAILED
    private Integer embed;            // 0=未向量化, 1=已向量化

    public enum FileStatus { PENDING, PROCESSING, SUCCESS, FAILED }

    public boolean isProcessed();
    public boolean isImage();
    public boolean isPdf();
    public boolean isWord();
}

2.2 RoundState / RoundMode（轮次状态）

entity/record/RoundState.java / RoundMode.java：

public class RoundState {
    public RoundMode mode = RoundMode.TEXT;  // TEXT or TOOL_CALL
    public List<AssistantMessage.ToolCall> toolCalls = new ArrayList<>();
    public StringBuilder textBuffer = new StringBuilder();
    public boolean inThink = false;  // 当前是否在 <think> 标签内
}

public enum RoundMode { TEXT, TOOL_CALL }

使用场景：WebSearch / File / Skills Agent 的 ReAct 循环

2.3 AgentState

entity/record/AgentState.java：

public class AgentState {
    public List<SearchResult> searchResults = new ArrayList<>();
}

使用场景：在 ReAct 循环中收集所有搜索结果，最终输出 reference

2.4 SearchResult

entity/record/SearchResult.java：

public record SearchResult(String url, String title, String content) {}

2.5 SimpleReactResult / ReactAgentResult / TaskResult

entity/record/SimpleReactResult.java / ReactAgentResult.java / TaskResult.java

• Plan-Execute 阶段结果模型

2.6 PlanTask

entity/record/PlanTask.java - 计划任务

2.7 CritiqueResult

entity/record/CritiqueResult.java - 批判反思结果

2.8 TemplateSelectionResult

entity/record/TemplateSelectionResult.java - 模板选择结果

三、PPT 业务模型

entity/record/pptx/ 目录下的 PPT 专用模型：

3.1 PptInstStatus（PPT 状态枚举）

public enum PptInstStatus {
    INIT("INIT", "初始化"),
    REQUIREMENT("REQUIREMENT", "需求澄清"),
    SEARCH("SEARCH", "信息收集"),
    OUTLINE("OUTLINE", "大纲生成"),
    TEMPLATE("TEMPLATE", "模板选择"),
    SCHEMA("SCHEMA", "Schema生成"),
    RENDER("RENDER", "PPT渲染"),
    SUCCESS("SUCCESS", "完成"),
    FAILED("FAILED", "失败");

    public static PptInstStatus fromCode(String code);
}

3.2 PptSchema（PPT 结构化 Schema）

entity/record/pptx/PptSchema.java：

{
  "title": "PPT 标题",
  "slides": [
    {
      "type": "cover",       // 幻灯片类型
      "title": "...",
      "data": {
        "background": {
          "type": "background",
          "url": "...",       // MinIO URL
          "content": "..."    // 配图提示词
        },
        "title": {
          "type": "text",
          "content": "..."
        }
      }
    }
  ]
}

3.3 Slide / FieldData

public class Slide {
    private String type;     // 幻灯片类型
    private String title;
    private Map<String, FieldData> data;
}

public class FieldData {
    private String type;     // text/image/background/chart
    private String content;  // 文本内容或图片提示词
    private String url;      // 图片 URL
}

3.4 PptIntent / PptIntentResult

public enum PptIntent {
    CREATE_PPT,    // 新建
    MODIFY_PPT,    // 修改
    RESUME_PPT     // 断点续传
}

public record PptIntentResult(PptIntent intent, String reason) {}

3.5 PptPageType

entity/record/pptx/PptPageType.java - PPT 页面类型枚举

四、Event 事件对象

entity/event/ 目录：

4.1 AgentStreamEvent

entity/event/AgentStreamEvent.java：

public class AgentStreamEvent {
    public enum Type {
        THINKING,    // 思考
        TEXT,        // 正文
        TOOL_START,  // 工具开始
        TOOL_END,    // 工具结束
        ERROR,       // 错误
        COMPLETE     // 完成
    }

    private Type type;
    private String content;
    private String toolName;     // 工具相关字段
    private Map<String, Object> metadata;
}

使用场景：SkillsReactAgent 输出 6 类事件

4.2 ToolRecord

entity/event/ToolRecord.java - 工具调用记录：

public class ToolRecord {
    private String toolName;
    private String args;
    private String result;
    private long startTime;
    private long endTime;
    private boolean success;
}

五、VO 视图对象

entity/vo/ 目录 - Controller 响应模型：

5.1 MessageVO

entity/vo/MessageVO.java：

public class MessageVO {
    private Long id;
    private String question;
    private String answer;
    private String thinking;
    private String tools;
    private String reference;
    private LocalDateTime createTime;
    private String fileid;
    private String recommend;
}

5.2 SessionListVO / SessionDetailVO / PageResult

entity/vo/SessionListVO.java - 会话列表项
entity/vo/SessionDetailVO.java - 会话详情

public class SessionDetailVO {
    private String conversationId;
    private String agentType;
    private String fileid;
    private List<MessageVO> messages;
}

public class PageResult<T> {
    private Integer pageNum;
    private Integer pageSize;
    private Long total;
    private List<T> records;
}

5.3 SaveQuestionRequest / UpdateAnswerRequest

entity/vo/SaveQuestionRequest.java：

public class SaveQuestionRequest {
    private String sessionId;
    private String question;
    private String fileid;
    private String tools;
    private Long firstResponseTime;
}

entity/vo/UpdateAnswerRequest.java：

public class UpdateAnswerRequest {
    private Long id;
    private String answer;
    private String thinking;
    private String tools;
    private String reference;
    private String recommend;
    private Long firstResponseTime;
    private Long totalResponseTime;
}

六、OverAllState

entity/OverAllState.java：

@Data
public class OverAllState {
    private final String conversationId;
    private final String question;
    private final List<Message> messages = new ArrayList<>();
    private int round = 0;
    private String refinedResearchTopic;

    public int currentChars();
    public void clearMessages();
    public String renderFullContext();  // 渲染完整上下文
    public String extractToolResults(); // 提取工具结果
    public String getLastCritique();    // 获取最近批判
}

使用场景：PlanExecuteAgent 的全局状态管理

七、SlideImage

entity/SlideImage.java - 幻灯片图片

八、Common 通用类

8.1 BaseResult

common/BaseResult.java - 统一响应：

public class BaseResult<T> {
    private Integer code;
    private Boolean success;
    private String message;
    private T data;

    public static <T> BaseResult<T> newSuccess(T data);
    public static <T> BaseResult<T> newError(String message);
    public static <T> BaseResult<T> fail(int code, String message);
}

8.2 AgentResponse

common/AgentResponse.java - SSE 响应工厂（详见 03 智能体框架）

8.3 ImageProvider

common/ImageProvider.java - 图片提供者接口

九、Mapper（MyBatis）

mapper/ 目录：

Mapper	对应表	方法
AiSessionMapper	ai_session	selectSessionListWithFirstRecord
AiFileInfoMapper	ai_file_info	MyBatis-Plus 基础 CRUD
AiPptInstMapper	ai_ppt_inst	MyBatis-Plus 基础 CRUD
AiPptTemplateMapper	ai_ppt_template	MyBatis-Plus 基础 CRUD

十、SQL 脚本

sql/ 目录包含数据库初始化脚本。

十一、ER 关系图

┌──────────────┐
│  ai_session  │
├──────────────┤
│ id (PK)      │
│ session_id   │  ←── 会话 ID（与 conversationId 同义）
│ agent_type   │
│ question     │
│ answer       │
│ fileid (FK)──┼──→┌──────────────┐
│ ...          │   │ ai_file_info │
└──────────────┘   ├──────────────┤
                   │ fileid (PK)  │
                   │ ...          │
                   └──────────────┘

┌──────────────┐
│ ai_ppt_inst  │
├──────────────┤
│ id (PK)      │
│ conversation_id (与 sessionId 同义)
│ template_code (FK)──→┌────────────────────┐
│ status      │        │ ai_ppt_template    │
│ ppt_schema  │        ├────────────────────┤
│ file_url    │        │ template_code (PK) │
│ error_msg   │        │ template_name      │
│ ...         │        │ template_schema    │
└──────────────┘        └────────────────────┘

注：ai_session.fileid 与 ai_file_info.fileid 通过业务层关联（没有数据库外键约束）