feat(knowledge): enhance knowledge base management with improved interfaces and components

refactor(interfaces): add comprehensive documentation and type definitions
feat(components): implement empty state handling and team filtering in KnowledgeGridView
refactor(hooks): optimize knowledge list fetching with better parameter handling
style(interfaces): improve code readability with detailed comments

src/interfaces/database/base.ts

@@ -1,17 +1,41 @@
+/**
+ * 通用响应类型接口
+ * 定义API响应的标准格式
+ * @template T 响应数据的类型，默认为any
+ */
 export interface ResponseType<T = any> {
+  /** 响应状态码 */
   code: number;
+  /** 响应数据 */
   data: T;
+  /** 响应消息 */
   message: string;
+  /** HTTP状态码 */
   status: number;
 }
 
+/**
+ * GET请求响应类型接口
+ * 用于GET请求的响应数据结构
+ * @template T 响应数据的类型，默认为any
+ */
 export interface ResponseGetType<T = any> {
+  /** 响应数据 */
   data: T;
+  /** 加载状态，可选字段 */
   loading?: boolean;
 }
 
+/**
+ * POST请求响应类型接口
+ * 用于POST请求的响应数据结构，支持扩展字段
+ * @template T 响应数据的类型，默认为any
+ */
 export interface ResponsePostType<T = any> {
+  /** 响应数据 */
   data: T;
+  /** 加载状态，可选字段 */
   loading?: boolean;
+  /** 其他扩展字段，键为字符串，值为未知类型 */
   [key: string]: unknown;
 }

src/interfaces/database/knowledge.ts

@@ -1,168 +1,355 @@
 import type { RunningStatus } from '@/constants/knowledge';
 
-// knowledge base
+/**
+ * 知识库接口定义
+ * 包含知识库的基本信息、配置和状态
+ */
 export interface IKnowledge {
+  /** 知识库头像，可选字段 */
   avatar?: any;
+  /** 知识库中的文档块数量 */
   chunk_num: number;
+  /** 创建日期（字符串格式） */
   create_date: string;
+  /** 创建时间戳 */
   create_time: number;
+  /** 创建者ID */
   created_by: string;
+  /** 知识库描述 */
   description: string;
+  /** 知识库中的文档数量 */
   doc_num: number;
+  /** 知识库语言 */
   language: string;
+  /** 知识库唯一标识符 */
   id: string;
+  /** 知识库名称 */
   name: string;
+  /** 解析器配置 */
   parser_config: ParserConfig;
+  /** 解析器ID */
   parser_id: string;
+  /** 管道ID */
   pipeline_id: string;
+  /** 管道名称 */
   pipeline_name: string;
+  /** 管道头像 */
   pipeline_avatar: string;
+  /** 权限设置 */
   permission: string;
+  /** 相似度阈值 */
   similarity_threshold: number;
+  /** 知识库状态 */
   status: string;
+  /** 租户ID */
   tenant_id: string;
+  /** 令牌数量 */
   token_num: number;
+  /** 更新日期（字符串格式） */
   update_date: string;
+  /** 更新时间戳 */
   update_time: number;
+  /** 向量相似度权重 */
   vector_similarity_weight: number;
+  /** 嵌入模型ID */
   embd_id: string;
+  /** 昵称 */
   nickname: string;
+  /** 操作权限级别 */
   operator_permission: number;
+  /** 知识库大小（字节） */
   size: number;
+  /** Raptor任务完成时间，可选 */
   raptor_task_finish_at?: string;
+  /** Raptor任务ID，可选 */
   raptor_task_id?: string;
+  /** 思维导图任务完成时间，可选 */
   mindmap_task_finish_at?: string;
+  /** 思维导图任务ID，可选 */
   mindmap_task_id?: string;
 }
 
+/**
+ * 知识库查询结果接口
+ * 包含知识库列表和总数
+ */
 export interface IKnowledgeResult {
+  /** 知识库列表 */
   kbs: IKnowledge[];
+  /** 知识库总数 */
   total: number;
 }
 
+/**
+ * Raptor配置接口
+ * 用于配置是否启用Raptor功能
+ */
 export interface Raptor {
+  /** 是否使用Raptor */
   use_raptor: boolean;
 }
 
+/**
+ * 解析器配置接口
+ * 定义文档解析的各种参数和选项
+ */
 export interface ParserConfig {
+  /** 起始页码，可选 */
   from_page?: number;
+  /** 结束页码，可选 */
   to_page?: number;
+  /** 自动关键词数量，可选 */
   auto_keywords?: number;
+  /** 自动问题数量，可选 */
   auto_questions?: number;
+  /** 每个文档块的令牌数量，可选 */
   chunk_token_num?: number;
+  /** 分隔符，可选 */
   delimiter?: string;
+  /** 是否将HTML转换为Excel格式，可选 */
   html4excel?: boolean;
+  /** 是否启用布局识别，可选 */
   layout_recognize?: boolean;
+  /** Raptor配置，可选 */
   raptor?: Raptor;
+  /** 标签知识库ID列表，可选 */
   tag_kb_ids?: string[];
+  /** 顶部标签数量，可选 */
   topn_tags?: number;
+  /** GraphRAG配置，可选 */
   graphrag?: { use_graphrag?: boolean };
 }
 
+/**
+ * 知识库文件解析器配置接口
+ * 定义文件解析的具体参数
+ */
 export interface IKnowledgeFileParserConfig {
+  /** 每个文档块的令牌数量 */
   chunk_token_num: number;
+  /** 是否启用布局识别 */
   layout_recognize: boolean;
+  /** 页面范围数组 */
   pages: number[][];
+  /** 任务页面大小 */
   task_page_size: number;
 }
+
+/**
+ * 知识库文件接口
+ * 定义知识库中单个文件的信息和状态
+ */
 export interface IKnowledgeFile {
+  /** 文件中的文档块数量 */
   chunk_num: number;
+  /** 创建日期（字符串格式） */
   create_date: string;
+  /** 创建时间戳 */
   create_time: number;
+  /** 创建者ID */
   created_by: string;
+  /** 文件唯一标识符 */
   id: string;
+  /** 所属知识库ID */
   kb_id: string;
+  /** 文件存储位置 */
   location: string;
+  /** 文件名称 */
   name: string;
+  /** 解析器ID */
   parser_id: string;
+  /** 处理开始时间，可选 */
   process_begin_at?: any;
+  /** 处理持续时间 */
   process_duration: number;
-  progress: number; // parsing process
-  progress_msg: string; // parsing log
-  run: RunningStatus; // parsing status
+  /** 解析进度百分比 */
+  progress: number;
+  /** 解析进度消息 */
+  progress_msg: string;
+  /** 解析运行状态 */
+  run: RunningStatus;
+  /** 文件大小（字节） */
   size: number;
+  /** 文件来源类型 */
   source_type: string;
-  status: string; // enabled
-  thumbnail?: any; // base64
+  /** 文件状态（启用/禁用） */
+  status: string;
+  /** 文件缩略图（base64编码），可选 */
+  thumbnail?: any;
+  /** 文件中的令牌数量 */
   token_num: number;
+  /** 文件类型 */
   type: string;
+  /** 更新日期（字符串格式） */
   update_date: string;
+  /** 更新时间戳 */
   update_time: number;
+  /** 解析器配置 */
   parser_config: IKnowledgeFileParserConfig;
 }
 
+/**
+ * 租户信息接口
+ * 定义租户的各种服务配置
+ */
 export interface ITenantInfo {
+  /** 自动语音识别服务ID */
   asr_id: string;
+  /** 嵌入模型服务ID */
   embd_id: string;
+  /** 图像转文本服务ID */
   img2txt_id: string;
+  /** 大语言模型服务ID */
   llm_id: string;
+  /** 租户名称 */
   name: string;
+  /** 解析器ID列表 */
   parser_ids: string;
+  /** 租户角色 */
   role: string;
+  /** 租户ID */
   tenant_id: string;
+  /** 聊天服务ID */
   chat_id: string;
+  /** 语音转文本服务ID */
   speech2text_id: string;
+  /** 文本转语音服务ID */
   tts_id: string;
 }
 
+/**
+ * 文档块接口
+ * 定义知识库中单个文档块的信息
+ */
 export interface IChunk {
-  available_int: number; // Whether to enable, 0: not enabled, 1: enabled
+  /** 是否启用，0：未启用，1：启用 */
+  available_int: number;
+  /** 文档块唯一标识符 */
   chunk_id: string;
+  /** 带权重的内容 */
   content_with_weight: string;
+  /** 所属文档ID */
   doc_id: string;
+  /** 所属文档名称 */
   doc_name: string;
+  /** 关联图像ID */
   image_id: string;
+  /** 重要关键词列表，可选 */
   important_kwd?: string[];
-  question_kwd?: string[]; // keywords
+  /** 问题关键词列表，可选 */
+  question_kwd?: string[];
+  /** 标签关键词列表，可选 */
   tag_kwd?: string[];
+  /** 位置信息数组 */
   positions: number[][];
+  /** 标签特征映射，可选 */
   tag_feas?: Record<string, number>;
 }
 
+/**
+ * 测试文档块接口
+ * 用于知识库测试和检索的文档块信息
+ */
 export interface ITestingChunk {
+  /** 文档块唯一标识符 */
   chunk_id: string;
+  /** 内容的LTKS表示 */
   content_ltks: string;
+  /** 带权重的内容 */
   content_with_weight: string;
+  /** 所属文档ID */
   doc_id: string;
+  /** 所属文档名称 */
   doc_name: string;
+  /** 图像ID（旧字段） */
   img_id: string;
+  /** 图像ID */
   image_id: string;
+  /** 重要关键词列表 */
   important_kwd: any[];
+  /** 所属知识库ID */
   kb_id: string;
+  /** 相似度分数 */
   similarity: number;
+  /** 词汇相似度分数 */
   term_similarity: number;
+  /** 向量表示 */
   vector: number[];
+  /** 向量相似度分数 */
   vector_similarity: number;
+  /** 高亮显示的内容 */
   highlight: string;
+  /** 位置信息数组 */
   positions: number[][];
+  /** 文档名称关键词 */
   docnm_kwd: string;
+  /** 文档类型关键词 */
   doc_type_kwd: string;
 }
 
+/**
+ * 测试文档接口
+ * 用于知识库测试的文档统计信息
+ */
 export interface ITestingDocument {
+  /** 文档中的块数量 */
   count: number;
+  /** 文档ID */
   doc_id: string;
+  /** 文档名称 */
   doc_name: string;
 }
 
+/**
+ * 测试结果接口
+ * 知识库测试的完整结果
+ */
 export interface ITestingResult {
+  /** 匹配的文档块列表 */
   chunks: ITestingChunk[];
+  /** 匹配的文档列表 */
   documents: ITestingDocument[];
+  /** 总匹配数量 */
   total: number;
+  /** 标签统计，可选 */
   labels?: Record<string, number>;
 }
 
+/**
+ * 下一代测试结果接口
+ * 改进版本的知识库测试结果
+ */
 export interface INextTestingResult {
+  /** 匹配的文档块列表 */
   chunks: ITestingChunk[];
+  /** 文档聚合统计 */
   doc_aggs: ITestingDocument[];
+  /** 总匹配数量 */
   total: number;
+  /** 标签统计，可选 */
   labels?: Record<string, number>;
+  /** 是否已运行，可选 */
   isRuned?: boolean;
 }
 
-export type IRenameTag = { fromTag: string; toTag: string };
+/**
+ * 重命名标签类型
+ * 用于标签重命名操作
+ */
+export type IRenameTag = { 
+  /** 原标签名 */
+  fromTag: string; 
+  /** 新标签名 */
+  toTag: string; 
+};
 
+/**
+ * 知识图谱接口
+ * 定义知识库的图谱结构
+ */
 export interface IKnowledgeGraph {
+  /** 图谱数据结构 */
   graph: Record<string, any>;
+  /** 思维导图数据（已注释） */
   // mind_map: TreeData;
 }

src/interfaces/database/plugin.ts

@@ -1,13 +1,31 @@
+/**
+ * LLM工具集合类型
+ * 定义大语言模型可用工具的元数据数组
+ */
 export type ILLMTools = ILLMToolMetadata[];
 
+/**
+ * LLM工具元数据接口
+ * 定义单个LLM工具的基本信息和参数
+ */
 export interface ILLMToolMetadata {
+    /** 工具名称（内部标识符） */
     name: string;
+    /** 工具显示名称（用户界面显示） */
     displayName: string;
+    /** 工具显示描述（用户界面显示的功能说明） */
     displayDescription: string;
+    /** 工具参数映射，键为参数名，值为参数配置 */
     parameters: Map<string, ILLMToolParameter>;
 }
 
+/**
+ * LLM工具参数接口
+ * 定义工具参数的类型和描述信息
+ */
 export interface ILLMToolParameter {
+    /** 参数类型（如：string、number、boolean等） */
     type: string;
+    /** 参数显示描述（用户界面显示的参数说明） */
     displayDescription: string;
 }

src/interfaces/database/system.ts

@@ -1,7 +1,17 @@
+/**
+ * Langfuse配置接口
+ * 定义Langfuse服务的连接和认证配置
+ * Langfuse是一个用于LLM应用的可观测性平台
+ */
 export interface ILangfuseConfig {
+  /** 密钥，用于API认证 */
   secret_key: string;
+  /** 公钥，用于客户端认证 */
   public_key: string;
+  /** 服务主机地址 */
   host: string;
+  /** 项目ID */
   project_id: string;
+  /** 项目名称 */
   project_name: string;
 }

src/interfaces/database/user-setting.ts

@@ -1,96 +1,204 @@
+/**
+ * 用户信息接口
+ * 定义用户的基本信息和配置
+ */
 export interface IUserInfo {
+  /** 访问令牌 */
   access_token: string;
+  /** 用户头像，可选字段 */
   avatar?: any;
+  /** 颜色主题方案 */
   color_schema: string;
+  /** 创建日期（字符串格式） */
   create_date: string;
+  /** 创建时间戳 */
   create_time: number;
+  /** 用户邮箱 */
   email: string;
+  /** 用户唯一标识符 */
   id: string;
+  /** 是否激活状态 */
   is_active: string;
+  /** 是否匿名用户 */
   is_anonymous: string;
+  /** 是否已认证 */
   is_authenticated: string;
+  /** 是否超级用户 */
   is_superuser: boolean;
+  /** 用户语言设置 */
   language: string;
+  /** 最后登录时间 */
   last_login_time: string;
+  /** 登录渠道 */
   login_channel: string;
+  /** 用户昵称 */
   nickname: string;
+  /** 用户密码 */
   password: string;
+  /** 用户状态 */
   status: string;
+  /** 时区设置 */
   timezone: string;
+  /** 更新日期（字符串格式） */
   update_date: string;
+  /** 更新时间戳 */
   update_time: number;
 }
 
+/**
+ * 任务执行器耗时统计类型
+ * 记录各个任务执行器的耗时数据
+ */
 export type TaskExecutorElapsed = Record<string, number[]>;
 
+/**
+ * 任务执行器心跳项接口
+ * 定义任务执行器的运行状态信息
+ */
 export interface TaskExecutorHeartbeatItem {
+  /** 启动时间 */
   boot_at: string;
+  /** 当前任务，通常为null */
   current: null;
+  /** 已完成任务数 */
   done: number;
+  /** 失败任务数 */
   failed: number;
+  /** 延迟时间 */
   lag: number;
+  /** 执行器名称 */
   name: string;
+  /** 当前时间 */
   now: string;
+  /** 待处理任务数 */
   pending: number;
 }
 
+/**
+ * 系统状态接口
+ * 定义系统各个组件的运行状态
+ */
 export interface ISystemStatus {
+  /** Elasticsearch状态 */
   es: Es;
+  /** 存储系统状态 */
   storage: Storage;
+  /** 数据库状态 */
   database: Database;
+  /** Redis状态 */
   redis: Redis;
+  /** 任务执行器心跳信息 */
   task_executor_heartbeat: Record<string, TaskExecutorHeartbeatItem[]>;
 }
 
+/**
+ * Redis状态接口
+ * 定义Redis服务的状态信息
+ */
 interface Redis {
+  /** 服务状态 */
   status: string;
+  /** 响应耗时 */
   elapsed: number;
+  /** 错误信息 */
   error: string;
+  /** 待处理任务数 */
   pending: number;
 }
 
+/**
+ * 存储系统状态接口
+ * 定义存储服务的状态信息
+ */
 export interface Storage {
+  /** 服务状态 */
   status: string;
+  /** 响应耗时 */
   elapsed: number;
+  /** 错误信息 */
   error: string;
 }
 
+/**
+ * 数据库状态接口
+ * 定义数据库服务的状态信息
+ */
 export interface Database {
+  /** 服务状态 */
   status: string;
+  /** 响应耗时 */
   elapsed: number;
+  /** 错误信息 */
   error: string;
 }
 
+/**
+ * Elasticsearch状态接口
+ * 定义Elasticsearch服务的状态信息
+ */
 interface Es {
+  /** 服务状态 */
   status: string;
+  /** 响应耗时 */
   elapsed: number;
+  /** 错误信息 */
   error: string;
+  /** 节点数量 */
   number_of_nodes: number;
+  /** 活跃分片数 */
   active_shards: number;
 }
 
+/**
+ * 租户用户接口
+ * 定义租户下用户的信息
+ */
 export interface ITenantUser {
+  /** 用户ID */
   id: string;
+  /** 用户头像 */
   avatar: string;
+  /** 时间差（秒） */
   delta_seconds: number;
+  /** 用户邮箱 */
   email: string;
+  /** 是否激活状态 */
   is_active: string;
+  /** 是否匿名用户 */
   is_anonymous: string;
+  /** 是否已认证 */
   is_authenticated: string;
+  /** 是否超级用户 */
   is_superuser: boolean;
+  /** 用户昵称 */
   nickname: string;
+  /** 用户角色 */
   role: string;
+  /** 用户状态 */
   status: string;
+  /** 更新日期 */
   update_date: string;
+  /** 关联的用户ID */
   user_id: string;
 }
 
+/**
+ * 租户接口
+ * 定义租户的基本信息
+ */
 export interface ITenant {
+  /** 租户头像 */
   avatar: string;
+  /** 时间差（秒） */
   delta_seconds: number;
+  /** 租户邮箱 */
   email: string;
+  /** 租户昵称 */
   nickname: string;
+  /** 租户角色 */
   role: string;
+  /** 租户ID */
   tenant_id: string;
+  /** 更新日期 */
   update_date: string;
 }