今日工作日报｜2026-06-25#

一、今日主要工作#

围绕门户智能助手历史会话功能，完成需求分析、数据存储方案设计和开发实施计划制定。
完成历史会话数据库表、后端 Entity、Mapper、DTO、Service、Controller 以及前端消息保存与历史加载逻辑的开发。
解决历史消息加载时序和欢迎卡片重复保存问题，保证页面刷新后能够正确恢复最近会话。
完成接口验证、页面功能测试和多分支代码推送，并沉淀《历史会话功能开发计划》和《历史会话功能开发文档》。

二、核心完成内容#

1. 需求分析与开发计划制定#

梳理门户智能助手历史会话需求，明确供应能力查询、订单交付查询、订单关注、供应风险预警和交付流程咨询等 AI 交互均需要自动保存。
明确页面重新打开或刷新后展示最近 50 条对话，后端每个用户最多保留 100 条记录。
制定按用户隔离的会话存储方案，使用当前门户用户 ID 作为数据归属标识，避免不同用户之间出现历史消息串联。
将功能开发拆分为数据库建表、后端基础对象开发、业务服务实现、接口开发、前端接入和测试验证等步骤，形成可执行的开发计划。

2. 数据库与存储策略设计#

在 zhineng_ai 库中设计并创建 portal_conversation_history 历史会话表。
表结构包含用户 ID、消息角色、消息内容、功能模块编码、功能模块名称和创建时间等字段。
使用 MEDIUMTEXT 存储消息内容，支持直接保存机器人回复的 HTML 内容，减少历史消息恢复时的二次构造。
新增 idx_user_time (sys_user_id, created_at DESC) 联合索引，支撑按用户和时间倒序查询最近会话。
设计以下数据保留策略：
- 前端每次最多加载最近 50 条记录；
- 后端每个用户最多保留 100 条记录；
- 新消息插入后检查记录数量，超过上限时清理最旧记录；
- 历史保存或清理失败不影响用户当前 AI 交互主流程。
沉淀建表脚本 portal_conversation_history.mysql.sql，便于测试环境和生产环境部署。

3. 后端基础代码开发#

3.1 Entity、DTO 与 Mapper#

新增 PortalConversationHistory 实体类，完成数据库字段与 Java 对象的映射。
新增 ConversationHistoryRequest 请求 DTO，用于接收消息角色、内容、模块编码和模块名称。
新增 PortalConversationHistoryMapper，继承 MyBatis-Plus BaseMapper，复用基础增删改查能力。
在 Mapper 中增加最旧记录 ID 查询方法，为超出上限后的历史数据清理提供支持。

3.2 Service 业务逻辑#

新增 PortalConversationHistoryService，实现历史消息保存、最近记录查询和超限清理功能。
保存消息时自动写入当前用户 ID、消息角色、HTML 内容、模块信息和创建时间。
使用 Portal 数据源事务管理器保障历史消息写入的一致性。
查询历史时按当前用户和创建时间倒序获取记录，并将接口最大返回条数限制为 50。
在消息保存后触发记录数量检查，超过 100 条时删除最旧记录，控制单用户数据规模。
对历史保存和清理流程进行容错处理，避免辅助功能异常阻塞供应能力查询等核心业务。

3.3 Controller 接口开发#

新增历史会话 REST Controller，对外提供消息保存和历史查询接口。
新增消息保存接口：

1
POST /api/portal/conversation-history

新增历史查询接口：

1
GET /api/portal/conversation-history?limit=50

接口通过门户 JWT 获取当前用户身份，后端不依赖前端传递用户 ID，保证用户数据隔离的可靠性。
保持接口职责清晰：POST 负责保存单条消息，GET 负责查询当前用户最近会话。

4. 前端历史会话功能接入#

4.1 自动保存用户和助手消息#

在 app.js 中新增历史会话接口地址和 saveConversationHistory 方法。
在 addUserMessage 中接入保存逻辑，用户发送消息后自动以 user 角色记录。
在 addBotMessage 中接入保存逻辑，机器人回复渲染后自动以 bot 角色记录。
自动记录当前功能模块的编码和名称，便于后续区分供应能力查询、订单交付查询、供应风险预警等消息来源。
保存失败时仅记录异常，不影响当前消息展示和用户操作。

4.2 页面加载历史记录#

新增 loadConversationHistory 方法，页面初始化时调用历史查询接口加载最近 50 条记录。
后端返回结果按时间倒序排列，前端通过反向遍历恢复为正常对话顺序。
用户消息按照用户气泡样式渲染，机器人消息使用已保存的 HTML 内容恢复。
机器人历史内容在写入页面前继续经过 HTML 清洗，降低直接渲染历史 HTML 的安全风险。
历史加载完成后自动滚动到会话底部，使用户能够直接查看最近一轮交互。

5. 功能问题排查与修复#

5.1 历史加载时序问题#

问题现象：刷新页面后，历史消息可能未正常显示或被后续页面初始化内容覆盖。
根因分析：loadConversationHistory() 未被 await，历史加载与欢迎页面渲染同时执行，产生异步竞态。
修复方式：将页面初始化方法调整为异步流程，并在后续角色卡片和欢迎内容渲染前执行 await loadConversationHistory()。
修复结果：历史消息加载完成后才继续执行页面初始化，避免刷新后历史内容被覆盖。

5.2 欢迎卡片误存问题#

问题现象：欢迎卡片被当作普通机器人消息保存，刷新页面后重复出现。
修复方式：在机器人消息保存前判断 extraClass，当消息类型为 msg-bubble--welcome 时跳过历史保存。
修复结果：欢迎卡片仅作为当前页面引导内容展示，不进入用户历史会话记录。

6. 功能覆盖与测试验证#

历史会话保存能力已覆盖所有通过 addUserMessage 和 addBotMessage 渲染的门户 AI 功能，包括：
- 供应能力查询；
- 订单交付查询；
- 交付文件查询；
- 设备配置查询；
- 供应风险预警；
- 交付流程咨询；
- 未发订单查询；
- 订单关注；
- Agent 通用回复。
对消息保存接口和历史查询接口进行调用验证，确认接口能够正常写入和返回记录。
在门户页面执行多次功能查询后刷新页面，验证最近历史消息能够按照正常时间顺序恢复。
验证欢迎卡片不会被重复保存和重复展示。
验证不同用户登录后仅能看到自己的历史会话，用户数据隔离正常。
验证单用户记录超过保留上限后的旧数据清理逻辑。
完成测试库建表，并将代码推送至 sit、supply-demand-iteration 和 supply-demand-iteration-merge 分支。
生产环境数据库建表脚本已准备，等待后续部署时执行。

三、今日工作产出#

完成《门户智能助手—历史会话功能开发计划》。
完成 portal_conversation_history 数据库表设计及 DDL 脚本。
新增历史会话 Entity、Mapper、请求 DTO、Service 和 Controller。
新增历史消息保存与最近 50 条记录查询接口。
完成前端用户消息和机器人消息的自动保存接入。
完成页面初始化时的历史消息加载与恢复展示。
修复历史加载异步竞态和欢迎卡片误存问题。
完成用户隔离、历史恢复、记录上限和页面刷新等场景验证。
完成《门户智能助手—历史会话功能开发文档》，沉淀数据库设计、接口、代码逻辑、问题修复、测试方法和部署清单。
完成相关代码多分支推送，为后续 SIT 验证和生产部署提供基础。

四、遇到的问题与解决情况#

问题：页面初始化过程中历史加载与欢迎内容渲染并行执行，导致历史消息可能被覆盖。
处理：将初始化流程调整为异步，并在后续页面渲染前等待历史记录加载完成。
结果：刷新页面后历史消息能够稳定恢复。
问题：欢迎卡片通过机器人消息方法渲染，导致其被错误保存到历史记录。
处理：根据欢迎卡片专用样式类进行判断，保存时主动排除。
结果：欢迎卡片不再进入历史记录，刷新后不会重复出现。
问题：所有 AI 功能都需要记录历史，逐个业务模块接入容易产生重复开发。
处理：将保存逻辑统一接入 addUserMessage 和 addBotMessage 两个公共消息入口。
结果：无需逐个修改业务模块，即可覆盖门户中的主要 AI 交互。
问题：历史记录持续增长可能增加数据库存储和查询压力。
处理：限制前端加载 50 条、后端保留 100 条，并设计超限清理机制。
结果：在满足用户查看近期会话需求的同时控制单用户数据规模。
问题：历史数据必须按用户隔离，不能依赖前端传入用户身份。
处理：后端从门户认证信息中获取当前用户 ID，并将其作为保存和查询条件。
结果：不同用户的历史会话相互隔离。

五、明日计划#

在 SIT 环境继续验证不同门户角色和不同功能模块下的历史会话保存效果。
关注长 HTML 消息、特殊字符和多轮连续交互的保存与恢复情况。
检查超过 100 条记录时的清理执行情况和数据库性能。
配合完成生产库建表申请及部署前检查。
根据测试反馈完善异常日志、接口返回和页面历史展示细节。
整理代码评审材料，推进功能合并和后续上线验证。

六、总结#

今日主要围绕门户智能助手历史会话功能开展工作，完成了从需求分析、开发计划制定、数据库和接口设计，到后端服务、前端消息保存与历史恢复的完整开发流程。同时解决了历史加载异步竞态和欢迎卡片重复保存问题，完成用户隔离、记录上限、页面刷新恢复及多模块覆盖等场景验证，并沉淀了开发计划、DDL 脚本和完整开发文档，为后续 SIT 验证和生产环境部署提供了完整依据。