HaHafeng
dfc0fe0b9a
Summary: - Migrate PostgreSQL to pgvector/pgvector:pg15 Docker image - Successfully install and verify pgvector 0.8.1 extension - Create comprehensive Dify-to-pgvector migration plan - Update PKB module documentation with pgvector status - Update system documentation with pgvector integration Key changes: - docker-compose.yml: Switch to pgvector/pgvector:pg15 image - Add EkbDocument and EkbChunk data model design - Design R-C-R-G hybrid retrieval architecture - Add clinical data JSONB fields (pico, studyDesign, regimen, safety, criteria, endpoints) - Create detailed 10-day implementation roadmap Documentation updates: - PKB module status: pgvector RAG infrastructure ready - System status: pgvector 0.8.1 integrated - New: Dify replacement development plan (01-Dify替换为pgvector开发计划.md) - New: Enterprise medical knowledge base solution V2 Tested: PostgreSQL with pgvector verified, frontend and backend functionality confirmed
443 lines
12 KiB
Markdown
443 lines
12 KiB
Markdown
# PKB个人知识库模块 - 当前状态与开发指南
|
||
|
||
> **文档版本：** v2.1
|
||
> **创建日期：** 2026-01-07
|
||
> **维护者：** PKB模块开发团队
|
||
> **最后更新：** 2026-01-19
|
||
> **重大进展：** 🎉 **PKB模块核心功能全部实现，pgvector向量数据库已集成！**
|
||
> **基础设施：** ✅ pgvector 0.8.1 已安装，RAG检索模式基础设施就绪
|
||
> **文档目的：** 反映模块真实状态，记录开发历程
|
||
|
||
---
|
||
|
||
## 📋 文档说明
|
||
|
||
本文档是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** | ✅ 已完成 | 95% | 基于V5原型实现 |
|
||
| **前端Workspace** | ✅ 已完成 | 95% | 基于V3原型实现 |
|
||
| **全文阅读模式** | ✅ 已完成 | 95% | Chat组件集成完成 |
|
||
| **逐篇精读模式** | ✅ 已完成 | 95% | 文档选择+对话 |
|
||
| **批处理模式** | ✅ 已完成 | 95% | 完整流程+结果导出 |
|
||
| **文档上传** | ✅ 已完成 | 100% | 拖拽+进度显示 |
|
||
| **RAG检索模式** | ⏸️ 暂缓 | 0% | 优先级调整 |
|
||
|
||
**整体完成度：约90%** 🎉
|
||
|
||
---
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
### 前端技术栈
|
||
|
||
```
|
||
框架: 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 + pgvector 0.8.1
|
||
Schema: pkb_schema (独立隔离)
|
||
向量存储: pgvector (PostgreSQL原生向量扩展) ✅ 2026-01-19 已集成
|
||
LLM: DeepSeek-V3, Qwen-Max (通过LLMFactory)
|
||
RAG: Dify知识库集成 → 计划迁移到 pgvector 原生RAG
|
||
存储: 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检索模式（基础设施就绪）
|
||
|
||
**功能说明**：
|
||
- 基于向量检索
|
||
- 精准定位相关段落
|
||
- 适合快速查找
|
||
|
||
**当前状态**：🟡 基础设施已就绪（pgvector 0.8.1 已安装），后端业务逻辑待实现
|
||
|
||
**技术基础**（2026-01-19 完成）：
|
||
- ✅ pgvector 扩展已安装（版本 0.8.1）
|
||
- ✅ 支持 HNSW 和 IVFFlat 索引
|
||
- ✅ 与阿里云 RDS pgvector 0.8.0 兼容
|
||
- ⏳ 向量表设计待实现
|
||
- ⏳ Embedding 服务集成待实现
|
||
- ⏳ 相似度检索 API 待实现
|
||
|
||
---
|
||
|
||
## ⚠️ 已知问题
|
||
|
||
### 1. RAG检索模式业务逻辑未实现 🟡 中优先级
|
||
|
||
**问题描述**：
|
||
- pgvector 基础设施已就绪（2026-01-19）
|
||
- RAG检索业务逻辑待实现
|
||
- 当前优先全文阅读和逐篇精读模式
|
||
|
||
**影响**：工作模式选择有限
|
||
|
||
**解决方案**：
|
||
- v2.1版本实现RAG检索（基于pgvector，不再依赖Dify）
|
||
- 设计向量表结构（pkb_schema.document_embeddings）
|
||
- 集成 Embedding 服务（OpenAI/智谱）
|
||
- 实现相似度检索 API
|
||
|
||
### 2. 批处理模板有限 🟢 低优先级
|
||
|
||
**问题描述**：
|
||
- 当前只支持1个模板（临床研究信息提取）
|
||
- 需要更多预设模板和自定义能力
|
||
|
||
**影响**：批处理应用场景有限
|
||
|
||
**解决方案**：
|
||
- v2.2版本增加药物安全性、患者基线等模板
|
||
- 支持用户自定义模板
|
||
|
||
### 3. 文档预览功能缺失 🟢 低优先级
|
||
|
||
**问题描述**：
|
||
- 暂不支持文档在线预览
|
||
- 需下载后查看原文
|
||
|
||
**影响**：用户体验
|
||
|
||
**解决方案**：
|
||
- v3.0版本集成PDF预览功能
|
||
- 支持文档标注和批注
|
||
|
||
---
|
||
|
||
## 📝 下一步开发计划
|
||
|
||
### v2.1 版本（短期）
|
||
|
||
1. **RAG检索模式** 🟡 （基础设施已就绪 ✅）
|
||
- ✅ pgvector 0.8.1 已安装
|
||
- 设计向量表结构（pkb_schema.document_embeddings）
|
||
- 集成 Embedding 服务（文本向量化）
|
||
- 实现相似度检索 API
|
||
- 添加工作模式选择器
|
||
- 测试检索准确度
|
||
|
||
2. **性能优化** 🟡
|
||
- 批处理并发优化
|
||
- 文档加载缓存
|
||
- API响应时间优化
|
||
|
||
### v2.2 版本（中期）
|
||
|
||
3. **批处理增强** 🟢
|
||
- 增加药物安全性模板
|
||
- 增加患者基线特征模板
|
||
- 支持自定义模板
|
||
|
||
4. **用户体验优化** 🟢
|
||
- 文档筛选和排序
|
||
- 批量操作
|
||
- 快捷键支持
|
||
|
||
### 中期任务（2周内）
|
||
|
||
5. **RAG检索模式**
|
||
- 后端API开发
|
||
- 前端集成
|
||
|
||
6. **PDF预览增强**
|
||
- 集成PDF查看器
|
||
- 支持标注
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
### 需求文档
|
||
- [PRD V5.0](./01-需求分析/AI%20临床医生与医院知识库%20-%20MVP%20阶段产品需求文档%20(PRD)%20V5.0.md)
|
||
- [知识库仪表盘V5原型](./01-需求分析/知识库仪表盘V5.html)
|
||
- [工作台V3原型](./01-需求分析/工作台V3.html)
|
||
|
||
### 技术文档
|
||
- [数据库设计](./02-技术设计/01-数据库设计.md)
|
||
|
||
### 开发记录
|
||
- [2026-01-07 前端V3设计实现](./06-开发记录/2026-01-07_PKB模块前端V3设计实现.md)
|
||
|
||
### 测试文档
|
||
- [与原型图的差距](./05-测试文档/与原型图的差距.md)
|
||
|
||
---
|
||
|
||
## 🎓 给新开发者的提示
|
||
|
||
### 快速上手
|
||
|
||
1. **了解模块结构**
|
||
- 阅读本文档了解当前状态
|
||
- 查看原型HTML了解UI设计
|
||
|
||
2. **运行项目**
|
||
```bash
|
||
# 后端
|
||
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-19 pgvector 向量数据库集成
|
||
|
||
**重大变更**：
|
||
- ✅ **pgvector 0.8.1 安装成功**：Docker 环境已迁移到 `pgvector/pgvector:pg15` 镜像
|
||
- ✅ **兼容性验证**：与阿里云 RDS pgvector 0.8.0 完全兼容
|
||
- ✅ **功能验证**：前后端服务重启后功能正常
|
||
- ✅ **数据完整性**：用户数据、知识库数据、pg-boss 队列函数全部正常
|
||
|
||
**技术细节**：
|
||
- 镜像：`pgvector/pgvector:pg15`
|
||
- 扩展版本：0.8.1
|
||
- 支持索引类型：HNSW、IVFFlat
|
||
- 向量维度：最高支持 16000 维
|
||
|
||
**下一步**：
|
||
- 设计 `pkb_schema.document_embeddings` 表
|
||
- 集成 Embedding 服务
|
||
- 实现 RAG 检索 API
|
||
|
||
---
|
||
|
||
**最后更新：** 2026-01-19
|
||
**文档维护：** PKB模块开发团队
|
||
**联系方式：** 项目Issues
|
||
|
||
|