Files

HaHafeng 0d9e6b9922 feat(admin): Implement System Knowledge Base management module

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

2026-01-28 21:57:44 +08:00

4.8 KiB

Raw Blame History

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 向量数据库

🔧 技术要点

下载功能实现

// 使用 OSSAdapter.getSignedUrl 传入原始文件名
const ossAdapter = storage as OSSAdapter;
const url = ossAdapter.getSignedUrl(doc.file_path, 3600, doc.filename);
// 生成的 URL 带有 Content-Disposition 头，浏览器下载时使用原始文件名

主从页面路由

// 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 行

📝 下一步计划

Prompt + 知识库关联
- 在 Prompt 编辑页添加知识库选择器
- 实现 Prompt 调用时自动 RAG 检索
知识库搜索
- 添加知识库内全文检索功能
- 语义搜索测试界面

📚 相关文档

开发计划：docs/03-业务模块/ADMIN-运营管理端/04-开发计划/05-Prompt知识库集成开发计划.md
OSS 规范：docs/04-开发规范/11-OSS存储开发规范.md
RAG 引擎：docs/02-通用能力层/03-RAG引擎/05-RAG引擎使用指南.md

开发记录完成

4.8 KiB Raw Blame History Unescape Escape