AIclinicalresearch/docs/03-业务模块/PKB-个人知识库/00-模块当前状态与开发指南.md

PKB个人知识库模块 - 当前状态与开发指南

文档版本： v1.0
创建日期： 2026-01-07
维护者： PKB模块开发团队
最后更新： 2026-01-07
重大进展： 🎉 PKB模块前端V3设计实现完成！
文档目的： 反映模块真实状态，记录开发历程

---

📋 文档说明

本文档是PKB个人知识库模块的真实状态快照，如实记录当前开发状态、技术架构和已知问题。

与其他文档的关系：

• 本文档（00-模块当前状态）：What is（真实状态，包括问题）
• 需求分析文档：What to do（产品需求）
• 开发记录文档：What done（开发历程）
• 技术设计文档：How to do（设计方案）

---

🎯 模块概述

核心功能

PKB（Personal Knowledge Base）个人知识库模块提供：

• 🗂️ 知识库管理：创建、编辑、删除个人知识库
• 📄 文档管理：上传、处理、组织文档（PDF/Word/TXT/MD）
• 🤖 AI问答：基于知识库内容的智能问答
• 📊 批处理：批量提取文档信息，生成结构化数据

当前状态

组件	状态	完成度	说明
后端API	✅ 已完成	100%	v1 + v2双路由运行
前端Dashboard	✅ 已完成	90%	基于V5原型实现
前端Workspace	✅ 已完成	85%	基于V3原型实现
全文阅读模式	✅ 已完成	90%	Chat组件集成完成
逐篇精读模式	✅ 已完成	85%	文档选择+对话
批处理模式	🔧 待调试	70%	UI完成，API待验证
RAG检索模式	❌ 待开发	0%	后端待实现

整体完成度：约75%

---

🏗️ 技术架构

前端技术栈

框架: React 19 + TypeScript 5
路由: React Router DOM v7
状态管理: Zustand
UI组件: Ant Design v6 + Ant Design X
样式: TailwindCSS v3
构建工具: Vite 7

后端技术栈

框架: Fastify v4 (Node.js 22)
数据库: PostgreSQL 15 + Prisma 6
Schema: pkb_schema (独立隔离)
LLM: DeepSeek-V3, Qwen-Max (通过LLMFactory)
RAG: Dify知识库集成
存储: OSS对象存储

API路由

# 新架构 (v2)
/api/v2/pkb/knowledge         # 知识库CRUD
/api/v2/pkb/knowledge/:id     # 知识库详情
/api/v2/pkb/documents         # 文档管理

# 旧架构 (v1，保持兼容)
/api/v1/knowledge             # 知识库管理
/api/v1/documents             # 文档管理
/api/v1/batch-tasks           # 批处理任务
/api/v1/chat/stream           # AI对话流

---

📂 代码结构

后端代码结构

backend/src/modules/pkb/
├── controllers/
│   ├── knowledgeBaseController.ts    # 知识库控制器
│   ├── documentController.ts         # 文档控制器
│   └── batchController.ts            # 批处理控制器
├── services/
│   ├── knowledgeBaseService.ts       # 知识库服务 (~350行)
│   ├── documentService.ts            # 文档服务 (~400行)
│   └── batchService.ts               # 批处理服务 (~300行)
├── routes/
│   └── index.ts                      # 路由配置
└── index.ts                          # 模块入口

总计: ~1500行后端代码

前端代码结构

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

总计: ~2300行前端代码

---

🎨 UI设计

原型文件

• Dashboard: docs/03-业务模块/PKB-个人知识库/01-需求分析/知识库仪表盘V5.html
• Workspace: docs/03-业务模块/PKB-个人知识库/01-需求分析/工作台V3.html

Workspace布局

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

设计特点

• 单层Header: 整合导航和Tab切换（智能问答/知识资产）
• 紧凑工作模式栏: 下拉选择，节省空间
• 最大化聊天区域: 全屏模式，沉浸式对话体验
• 响应式布局: 支持不同屏幕尺寸

---

🔌 工作模式

1. 全文阅读模式（Full Text）

功能说明：

• 加载知识库全部文档
• AI具备全知视角
• 适合文献综述、跨文献分析

技术实现：

• 调用 /api/v1/chat/stream 接口
• 传入所有文档ID
• 使用SSE流式响应

2. 逐篇精读模式（Deep Read）

功能说明：

• 选择1-5篇文档
• 深度解读单篇文献
• 适合精读、批注、理解

技术实现：

• 下拉选择文档（最多5篇）
• 调用相同Chat接口
• 仅传入选中文档ID

3. 批处理模式（Batch）

功能说明：

• 选择批处理模板
• 批量提取文档信息
• 生成结构化表格

技术实现：

• 调用 /api/v1/batch-tasks 接口
• 支持进度查询
• 结果导出Excel

当前状态：🔧 API执行待调试

4. RAG检索模式（待开发）

功能说明：

• 基于向量检索
• 精准定位相关段落
• 适合快速查找

当前状态：❌ 后端待实现

---

⚠️ 已知问题

1. 批处理执行功能 🔴 高优先级

问题描述：

• 批处理模式前端UI已完成
• 后端API /api/v1/batch-tasks 执行需验证
• 无法正常执行批量提取

影响：批处理功能不可用

解决方案：

1. 验证后端API接口
2. 检查请求参数格式
3. 调试执行流程

2. 知识资产页面导航 🟡 中优先级

问题描述：

• 知识资产Tab页面缺少工具栏
• 无法进行筛选、排序操作

影响：用户操作不便

解决方案：

• 添加文档筛选工具栏
• 添加排序功能
• 添加批量操作

3. UI精细化 🟡 中优先级

问题描述：

• 与原型图仍有差距
• 部分样式需要调整

影响：视觉体验

解决方案：

• 逐项对比原型图
• 调整间距、字体、颜色
• 完善动画效果

4. 引用格式化 🟢 低优先级

问题描述：

• AI回复中的引用格式不够美观
• 需要自定义渲染

影响：阅读体验

解决方案：

• 实现customMessageRenderer
• 解析引用标记
• 渲染为可点击的引用块

---

📝 下一步开发计划

立即需要做的（紧急）

1. 调试批处理API 🔴

   • 验证 /api/v1/batch-tasks 接口
   • 检查请求参数
   • 测试完整流程

2. 完善知识资产页面 🔴

   • 添加工具栏导航
   • 实现筛选功能

短期任务（本周）

3. UI精细化

   • 对比原型图优化
   • 调整样式细节

4. 错误处理

   • 完善错误提示
   • 添加重试机制

中期任务（2周内）

5. RAG检索模式

   • 后端API开发
   • 前端集成

6. PDF预览增强

   • 集成PDF查看器
   • 支持标注

---

📚 相关文档

需求文档

• PRD V5.0
• 知识库仪表盘V5原型
• 工作台V3原型

技术文档

• 数据库设计

开发记录

• 2026-01-07 前端V3设计实现

测试文档

• 与原型图的差距

---

🎓 给新开发者的提示

快速上手

1. 了解模块结构

   • 阅读本文档了解当前状态
   • 查看原型HTML了解UI设计

2. 运行项目

   # 后端
   cd backend && npm run dev
   
   # 前端
   cd frontend-v2 && npm run dev
   

3. 查看关键代码

   • WorkspacePage.tsx - 工作台主逻辑
   • knowledgeBaseApi.ts - API调用
   • useKnowledgeBaseStore.ts - 状态管理

注意事项

✅ 应该这样做：

1. 使用Zustand管理状态
2. 复用shared/components中的Chat组件
3. 遵循TailwindCSS样式规范
4. 使用Ant Design组件

❌ 不要这样做：

1. 创建新的Chat实现
2. 直接操作DOM
3. 使用行内样式
4. 忽略TypeScript类型

---

📊 模块统计

代码量统计

后端代码：约1,500行
前端代码：约2,300行
总计：约3,800行

开发进度

整体进度：约75%

- 后端API：100% ✅
- Dashboard页面：90% ✅
- Workspace页面：85% ✅
- 全文阅读模式：90% ✅
- 逐篇精读模式：85% ✅
- 批处理模式：70% 🔧
- RAG检索模式：0% ❌

---

🔗 Git提交记录

最新提交：

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

提交内容：

• 后端模块迁移到 /modules/pkb
• 前端V3设计实现
• 3种工作模式框架
• Chat组件集成

---

最后更新： 2026-01-07
文档维护： PKB模块开发团队
联系方式： 项目Issues