AIclinicalresearch/docs/03-业务模块/PKB-个人知识库/06-开发记录/2026-01-07_PKB模块前端V3设计实现.md

PKB模块前端V3设计实现 - 开发记录

日期： 2026-01-07
开发者： PKB开发团队
版本： v1.0
状态： ✅ 基础框架完成，待细化优化

---

📋 今日工作概述

今天完成了PKB（个人知识库）模块的前端迁移和V3设计实现工作，主要包括：

1. 后端模块迁移：将PKB后端代码迁移到新的模块化架构
2. 前端V3设计实现：基于原型图实现Dashboard和Workspace页面
3. 3种工作模式实现：全文阅读、逐篇精读、批处理
4. Chat组件集成：使用Ant Design X Chat组件实现AI对话

---

✅ 完成的工作

1. 后端模块迁移

迁移内容：

• 将Controller、Service、Route代码迁移到 backend/src/modules/pkb/
• 更新import路径
• 注册新API路由 /api/v2/pkb/*
• 保持旧版路由 /api/v1/knowledge* 兼容

目录结构：

backend/src/modules/pkb/
├── controllers/
│   ├── knowledgeBaseController.ts
│   ├── documentController.ts
│   └── batchController.ts
├── services/
│   ├── knowledgeBaseService.ts
│   ├── documentService.ts
│   └── batchService.ts
├── routes/
│   └── index.ts
└── index.ts

路由注册：

• v2路由：/api/v2/pkb/knowledge（新架构）
• v1路由：/api/v1/knowledge、/api/v1/batch-tasks（兼容）

2. 前端V3设计实现

基于原型图：

• 知识库仪表盘V5.html → DashboardPage
• 工作台V3.html → WorkspacePage

前端目录结构：

frontend-v2/src/modules/pkb/
├── api/
│   └── knowledgeBaseApi.ts          # API客户端
├── stores/
│   └── useKnowledgeBaseStore.ts     # Zustand状态管理
├── pages/
│   ├── DashboardPage.tsx            # 仪表盘页面
│   └── WorkspacePage.tsx            # 工作台页面
├── components/
│   └── Workspace/
│       ├── WorkModeSelector.tsx     # 工作模式选择器
│       ├── FullTextMode.tsx         # 全文阅读模式
│       ├── DeepReadMode.tsx         # 逐篇精读模式
│       ├── BatchMode.tsx            # 批处理模式
│       └── BatchModeComplete.tsx    # 批处理完整实现
├── hooks/
│   └── useWorkMode.ts               # 工作模式Hook
├── types/
│   └── index.ts                     # 类型定义
└── styles/
    └── workspace.css                # 自定义样式

3. WorkspacePage布局设计

最终采用的布局：

┌─────────────────────────────────────────────────┐
│ [返回] │ 知识库名  │ [问答][资产] │ 设置 头像 │ Header 56px
├─────────────────────────────────────────────────┤
│ [工作模式▼] [文档▼]              已加载 x/y 篇 │ 工作模式栏 40px
├─────────────────────────────────────────────────┤
│                                                 │
│              聊天区域（最大化）                 │
│                                                 │
└─────────────────────────────────────────────────┘

设计特点：

• 单层Header整合导航和Tab切换
• 紧凑的工作模式选择栏
• 最大化的聊天区域
• 全屏模式（fixed定位）

4. 3种工作模式

模式	说明	后端API
全文阅读	加载全部文档，AI具备全知视角	/api/v1/chat/stream
逐篇精读	选择1-5篇文档深度解读	/api/v1/chat/stream
批处理	批量提取信息，生成结构化表格	/api/v1/batch-tasks

5. Chat组件集成

使用Ant Design X Chat组件：

• 复用 frontend-v2/src/shared/components/Chat/
• 支持SSE流式响应
• 自定义消息渲染（引用格式化）
• 上下文管理

---

🔧 技术细节

API调用配置

// knowledgeBaseApi.ts
const api = axios.create({
  baseURL: `${API_BASE_URL}/api/v2/pkb`,
  timeout: 30000,
});

// Chat使用v1接口
const chatApi = axios.create({
  baseURL: `${API_BASE_URL}/api/v1/chat/stream`,
});

状态管理

使用Zustand管理全局状态：

• 知识库列表
• 当前知识库
• 文档列表
• 工作模式
• 选中的文档

样式方案

• TailwindCSS作为主要样式方案
• Ant Design组件库
• 自定义CSS处理特殊样式（workspace.css）

---

⚠️ 已知问题

1. 批处理执行功能待调试

• 问题：批处理模式无法执行
• 原因：后端API /api/v1/batch-tasks 需要验证
• 优先级：🔴 高

2. 知识资产页面导航条

• 问题：知识资产页面缺少导航条
• 影响：用户无法在资产页面进行筛选操作
• 优先级：🟡 中

3. UI精细化

• 问题：与原型图仍有差距，需要进一步优化
• 影响：用户体验
• 优先级：🟡 中

---

📝 下一步计划

高优先级

1. 调试批处理API执行功能
2. 完善知识资产页面导航条
3. 引用格式化优化

中优先级

4. UI精细化（与原型图对比优化）
5. 错误处理完善
6. 加载状态优化

低优先级

7. RAG检索模式实现（后端待开发）
8. PDF预览功能增强

---

📊 代码统计

文件	行数	说明
WorkspacePage.tsx	~513	工作台主页面
DashboardPage.tsx	~450	仪表盘页面
BatchModeComplete.tsx	~511	批处理完整实现
WorkModeSelector.tsx	~200	工作模式选择器
FullTextMode.tsx	~150	全文阅读模式
DeepReadMode.tsx	~150	逐篇精读模式
knowledgeBaseApi.ts	~200	API客户端
useKnowledgeBaseStore.ts	~150	状态管理
总计	~2300行	PKB前端模块

---

🎯 总结

今天完成了PKB模块的核心前端框架搭建，实现了：

• ✅ 后端模块迁移和路由注册
• ✅ 前端V3设计基础实现
• ✅ 3种工作模式框架
• ✅ Chat组件集成
• ✅ 响应式布局

虽然还有一些功能需要调试和优化，但整体架构已经搭建完成，可以作为后续开发的基础。

---

Git提交：

5a17d09 feat(pkb): Complete PKB module frontend migration with V3 design

---

文档编写时间：2026-01-07
下次更新：批处理功能调试完成后