+ {
items?: T[];
}
interface CustomSelectProps extends Omit {
+ /** API endpoint URL to fetch options */
url: string;
+ /** Query parameters for the API request */
params?: Record;
+ /** Key name for option value in response data */
valueKey?: string;
+ /** Key name for option label in response data */
labelKey?: string;
+ /** Placeholder text for the select */
placeholder?: string;
+ /** Whether to show "All" option */
hasAll?: boolean;
+ /** Custom text for "All" option */
allTitle?: string;
+ /** Function to format/transform the options data */
format?: (items: OptionType[]) => OptionType[];
+ /** Whether to enable search functionality */
showSearch?: boolean;
+ /** Property name to filter options by */
optionFilterProp?: string;
+ /** Custom filter function for search */
filterOption?: (inputValue: string, option?: DefaultOptionType) => boolean;
}
+// Default filter function for search - performs case-insensitive substring matching
const defaultFilterOption = (inputValue: string, option?: DefaultOptionType): boolean => {
if (!option || !inputValue) return true;
const label = String(option.children || option.label || '');
@@ -47,8 +77,10 @@ const CustomSelect: FC = ({
}) => {
const { t } = useTranslation();
const [options, setOptions] = useState([]);
+ // Memoize params to prevent unnecessary re-fetches
const memoizedParams = useMemo(() => params, [JSON.stringify(params)]);
+ // Fetch options from API when url or params change
useEffect(() => {
request.get>(url, memoizedParams).then((res) => {
const data = Array.isArray(res) ? res : res?.items || [];
@@ -56,6 +88,7 @@ const CustomSelect: FC = ({
});
}, [url, memoizedParams]);
+ // Apply custom format function if provided
const displayOptions = format ? format(options) : options;
return (
@@ -66,7 +99,9 @@ const CustomSelect: FC = ({
filterOption={filterOption || defaultFilterOption}
{...props}
>
+ {/* Optional "All" option for selecting all items */}
{hasAll && {allTitle || t('common.all')} }
+ {/* Render options from API data */}
{displayOptions.map((option) => (
{String(option[labelKey])}
diff --git a/web/src/components/Empty/BodyWrapper.tsx b/web/src/components/Empty/BodyWrapper.tsx
index 9cdeb0e8..22bd226a 100644
--- a/web/src/components/Empty/BodyWrapper.tsx
+++ b/web/src/components/Empty/BodyWrapper.tsx
@@ -1,19 +1,41 @@
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:02:47
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:47:24
+ */
+/**
+ * BodyWrapper Component
+ *
+ * A wrapper component that conditionally renders loading, empty, or content states.
+ * Simplifies state management for data-driven components.
+ *
+ * @component
+ */
+
import type { FC, ReactNode } from 'react'
+
import PageEmpty from './PageEmpty'
import PageLoading from './PageLoading'
interface BodyWrapperProps {
+ /** Content to render when not loading or empty */
children: ReactNode
+ /** Whether to show loading state */
loading?: boolean
+ /** Whether the content is empty */
empty: boolean
}
const BodyWrapper: FC = ({ children, loading = false, empty }) => {
+ // Show loading spinner while data is being fetched
if (loading) {
return {
+
+/**
+ * @param size - Icon size in pixels - single number or [width, height] array (default: [240, 210])
+ */
+const PageEmpty: FC<{ size?: number | number[] }> = ({ size = [240, 210] }) => {
const { t } = useTranslation()
return (
{
+
+/**
+ * @param size - Icon size in pixels - single number or [width, height] array (default: [240, 210])
+ */
+const PageLoading: FC<{ size?: number | number[] }> = ({ size = [240, 210] }) => {
const { t } = useTranslation()
return (
= ({
@@ -19,14 +41,19 @@ const Empty: FC = ({
className = '',
}) => {
const { t } = useTranslation();
+ // Calculate width and height from size prop (supports single value or [width, height] array)
const width = Array.isArray(size) ? size[0] : size ? size : url ? 200 : 88;
const height = Array.isArray(size) ? size[1] : size ? size : url ? 200 : 88;
+ // Use custom subtitle or default translation if subtitle is needed
const curSubTitle = isNeedSubTitle ? (subTitle || t('empty.tableEmpty')) : null;
return (
+ {/* Display unchecked icon when not checked */}
{icon && !checked && 
}
+ {/* Display checked icon when checked */}
{checkedIcon && checked && 
}
{children}
diff --git a/web/src/components/CustomSelect/index.tsx b/web/src/components/CustomSelect/index.tsx
index f93014c9..ea5ca718 100644
--- a/web/src/components/CustomSelect/index.tsx
+++ b/web/src/components/CustomSelect/index.tsx
@@ -1,31 +1,61 @@
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:02:17
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:46:29
+ */
+/**
+ * CustomSelect - A select component that fetches options from an API
+ *
+ * This component extends Ant Design's Select with automatic data fetching,
+ * search functionality, and customizable option formatting.
+ *
+ * @component
+ */
+
import { useEffect, useState, useMemo, type FC, type Key } from 'react';
import { Select } from 'antd';
import type { SelectProps, DefaultOptionType } from 'antd/es/select';
import { useTranslation } from 'react-i18next';
+
import { request } from '@/utils/request';
+// Generic option type for API response data
interface OptionType {
[key: string]: Key | string | number;
}
+// API response structure
interface ApiResponse
+ {/* Empty state icon */}
+ {/* Optional title */}
{title &&
);
diff --git a/web/src/components/FormItem/DescWrapper.tsx b/web/src/components/FormItem/DescWrapper.tsx
index 300fc2b6..5060b588 100644
--- a/web/src/components/FormItem/DescWrapper.tsx
+++ b/web/src/components/FormItem/DescWrapper.tsx
@@ -1,6 +1,25 @@
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:05:16
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:05:16
+ */
+/**
+ * DescWrapper Component
+ *
+ * A styled wrapper for displaying description text in forms.
+ * Provides consistent typography and styling for form field descriptions.
+ *
+ * @component
+ */
+
import clsx from "clsx";
import type { FC, ReactNode } from "react";
+/**
+ * @param desc - Description content (string or React node)
+ * @param className - Additional CSS classes for customization
+ */
const DescWrapper: FC<{desc: string | ReactNode, className?: string}> = ({desc, className}) => {
return (
{title}
}
+ {/* Optional subtitle with conditional styling */}
{curSubTitle && {curSubTitle}
}
diff --git a/web/src/components/FormItem/LabelWrapper.tsx b/web/src/components/FormItem/LabelWrapper.tsx
index 461250d8..d608462b 100644
--- a/web/src/components/FormItem/LabelWrapper.tsx
+++ b/web/src/components/FormItem/LabelWrapper.tsx
@@ -1,9 +1,30 @@
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:05:41
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:05:41
+ */
+/**
+ * LabelWrapper Component
+ *
+ * A styled wrapper for displaying form field labels with optional child content.
+ * Provides consistent typography and layout for form labels.
+ *
+ * @component
+ */
+
import clsx from "clsx";
import type { FC, ReactNode } from "react";
+/**
+ * @param title - Label text or React node to display
+ * @param className - Additional CSS classes for customization
+ * @param children - Optional child content to render below the label
+ */
const LabelWrapper: FC<{ title: string | ReactNode, className?: string; children?: ReactNode}> = ({title, className, children}) => {
return (
= ({
className,
disabled
}) => {
- const componentSize = useSize()
- console.log('componentSize', componentSize)
-
return (
+ {/* Label title with consistent styling */}
diff --git a/web/src/components/FormItem/SwitchFormItem.tsx b/web/src/components/FormItem/SwitchFormItem.tsx
index e17a8728..8ac52f98 100644
--- a/web/src/components/FormItem/SwitchFormItem.tsx
+++ b/web/src/components/FormItem/SwitchFormItem.tsx
@@ -1,17 +1,36 @@
-import { Switch, Form, ConfigProvider } from "antd";
-import useSize from 'antd/lib/config-provider/hooks/useSize'
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:06:24
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:50:49
+ */
+/**
+ * SwitchFormItem Component
+ *
+ * A form item component that combines a switch control with a label and optional description.
+ * Provides a consistent layout for switch-based form fields.
+ *
+ * @component
+ */
+
+import { Switch, Form } from "antd";
import type { FC, ReactNode } from "react";
-import { useContext } from "react";
import LabelWrapper from './LabelWrapper'
import DescWrapper from './DescWrapper'
interface SwitchFormItemProps {
+ /** Label text or React node */
title: string | ReactNode;
+ /** Optional description text or React node */
desc?: string | ReactNode;
+ /** Form field name (string or nested path array) */
name: string | string[];
+ /** Switch size */
size?: 'small' | 'default'
+ /** Additional CSS classes */
className?: string;
+ /** Whether the switch is disabled */
disabled?: boolean;
}
@@ -23,14 +42,13 @@ const SwitchFormItem: FC{title}
{children}
+ {/* Label and description section */}
{desc &&
+ {/* Switch control */}
void;
+ /** Close the settings modal */
handleClose: () => void;
}
+/** Settings modal component for language and timezone configuration */
const SettingModal = forwardRef((_props, ref) => {
const { t } = useTranslation();
const { changeLanguage, language, timeZone, changeTimeZone } = useI18n()
const [visible, setVisible] = useState(false);
const [form] = Form.useForm();
- const values = Form.useWatch([], form);
-
- // 封装取消方法，添加关闭弹窗逻辑
+ /** Close modal and reset form to initial state */
const handleClose = () => {
setVisible(false);
form.resetFields();
};
+ /** Open modal and populate form with current settings */
const handleOpen = () => {
form.setFieldsValue({ language, timeZone })
setVisible(true);
};
- // 封装保存方法，添加提交逻辑
+
+ /** Validate and save settings, update language and timezone if changed */
const handleSave = () => {
form
.validateFields()
- .then(() => {
+ .then((values) => {
const { language: newLanguage, timeZone: newTimeZone } = values
if (newLanguage !== language) {
changeLanguage(newLanguage);
@@ -47,11 +67,12 @@ const SettingModal = forwardRef((_props, ref) => {
});
}
- // 暴露给父组件的方法
+ /** Expose handleOpen and handleClose methods to parent component via ref */
useImperativeHandle(ref, () => ({
handleOpen,
handleClose
}));
+
return (
((_props, ref) => {
form={form}
layout="vertical"
>
- {/* 中英文切换 */}
+ {/* Language selection dropdown */}
((_props, ref) => {
options={['zh', 'en'].map(key => ({ label: t(`header.${key}`), value: key }))}
/>
- {/* 时区切换 */}
+ {/* Timezone selection dropdown */}
void;
+ /** Close the user info modal */
handleClose: () => void;
}
+/** User information modal component displaying user details and security settings */
const UserInfoModal = forwardRef((_props, ref) => {
const { t } = useTranslation();
const resetPasswordModalRef = useRef(null)
const { user } = useUser();
const [visible, setVisible] = useState(false);
- // 封装取消方法，添加关闭弹窗逻辑
+ /** Close the modal */
const handleClose = () => {
setVisible(false);
};
+ /** Open the modal */
const handleOpen = () => {
setVisible(true);
};
- // 暴露给父组件的方法
+ /** Expose handleOpen and handleClose methods to parent component via ref */
useImperativeHandle(ref, () => ({
handleOpen,
handleClose
}));
+
return (
((_props, ref) => {
onCancel={handleClose}
footer={null}
>
+ {/* Basic Information Section */}
{t('header.basicInfo')}
-
+ {/* Username */}
+
{t('user.username')}
{user.username}
-
+ {/* Email */}
+
{t('user.email')}
{user.email}
-
+ {/* Role */}
+
{t('user.role')}
{user.is_superuser ? t('user.superuser') : t('user.normalUser')}
-
+ {/* Created Date */}
+
{t('user.createdAt')}
{formatDateTime(user.created_at, 'YYYY-MM-DD HH:mm:ss')}
- {t('header.securitySettings')}
+
+ {/* Security Settings Section */}
+ {t('header.securitySettings')}
-
-
+ {/* Password Change Card */}
+
+
+ {/* Breadcrumb navigation */}
- {/* */}
-
- {/* 用户信息下拉菜单 */}
-
-
-
+ {/* User info dropdown menu */}
+
+
+ {/* Sidebar navigation */}
+ {/* Header with breadcrumbs and user menu */}
diff --git a/web/src/components/Layout/AuthSpaceLayout.tsx b/web/src/components/Layout/AuthSpaceLayout.tsx
index 17ee0bac..d47f13f2 100644
--- a/web/src/components/Layout/AuthSpaceLayout.tsx
+++ b/web/src/components/Layout/AuthSpaceLayout.tsx
@@ -1,6 +1,26 @@
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:11:43
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:11:43
+ */
+/**
+ * AuthSpaceLayout Component
+ *
+ * The authenticated layout wrapper for knowledge base (space) pages that provides:
+ * - Route authentication and permission checks for space context
+ * - Automatic breadcrumb navigation updates
+ * - Sidebar navigation and header configured for space mode
+ * - Token-based authentication validation
+ * - Storage type initialization
+ *
+ * @component
+ */
+
import { Outlet } from 'react-router-dom';
import { useEffect, type FC } from 'react';
import { Layout } from 'antd';
+
import useRouteGuard from '@/hooks/useRouteGuard';
import { useNavigationBreadcrumbs } from '@/hooks/useNavigationBreadcrumbs';
import AppHeader from '@/components/Header';
@@ -11,28 +31,38 @@ import { cookieUtils } from '@/utils/request';
const { Content } = Layout;
-// 认证布局组件，使用useRouteGuard hook进行路由鉴权
+/**
+ * Authentication layout component for knowledge base (space) pages.
+ * Similar to AuthLayout but configured for space context with storage type management.
+ */
const AuthSpaceLayout: FC = () => {
const { getUserInfo, getStorageType } = useUser();
- // 使用路由守卫hook处理认证和权限检查
+
+ // Use route guard hook to handle authentication and permission checks for space context
useRouteGuard('space');
- // 自动更新面包屑导航
+
+ // Automatically update breadcrumb navigation based on current route in space context
useNavigationBreadcrumbs('space');
+
+ // Check authentication token, fetch user info and storage type on mount
useEffect(() => {
const authToken = cookieUtils.get('authToken')
if (!authToken && !window.location.hash.includes('#/login')) {
window.location.href = `/#/login`;
} else {
getUserInfo()
- getStorageType()
+ getStorageType() // Fetch storage type for knowledge base operations
}
}, []);
return (
+ {/* Sidebar navigation configured for space mode */}
+ {/* Header with breadcrumbs and user menu configured for space mode */}
diff --git a/web/src/components/Layout/BasicLayout.tsx b/web/src/components/Layout/BasicLayout.tsx
index 6b3d2904..cadcafb2 100644
--- a/web/src/components/Layout/BasicLayout.tsx
+++ b/web/src/components/Layout/BasicLayout.tsx
@@ -1,12 +1,35 @@
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:12:42
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:12:42
+ */
+/**
+ * BasicLayout Component
+ *
+ * A minimal layout wrapper that provides:
+ * - User information initialization
+ * - Storage type initialization
+ * - Simple container for child routes without navigation UI
+ *
+ * Used for pages that don't require sidebar/header (e.g., login, public pages).
+ *
+ * @component
+ */
+
import { Outlet } from 'react-router-dom';
import { useEffect, type FC } from 'react';
+
import { useUser } from '@/store/user';
-// 基础布局组件，用于展示内容并保留用户信息获取功能
+/**
+ * Basic layout component for pages without navigation UI.
+ * Fetches user info and storage type on mount, then renders child routes.
+ */
const BasicLayout: FC = () => {
const { getUserInfo, getStorageType } = useUser();
- // 获取用户信息
+ // Fetch user information and storage type on component mount
useEffect(() => {
getUserInfo();
getStorageType()
@@ -14,6 +37,7 @@ const BasicLayout: FC = () => {
return (
-
{t('header.changePassword')}
- {t('header.changePasswordDesc')}
+ {t('header.changePassword')}
+ {t('header.changePasswordDesc')}
{user.username}
- {user.username}
+
+ {/* Render child routes without additional UI */}
)
diff --git a/web/src/components/Layout/LayoutBg.tsx b/web/src/components/Layout/LayoutBg.tsx
index 2cddfb62..ec76f196 100644
--- a/web/src/components/Layout/LayoutBg.tsx
+++ b/web/src/components/Layout/LayoutBg.tsx
@@ -1,13 +1,37 @@
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:13:20
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:13:20
+ */
+/**
+ * LayoutBg Component
+ *
+ * A decorative background component that displays styled background elements.
+ * Provides visual aesthetics with positioned decorative shapes.
+ *
+ * @component
+ */
+
import { type FC } from 'react';
import clsx from 'clsx';
+
import styles from './layout.module.css';
+/**
+ * Background layout component with decorative elements.
+ * Renders a fixed full-screen background with styled shapes.
+ */
const LayoutBg: FC = () => {
return (
- = (props) => {
- // console.log('AudioBlock', props)
const { children } = props.node;
+ /** Extract audio source URLs from node children and filter out empty values */
const srcs = children.map(item => item.properties?.src).filter(item => item)
return (
diff --git a/web/src/components/Markdown/Code.tsx b/web/src/components/Markdown/Code.tsx
index de60d0de..9aecd977 100644
--- a/web/src/components/Markdown/Code.tsx
+++ b/web/src/components/Markdown/Code.tsx
@@ -1,22 +1,45 @@
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:15:05
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:15:05
+ */
+/**
+ * Code Component
+ *
+ * A versatile code rendering component that supports:
+ * - Syntax-highlighted code blocks
+ * - ECharts visualizations
+ * - SVG rendering
+ * - Mermaid diagrams
+ * - Inline code snippets
+ *
+ * @component
+ */
+
import { type FC, useMemo } from 'react'
import SyntaxHighlighter from 'react-syntax-highlighter';
import { atelierHeathLight } from 'react-syntax-highlighter/dist/esm/styles/hljs';
-import CopyBtn from './CopyBtn';
import ReactEcharts from 'echarts-for-react';
+
+import CopyBtn from './CopyBtn';
import Svg from './Svg'
import MermaidChart from './MermaidChart'
-
+/** Props interface for Code component */
type ICodeProps = {
children: string;
className: string;
}
+/** Code block component that renders syntax-highlighted code or special visualizations */
const Code: FC = (props) => {
const { children, className } = props;
+ /** Extract language from className (e.g., 'language-javascript' -> 'javascript') */
const language = className?.split('-')[1]
console.log('Code', props)
+ // Parse ECharts configuration from code content
const charData = useMemo(() => {
if (language !== 'echarts') return null;
try {
@@ -27,6 +50,7 @@ const Code: FC = (props) => {
}
}, [language, children])
+ // Render ECharts visualization
if (language === 'echarts') {
return (
= (props) => {
)
}
+ // Render SVG content
if (language === 'svg') {
return (
+ {/* Top section with decorative background shapes */}
+
diff --git a/web/src/components/Layout/LoginLayout.tsx b/web/src/components/Layout/LoginLayout.tsx
index ee49e98f..b3c3b8e6 100644
--- a/web/src/components/Layout/LoginLayout.tsx
+++ b/web/src/components/Layout/LoginLayout.tsx
@@ -1,11 +1,30 @@
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:13:38
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:13:38
+ */
+/**
+ * LoginLayout Component
+ *
+ * A minimal layout wrapper for authentication pages (login, register, etc.).
+ * Provides a simple container without navigation UI or authentication checks.
+ *
+ * @component
+ */
+
import { Outlet } from 'react-router-dom';
import { type FC } from 'react';
-// 基础布局组件，用于展示内容并保留用户信息获取功能
+/**
+ * Login layout component for unauthenticated pages.
+ * Renders child routes in a simple full-size container.
+ */
const LoginLayout: FC = () => {
return (
+ {/* Left decorative element 1 */}
+ {/* Left decorative element 2 */}
+ {/* Right decorative element */}
+ {/* Render authentication pages (login, register, etc.) */}
)
diff --git a/web/src/components/Layout/NoAuthLayout.tsx b/web/src/components/Layout/NoAuthLayout.tsx
index a2e6f274..2e6154cf 100644
--- a/web/src/components/Layout/NoAuthLayout.tsx
+++ b/web/src/components/Layout/NoAuthLayout.tsx
@@ -1,11 +1,30 @@
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:13:55
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:52:17
+ */
+/**
+ * NoAuthLayout Component
+ *
+ * A minimal layout wrapper for public pages that don't require authentication.
+ * Provides a simple container without navigation UI or authentication checks.
+ *
+ * @component
+ */
+
import { Outlet } from 'react-router-dom';
import { type FC } from 'react';
-// 基础布局组件，用于展示内容并保留用户信息获取功能
+/**
+ * No-authentication layout component for public pages.
+ * Renders child routes in a simple full-size container without any auth requirements.
+ */
const NoAuthLayout: FC = () => {
return (
+ {/* Render public pages without authentication */}
)
diff --git a/web/src/components/Markdown/AudioBlock.tsx b/web/src/components/Markdown/AudioBlock.tsx
index bd638816..75039d61 100644
--- a/web/src/components/Markdown/AudioBlock.tsx
+++ b/web/src/components/Markdown/AudioBlock.tsx
@@ -1,15 +1,31 @@
-import { memo } from 'react'
+/*
+ * @Author: ZhaoYing
+ * @Date: 2026-02-02 15:14:59
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:14:59
+ */
+/**
+ * AudioBlock Component
+ *
+ * Renders audio elements from markdown nodes.
+ * Extracts audio source URLs and creates HTML audio players with controls.
+ *
+ * @component
+ */
-import type { FC } from 'react'
+import { memo, type FC } from 'react'
+/** Props interface for AudioBlock component */
interface AudioBlockProps {
node: {
children: { properties: { src: string } }[]
}
}
+
+/** Audio block component that renders audio elements from markdown nodes */
const AudioBlock: FC