Java MaxKB 前端适配与验收记录

本章记录复用 MaxKB 前端时的接口约定，方便后续更新前端分支后重新核对。

前端独立运行

  • 路由使用 createWebHashHistory。页面路径位于 /ui/#/ 后，刷新页面不要求 Java 后端识别前端路由。
  • 普通请求和 SSE 请求统一使用 VITE_API_BASE_URL，默认 /api。
  • Vite 将 /api 转发到 VITE_PROXY_TARGET，本地默认 http://127.0.0.1:10060。
  • 应用分享地址采用当前浏览器 origin 加 /ui/#/chat/，不写死主机名。
  • 构建与类型检查分别执行 npm run build-only、npm run type-check。

部署构建产物时，静态服务提供 /ui/，反向代理负责 /api。如果改变静态目录前缀，需要同步调整 Vite base 和分享地址前缀。

上传接口

POST /api/dataset/document/split 接收 multipart 的 file 字段，可以包含多个文件。解析返回文件 id、name 和 content 分段列表。

确认导入时，POST /api/dataset/{datasetId}/document/_bach 的每个元素必须携带相同的文件 id：

[
  {
    "id": "解析接口返回的文件ID",
    "name": "行政复议法.docx",
    "paragraphs": [
      {"title": "申请期限", "content": "确认后的分段正文"}
    ]
  }
]

UploadDocumentDataset.vue 继续调用 Pinia store 的 asyncPostDocument，并保留 id: item.id。接口中的 _bach 拼写属于现有前后端协议，不能只改动一端。

上传文件名保留 Unicode 和百分号；multipart 中的 filename* 按声明编码解析，适用于浏览器及命令行客户端。

应用与流式问答

  • 应用详情保留 model_id，并兼容 model 字段。
  • 模型列表按 model_type 区分向量模型和推理模型。
  • “部门机构”类型保留创建入口、列表标签和菜单显示。
  • 资料检索测试保留较低的初始相似度阈值，便于观察结果后再调整。
  • SSE 响应包含 chat_id、chat_record_id、节点标识、content 和 is_end。
  • 前端复用同一个 TextDecoder 处理流，兼容一个中文字符被拆到多个网络数据块的情况，并显示流内错误消息。
  • 登录页根据 profile 的 captcha_enabled 决定是否显示验证码控件。

对话历史接口返回分段答案列表及字符串时间，支持页面刷新后恢复历史聊天。调试会话与正式分享会话分别保存。

本地验收

验收使用公开政法资料，日期为 2026-10-02。

路径输入或操作观察结果
DOCX 上传《中华人民共和国行政复议法》界面预览 8 个分段，向量入库成功
第一轮问答询问行政复议申请的一般期限及依据界面回答六十日并引用第二十条
第二轮追问“如果因不可抗力耽误了这个期限，应当如何计算？”承接前文主题，引用第二十条第二款
扫描 PDF《褚庙乡职能配置、内设机构和人员编制规定》检测为 4 页扫描 PDF，OCR 后生成 2 个分段
OCR 问答询问该乡主要职责分享聊天页回答八个方面并引用第二条
刷新后追问恢复历史后询问“其中的行政审批服务具体包括什么？”正确恢复主题，引用扫描文件第二条和第三条
检索模式同一问题分别使用向量、关键词和混合模式三种模式均返回有效分段
会话隔离分享访客请求管理模型列表、另一访客会话分别被权限检查与会话归属检查拦截
文档安全与格式测试空文件、DOCX 外部实体、混合 PDF、中文编码、表格、图片、ZIP独立测试覆盖解析策略与拒绝条件

解析策略及缓存共 9 项独立测试通过。另有 HTTP 动词路由、用户 ID 类型与 multipart 文件名测试通过。OCR 缓存使用原始 PDF 内容摘要和页码作为标识，PDF 页重新序列化或文件改名不会导致同一内容重复请求。

本记录验证知识库导入、远程模型检索、多轮聊天和独立前端。功能库、任意工作流节点、语音及企业扩展应按各自接口另行验收，不能把本记录理解为原版全部功能的等价性证明。

迭代检索与上下文压缩适配

新增 agent_status SSE 事件用于显示整理上下文、正在检索、核验证据及生成回答的进度。事件按类型分流，不写入答案正文。回答结束后读取记录详情，展示每轮查询、资料缺口、新增段落数和停止原因；页面刷新后可以从记录详情恢复轨迹。上下文发生压缩时，显示累计压缩轮数和保留的近期轮数。

后端配置、迁移和 Python 执行器接口见第 32 章。本次真实问答已验证一个提问执行三轮检索：行政复议一般期限有证据，褚庙乡指定年度预算金额无证据，系统继续查询后明确说明不能核实预算数字。

表格解析使用 Apache POI，相关能力可参考 官方项目说明。