HaHafeng
0d9e6b9922
Features:
- Backend: SystemKbService with full CRUD (knowledge bases + documents)
- Backend: 8 RESTful API endpoints (list/detail/create/update/delete/upload/download)
- Backend: OSS storage integration (system/knowledge-bases/{kbId}/{docId})
- Backend: RAG engine integration (document parsing, chunking, vectorization)
- Frontend: SystemKbListPage with card-based layout
- Frontend: SystemKbDetailPage with document management table
- Frontend: Master-Detail UX pattern for better user experience
- Document upload (single/batch), download (preserving original filename), delete
Technical:
- Database migration for system_knowledge_bases and system_kb_documents tables
- OSSAdapter.getSignedUrl with Content-Disposition for original filename
- Reuse RAG engine from common/rag for document processing
Tested: Local environment verified, all features working
147 lines
4.8 KiB
Markdown
147 lines
4.8 KiB
Markdown
# 2026-01-27 系统知识库管理功能完成
|
||
|
||
> **开发日期：** 2026-01-27
|
||
> **开发者：** AI Assistant
|
||
> **状态：** ✅ 功能完整可用
|
||
|
||
---
|
||
|
||
## 📋 开发内容
|
||
|
||
### 系统知识库管理功能（System KB）
|
||
|
||
运营管理端新增「系统知识库」模块，供管理员创建和管理公共知识库，支持 Prompt 引用。
|
||
|
||
---
|
||
|
||
## ✅ 已完成功能
|
||
|
||
### 1. 后端 API（8 个接口）
|
||
|
||
| 接口 | 方法 | 路径 | 功能 |
|
||
|------|------|------|------|
|
||
| 知识库列表 | GET | `/api/v1/admin/system-kb` | 获取所有系统知识库 |
|
||
| 知识库详情 | GET | `/api/v1/admin/system-kb/:id` | 获取单个知识库详情 |
|
||
| 创建知识库 | POST | `/api/v1/admin/system-kb` | 创建新知识库 |
|
||
| 更新知识库 | PATCH | `/api/v1/admin/system-kb/:id` | 更新知识库信息 |
|
||
| 删除知识库 | DELETE | `/api/v1/admin/system-kb/:id` | 删除知识库（含所有文档） |
|
||
| 文档列表 | GET | `/api/v1/admin/system-kb/:id/documents` | 获取知识库文档列表 |
|
||
| 上传文档 | POST | `/api/v1/admin/system-kb/:id/documents` | 上传文档（支持 PDF/Word/TXT） |
|
||
| 删除文档 | DELETE | `/api/v1/admin/system-kb/:id/documents/:docId` | 删除单个文档 |
|
||
| 下载文档 | GET | `/api/v1/admin/system-kb/:id/documents/:docId/download` | 获取文档下载链接 |
|
||
|
||
**后端文件：**
|
||
- `backend/src/modules/admin/system-kb/systemKbService.ts` - 核心业务逻辑
|
||
- `backend/src/modules/admin/system-kb/systemKbController.ts` - 请求处理
|
||
- `backend/src/modules/admin/system-kb/systemKbRoutes.ts` - 路由定义
|
||
- `backend/src/modules/admin/system-kb/index.ts` - 模块导出
|
||
|
||
### 2. 前端界面（主从页面模式）
|
||
|
||
**Master 页面 - 知识库列表**
|
||
- 卡片式布局展示所有知识库
|
||
- 显示知识库名称、代码、文档数、Token 数
|
||
- 支持创建新知识库（Modal 弹窗）
|
||
- 支持编辑、删除知识库
|
||
- 点击卡片进入详情页
|
||
|
||
**Detail 页面 - 知识库详情**
|
||
- 顶部：面包屑导航 + 返回按钮
|
||
- 统计卡片：文档数、Token 总量
|
||
- 文档表格：文件名、大小、Token、状态、上传时间、操作
|
||
- 支持单个/批量上传文档
|
||
- 支持单个/批量删除文档
|
||
- 上传进度显示
|
||
- 下载文档功能（保留原始文件名）
|
||
|
||
**前端文件：**
|
||
- `frontend-v2/src/modules/admin/pages/SystemKbListPage.tsx` - 列表页
|
||
- `frontend-v2/src/modules/admin/pages/SystemKbDetailPage.tsx` - 详情页
|
||
- `frontend-v2/src/modules/admin/api/systemKbApi.ts` - API 调用
|
||
- `frontend-v2/src/modules/admin/types/systemKb.ts` - 类型定义
|
||
|
||
### 3. 数据库设计
|
||
|
||
**表结构：**
|
||
- `capability_schema.system_knowledge_bases` - 系统知识库表
|
||
- `capability_schema.system_kb_documents` - 知识库文档表
|
||
- `ekb_schema.ekb_knowledge_base` - EKB 知识库（RAG 引擎）
|
||
- `ekb_schema.ekb_document` - EKB 文档（向量化）
|
||
- `ekb_schema.ekb_chunk` - 文档分块（向量存储）
|
||
|
||
### 4. OSS 存储集成
|
||
|
||
**存储路径：** `system/knowledge-bases/{kbId}/{docId}.{ext}`
|
||
|
||
**遵循规范：**
|
||
- ✅ UUID 命名存储，原始文件名存数据库
|
||
- ✅ 签名 URL 下载，支持 Content-Disposition
|
||
- ✅ 下载时恢复原始文件名
|
||
|
||
### 5. RAG 引擎集成
|
||
|
||
复用 `common/rag/` RAG 引擎能力：
|
||
- DocumentIngestService：文档解析、分块、向量化
|
||
- EmbeddingService：文本向量化（text-embedding-v4）
|
||
- 存储到 pgvector 向量数据库
|
||
|
||
---
|
||
|
||
## 🔧 技术要点
|
||
|
||
### 下载功能实现
|
||
|
||
```typescript
|
||
// 使用 OSSAdapter.getSignedUrl 传入原始文件名
|
||
const ossAdapter = storage as OSSAdapter;
|
||
const url = ossAdapter.getSignedUrl(doc.file_path, 3600, doc.filename);
|
||
// 生成的 URL 带有 Content-Disposition 头，浏览器下载时使用原始文件名
|
||
```
|
||
|
||
### 主从页面路由
|
||
|
||
```typescript
|
||
// App.tsx 路由配置
|
||
<Route path="system-kb" element={<SystemKbListPage />} />
|
||
<Route path="system-kb/:id" element={<SystemKbDetailPage />} />
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 代码量统计
|
||
|
||
| 文件类型 | 文件数 | 代码行数（约） |
|
||
|---------|--------|---------------|
|
||
| 后端 Service | 1 | ~500 行 |
|
||
| 后端 Controller | 1 | ~340 行 |
|
||
| 后端 Routes | 1 | ~75 行 |
|
||
| 前端 ListPage | 1 | ~320 行 |
|
||
| 前端 DetailPage | 1 | ~450 行 |
|
||
| 前端 API | 1 | ~130 行 |
|
||
| 前端 Types | 1 | ~60 行 |
|
||
| **合计** | **7** | **~1,875 行** |
|
||
|
||
---
|
||
|
||
## 📝 下一步计划
|
||
|
||
1. **Prompt + 知识库关联**
|
||
- 在 Prompt 编辑页添加知识库选择器
|
||
- 实现 Prompt 调用时自动 RAG 检索
|
||
|
||
2. **知识库搜索**
|
||
- 添加知识库内全文检索功能
|
||
- 语义搜索测试界面
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- 开发计划：`docs/03-业务模块/ADMIN-运营管理端/04-开发计划/05-Prompt知识库集成开发计划.md`
|
||
- OSS 规范：`docs/04-开发规范/11-OSS存储开发规范.md`
|
||
- RAG 引擎：`docs/02-通用能力层/03-RAG引擎/05-RAG引擎使用指南.md`
|
||
|
||
---
|
||
|
||
*开发记录完成*
|