AIclinicalresearch/docs/03-业务模块/PKB-个人知识库/06-开发记录/2026-01-07-前端迁移与批处理功能完善.md

PKB个人知识库 - 前端迁移与批处理功能完善

开发日期：2026年1月7日
开发人员：AI Assistant
版本：v2.0

---

一、开发目标

1. 前端架构迁移：将PKB前端迁移到 frontend-v2/modules/pkb 新架构
2. 工作模式实现：实现全文阅读、逐篇精读、批处理三种工作模式
3. 批处理功能：完善批处理任务的执行、进度显示和结果导出
4. UI优化：优化界面细节，提升用户体验

---

二、主要工作内容

1. 前端架构搭建

目录结构创建

frontend-v2/src/modules/pkb/
├── api/                    # API客户端
│   └── knowledgeBaseApi.ts
├── stores/                 # 状态管理
│   └── useKnowledgeBaseStore.ts
├── components/             # 通用组件
│   ├── DocumentUpload.tsx
│   └── Workspace/          # 工作台组件
│       ├── FullTextMode.tsx
│       ├── DeepReadMode.tsx
│       ├── BatchModeComplete.tsx
│       └── WorkModeSelector.tsx
├── pages/                  # 页面组件
│   ├── DashboardPage.tsx
│   └── WorkspacePage.tsx
├── hooks/                  # 自定义Hooks
│   └── useWorkMode.ts
└── styles/                 # 样式文件
    └── workspace.css

核心文件创建

• DashboardPage.tsx：知识库列表和创建入口
• WorkspacePage.tsx：知识库工作台主页面
• 三种工作模式组件：全文阅读、逐篇精读、批处理

2. Chat组件集成

技术选型：Ant Design X
特点：

• 统一的对话组件，支持流式响应
• 自定义消息渲染器
• 自动滚动和输入框管理

集成问题修复：

• ✅ 输入框清除：使用受控模式 value={inputValue}
• ✅ 自动滚动：添加 messagesEndRef 锚点
• ✅ 参考文献格式化：实现 customMessageRenderer

3. 工作模式实现

3.1 全文阅读模式

功能：

• 加载知识库全部文档（已完成状态）
• 使用 fullTextDocumentIds 参数传递完整文献
• AI具备全知视角，可进行综合分析

API调用：

body: JSON.stringify({
  content: message,
  modelType: 'qwen-long',
  knowledgeBaseIds: [kbId],
  fullTextDocumentIds: completedDocIds,  // 全文模式
})

修复问题：

• ❌ 初次加载显示"0篇文档"
• ✅ 将文档数量加入 conversationKey，强制重新渲染

3.2 逐篇精读模式

功能：

• 选择1-5篇文档进行深度解读
• 每篇文档独立对话上下文
• 切换文档时清空对话历史

技术实现：

const conversationKey = useMemo(() => {
  return `kb-deepread-${kbId}-${selectedDoc.id}`;
}, [kbId, selectedDoc.id]);

修复问题：

• ❌ 切换文档报错：TypeError: formattedContent.replace is not a function
• ✅ 添加类型检查，正确处理 MessageRenderParams
• ❌ 输入框不清除、不自动滚动
• ✅ 在ChatContainer添加受控输入和滚动锚点

3.3 批处理模式

功能：

• 选择3-50篇文档批量提取信息
• 支持临床研究信息提取模板（8个字段）
• 实时显示处理进度
• 结果可导出为CSV

开发历程：

问题1：选择数量翻倍

• ❌ 原因：点击行和Checkbox都触发选择，导致重复添加
• ✅ 解决：使用统一的 toggle 函数，Checkbox用 onClick stopPropagation

问题2：API 404错误

• ❌ 路径错误：/api/v1/batch-tasks
• ✅ 正确路径：/api/v2/pkb/batch-tasks/batch/execute

问题3：API 500错误

• ❌ 字段名不匹配：前端发送 knowledgeBaseId，后端期望 kb_id
• ✅ 修复请求体格式：

{
  kb_id: kbId,                   // 后端格式
  document_ids: selectedDocs,
  template_type: 'preset',
  template_id: 'clinical_research',
  model_type: 'qwen-long',
}

问题4：模板ID不匹配

• ❌ 前端：clinicalResearch（驼峰）
• ❌ 后端：clinical_research（下划线）
• ✅ 统一为 clinical_research

问题5：前端不显示结果

• ❌ 后端返回 status: "success"，前端判断 status === 'completed'
• ✅ 修复状态判断：

const isSuccess = docResult.status === 'success' || docResult.status === 'completed';

问题6：表格显示粗糙

• ❌ 文件名过长，内容显示不全
• ✅ 实现方案A：
  • 文件名最多2行
  • 内容最多3行 (-webkit-line-clamp: 3)
  • 悬停显示完整内容（Tooltip）
  • 结果数据列更宽（280px）

4. 文档上传功能

问题：

• ❌ "上传新文件"按钮无响应
• ❌ 没有绑定 onClick 事件

解决方案：

1. 导入 DocumentUpload 组件和 Modal
2. 添加 uploadModalVisible 状态
3. 为按钮绑定 onClick={() => setUploadModalVisible(true)}
4. 添加上传弹窗，集成 DocumentUpload 组件
5. 修复导入路径：../stores/useKnowledgeBaseStore

---

三、技术难点与解决方案

1. ChatContainer消息渲染

问题：自定义渲染器接收的参数格式复杂

interface MessageRenderParams {
  id: string | number;
  message: {
    id: string | number;
    role: string;
    content: string;
    status?: string;
  };
  status: string;
}

解决：正确解析 params.message.content

2. 批处理结果获取

问题：后端返回嵌套结构 { success: true, data: { results: [...] } }

解决：

const resultsData = resultsJson.data?.results || [];
const newResults = resultsData.map((docResult: any) => ({
  documentId: docResult.document_id,
  documentName: docResult.document_name,
  result: docResult.data,  // 提取数据在这里
}));

3. React Key重复警告

问题：批处理结果列表使用 documentId 作为key，可能重复

解决：

• 在文档选择列表使用 useMemo 去重
• 在结果映射时使用 ${documentId}-${index} 确保唯一

4. 前后端字段映射

后端字段	前端显示
research_purpose	研究目的
research_design	研究设计
research_subjects	研究对象
sample_size	样本量
intervention_group	干预组
control_group	对照组
results_data	结果及数据
oxford_level	牛津评级

---

四、API路由总结

新架构路由（v2）

功能	方法	路径
知识库列表	GET	/api/v2/pkb/knowledge-bases
创建知识库	POST	/api/v2/pkb/knowledge-bases
上传文档	POST	/api/v2/pkb/knowledge-bases/:id/documents
文档列表	GET	/api/v2/pkb/knowledge-bases/:id/documents
批处理执行	POST	/api/v2/pkb/batch-tasks/batch/execute
批处理状态	GET	/api/v2/pkb/batch-tasks/batch/tasks/:id
批处理结果	GET	/api/v2/pkb/batch-tasks/batch/tasks/:id/results

对话路由（通用）

功能	方法	路径
流式对话	POST	/api/v1/chat/stream

---

五、UI/UX优化细节

1. WorkspacePage布局

• 单层Header：整合返回、标题、Tab切换、设置、头像
• Header高度：h-14（56px）
• 工作模式选择器：紧凑的 h-10 栏
• Chat区域：最大化剩余空间

2. 批处理结果表格

• 固定表头：背景 #F9FAFB，文字 #6B7280
• 文件名列：220px，最多2行
• 内容列：180-280px，最多3行
• 悬停提示：最大宽度450px，最大高度300px

3. 参考文献格式

// 卡片式显示
<div className="flex items-start p-3 bg-blue-50 rounded-lg border border-blue-100">
  <BookOpen className="w-4 h-4 text-blue-500 mr-2" />
  <span className="text-sm text-slate-700">{citation}</span>
</div>

---

六、测试结果

功能测试

功能模块	测试项	结果
知识库列表	创建/查看/删除	✅
文档上传	拖拽/点击上传	✅
全文阅读	加载文档/问答	✅
逐篇精读	文档切换/问答	✅
批处理	模板选择/执行/结果显示	✅
结果导出	CSV导出	✅

性能测试

• 3篇文档批处理：~17-28秒
• 6篇文档全文加载：~14k-15k tokens
• 文档上传：进度实时显示，支持10MB以内

---

七、已知问题与改进方向

当前限制

1. 批处理只支持1个模板（临床研究信息提取）
2. 批处理最少3篇文档（后端限制）
3. 逐篇精读最多5篇文档（前端限制）

未来优化

1. 增加模板：药物安全性、患者基线特征等
2. 自定义模板：允许用户自定义提取字段
3. 结果预览：在表格中支持单元格展开
4. 批处理恢复：支持中断后继续执行
5. 文档预览：集成PDF预览功能

---

八、代码统计

新增文件

• 前端页面：2个（Dashboard、Workspace）
• 前端组件：6个（3种工作模式 + 选择器 + 上传 + 文档列表）
• API客户端：1个
• 状态管理：1个
• 样式文件：1个

代码量估算

• TypeScript：~2500行
• CSS：~200行
• 文档：~1000行

---

九、团队协作

参考旧版实现

• 文档上传：frontend/src/components/knowledge/DocumentUpload.tsx
• 批处理：frontend/src/components/chat/BatchMode.tsx
• 文档选择：frontend/src/components/chat/DocumentSelection.tsx

Git提交

• 遵循语义化提交规范
• 中文使用UTF-8编码
• 分多次提交，每次聚焦单一功能

---

十、总结

本次开发完成了PKB个人知识库模块从架构设计到核心功能的完整实现，特别是：

1. ✅ 新架构迁移：成功迁移到 frontend-v2 新架构
2. ✅ 三种工作模式：全文阅读、逐篇精读、批处理全部实现
3. ✅ 批处理完整流程：从模板选择到结果导出的完整链路
4. ✅ UI/UX优化：参照原型图精细化实现，用户体验良好
5. ✅ 问题解决能力：快速定位并解决10+个技术问题

里程碑意义：PKB模块已具备生产环境可用性，为后续功能扩展奠定了坚实基础！

---

下一步建议：

1. 进行完整的用户验收测试（UAT）
2. 优化批处理性能（并发、缓存）
3. 增加更多模板和自定义能力
4. 完善错误处理和用户反馈