docs: add comments to the src/components directory

2026-02-02 16:14:39 +08:00
parent 9a38e8a4a0
commit a191e32f71
55 changed files with 1417 additions and 375 deletions
--- a/web/src/components/Header/SettingModal.tsx
+++ b/web/src/components/Header/SettingModal.tsx
@@ -1,3 +1,18 @@
+/*
+ * @Author: ZhaoYing 
+ * @Date: 2026-02-02 15:08:58 
+ * @Last Modified by:   ZhaoYing 
+ * @Last Modified time: 2026-02-02 15:08:58 
+ */
+/**
+ * SettingModal Component
+ * 
+ * A modal dialog for configuring application settings including language and timezone.
+ * Uses forwardRef to expose open/close methods to parent components.
+ * 
+ * @component
+ */
+
 import { forwardRef, useImperativeHandle, useState } from 'react';
 import { Form, Select } from 'antd';
 import { useTranslation } from 'react-i18next';
@@ -7,34 +22,39 @@ import { useI18n } from '@/store/locale'
 import { timezones } from '@/utils/timezones'

 const FormItem = Form.Item;
+
+/** Interface for SettingModal ref methods exposed to parent components */
 export interface SettingModalRef {
+  /** Open the settings modal */
  handleOpen: () => void;
+  /** Close the settings modal */
  handleClose: () => void;
 }

+/** Settings modal component for language and timezone configuration */
 const SettingModal = forwardRef<SettingModalRef>((_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<SettingModalRef>((_props, ref) => {
      });
  }

-  // 暴露给父组件的方法
+  /** Expose handleOpen and handleClose methods to parent component via ref */
  useImperativeHandle(ref, () => ({
    handleOpen,
    handleClose
  }));
+  
  return (
    <RbModal
      title={t('header.setting')}
@@ -64,7 +85,7 @@ const SettingModal = forwardRef<SettingModalRef>((_props, ref) => {
        form={form}
        layout="vertical"
      >
-        {/* 中英文切换 */}
+        {/* Language selection dropdown */}
        <FormItem
          name="language"
          label={t('header.language')}
@@ -73,7 +94,7 @@ const SettingModal = forwardRef<SettingModalRef>((_props, ref) => {
            options={['zh', 'en'].map(key => ({ label: t(`header.${key}`), value: key }))}
          />
        </FormItem>
-        {/* 时区切换 */}
+        {/* Timezone selection dropdown */}
        <FormItem
          name="timeZone"
          label={t('header.timeZone')}
--- a/web/src/components/Header/UserInfoModal.tsx
+++ b/web/src/components/Header/UserInfoModal.tsx
@@ -1,39 +1,61 @@
+/*
+ * @Author: ZhaoYing 
+ * @Date: 2026-02-02 15:09:47 
+ * @Last Modified by: ZhaoYing
+ * @Last Modified time: 2026-02-02 15:51:54
+ */
+/**
+ * UserInfoModal Component
+ * 
+ * A modal dialog that displays user profile information and security settings.
+ * Includes basic user details and password change functionality.
+ * Uses forwardRef to expose open/close methods to parent components.
+ * 
+ * @component
+ */
+
 import { forwardRef, useImperativeHandle, useState, useRef } from 'react';
 import { Button } from 'antd';
 import { UnlockOutlined } from '@ant-design/icons';
 import { useTranslation } from 'react-i18next';
-import { useUser } from '@/store/user';

+import { useUser } from '@/store/user';
 import RbModal from '@/components/RbModal'
 import { formatDateTime } from '@/utils/format';
 import ResetPasswordModal from '@/views/UserManagement/components/ResetPasswordModal'
 import type { ResetPasswordModalRef } from '@/views/UserManagement/types'

+/** Interface for UserInfoModal ref methods exposed to parent components */
 export interface UserInfoModalRef {
+  /** Open the user info modal */
  handleOpen: () => void;
+  /** Close the user info modal */
  handleClose: () => void;
 }

+/** User information modal component displaying user details and security settings */
 const UserInfoModal = forwardRef<UserInfoModalRef>((_props, ref) => {
  const { t } = useTranslation();
  const resetPasswordModalRef = useRef<ResetPasswordModalRef>(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 (
    <RbModal
      title={t('header.userInfo')}
@@ -41,32 +63,40 @@ const UserInfoModal = forwardRef<UserInfoModalRef>((_props, ref) => {
      onCancel={handleClose}
      footer={null}
    >
+      {/* Basic Information Section */}
      <div className="rb:text-[#5B6167] rb:font-medium">{t('header.basicInfo')}</div>

-      <div className="rb:flex rb:justify-between rb:text-[#5B6167] rb:text-[14px] rb:leading-[20px] rb:mb-[12px] rb:mt-[12px]">
+      {/* Username */}
+      <div className="rb:flex rb:justify-between rb:text-[#5B6167] rb:text-[14px] rb:leading-5 rb:mb-3 rb:mt-3">
        <span className="rb:whitespace-nowrap">{t('user.username')}</span>
        <span className="rb:text-[#212332]">{user.username}</span>
      </div>
-      <div className="rb:flex rb:justify-between rb:text-[#5B6167] rb:text-[14px] rb:leading-[20px] rb:mb-[12px]">
+      {/* Email */}
+      <div className="rb:flex rb:justify-between rb:text-[#5B6167] rb:text-[14px] rb:leading-5 rb:mb-3">
        <span className="rb:whitespace-nowrap">{t('user.email')}</span>
        <span className="rb:text-[#212332]">{user.email}</span>
      </div>
-      <div className="rb:flex rb:justify-between rb:text-[#5B6167] rb:text-[14px] rb:leading-[20px] rb:mb-[12px]">
+      {/* Role */}
+      <div className="rb:flex rb:justify-between rb:text-[#5B6167] rb:text-[14px] rb:leading-5 rb:mb-3">
        <span className="rb:whitespace-nowrap">{t('user.role')}</span>
        <span className="rb:text-[#212332]">{user.is_superuser ? t('user.superuser') : t('user.normalUser')}</span>
      </div>
-      <div className="rb:flex rb:justify-between rb:text-[#5B6167] rb:text-[14px] rb:leading-[20px] rb:mb-[12px]">
+      {/* Created Date */}
+      <div className="rb:flex rb:justify-between rb:text-[#5B6167] rb:text-[14px] rb:leading-5 rb:mb-3">
        <span className="rb:whitespace-nowrap">{t('user.createdAt')}</span>
        <span className="rb:text-[#212332]">{formatDateTime(user.created_at, 'YYYY-MM-DD HH:mm:ss')}</span>
      </div>
-      <div className="rb:text-[#5B6167] rb:font-medium rb:mt-[24px]">{t('header.securitySettings')}</div>
+      
+      {/* Security Settings Section */}
+      <div className="rb:text-[#5B6167] rb:font-medium rb:mt-6">{t('header.securitySettings')}</div>

-      <div className="rb:mt-[12px] rb:bg-[#F0F3F8] rb:p-[10px_12px] rb:rounded-[6px] rb:flex rb:items-center rb:justify-between rb:gap-[8px]">
-        <div className="rb:flex rb:items-center rb:gap-[12px]">
+      {/* Password Change Card */}
+       <div className="rb:mt-3 rb:bg-[#F0F3F8] rb:p-[10px_12px] rb:rounded-md rb:flex rb:items-center rb:justify-between rb:gap-2">
+        <div className="rb:flex rb:items-center rb:gap-3">
          <UnlockOutlined className="rb:text-[24px]" />
          <div>
-            <div className="rb:leading-[20px]">{t('header.changePassword')}</div>
-            <div className="rb:text-[#5B6167] rb:text-[12px] rb:mt-[4px] rb:leading-[16px]">{t('header.changePasswordDesc')}</div>
+            <div className="rb:leading-5">{t('header.changePassword')}</div>
+            <div className="rb:text-[#5B6167] rb:text-[12px] rb:mt-1 rb:leading-4">{t('header.changePasswordDesc')}</div>
          </div>
        </div>
        <Button onClick={() => resetPasswordModalRef.current?.handleOpen(user)}>{t('common.change')}</Button>
--- a/web/src/components/Header/index.tsx
+++ b/web/src/components/Header/index.tsx
@@ -1,16 +1,36 @@
+/*
+ * @Author: ZhaoYing 
+ * @Date: 2026-02-02 15:07:49 
+ * @Last Modified by:   ZhaoYing 
+ * @Last Modified time: 2026-02-02 15:07:49 
+ */
+/**
+ * AppHeader Component
+ * 
+ * The main application header that displays breadcrumb navigation and user menu.
+ * Supports different breadcrumb sources based on the current route.
+ * 
+ * @component
+ */
+
 import { type FC, useRef } from 'react';
-import { Layout, Dropdown, Space, Breadcrumb } from 'antd';
+import { Layout, Dropdown, Breadcrumb } from 'antd';
 import type { MenuProps, BreadcrumbProps } from 'antd';
 import { UserOutlined, LogoutOutlined, SettingOutlined } from '@ant-design/icons';
 import { useTranslation } from 'react-i18next';
 import { useLocation } from 'react-router-dom';
+
 import { useUser } from '@/store/user';
 import { useMenu } from '@/store/menu';
 import styles from './index.module.css'
 import SettingModal, { type SettingModalRef } from './SettingModal'
 import UserInfoModal, { type UserInfoModalRef } from './UserInfoModal'
+
 const { Header } = Layout;

+/**
+ * @param source - Breadcrumb source type ('space' or 'manage'), defaults to 'manage'
+ */
 const AppHeader: FC<{source?: 'space' | 'manage';}> = ({source = 'manage'}) => {
  const { t } = useTranslation();
  const location = useLocation();
@@ -20,21 +40,26 @@ const AppHeader: FC<{source?: 'space' | 'manage';}> = ({source = 'manage'}) => {
  const { user, logout } = useUser();
  const { allBreadcrumbs } = useMenu();
  
-  // 根据当前路由动态选择面包屑源
+  /**
+   * Dynamically select breadcrumb source based on current route
+   * - Knowledge base list: uses 'space' breadcrumb
+   * - Knowledge base detail: uses 'space-detail' breadcrumb
+   * - Other pages: uses the passed source prop
+   */
  const getBreadcrumbSource = () => {
    const pathname = location.pathname;
    
-    // 知识库列表页面使用默认的 space 面包屑
+    // Knowledge base list page uses default space breadcrumb
    if (pathname === '/knowledge-base') {
      return 'space';
    }
    
-    // 知识库详情相关页面使用独立的面包屑
+    // Knowledge base detail pages use independent breadcrumb
    if (pathname.includes('/knowledge-base/') && pathname !== '/knowledge-base') {
      return 'space-detail';
    }
    
-    // 其他页面使用传入的 source
+    // Other pages use the passed source
    return source;
  };
  
@@ -42,13 +67,12 @@ const AppHeader: FC<{source?: 'space' | 'manage';}> = ({source = 'manage'}) => {
  const breadcrumbs = allBreadcrumbs[breadcrumbSource] || [];
  

-
-  // 处理退出登录
+  /** Handle user logout */
  const handleLogout = () => {
    logout()
  };

-  // 用户下拉菜单配置
+  /** User dropdown menu configuration with profile, settings, and logout options */
  const userMenuItems: MenuProps['items'] = [
    {
      key: '1',
@@ -89,18 +113,25 @@ const AppHeader: FC<{source?: 'space' | 'manage';}> = ({source = 'manage'}) => {
      onClick: handleLogout,
    },
  ];
+  
+  /**
+   * Format breadcrumb items with proper titles, paths, and click handlers
+   * - Translates i18n keys to display text
+   * - Handles custom onClick events
+   * - Disables navigation for the last breadcrumb item
+   */
  const formatBreadcrumbNames = () => {
    return breadcrumbs.map((menu, index) => {
      const item: any = {
        title: menu.i18nKey ? t(menu.i18nKey) : menu.label,
      };
      
-      // 如果是最后一项，不设置 path
+      // If it's the last item, don't set path
      if (index === breadcrumbs.length - 1) {
        return item;
      }
      
-      // 如果有自定义 onClick，使用 onClick 并设置 href 为 '#' 以显示手型光标
+      // If has custom onClick, use onClick and set href to '#' to show pointer cursor
      if ((menu as any).onClick) {
        item.onClick = (e: React.MouseEvent) => {
          e.preventDefault();
@@ -108,35 +139,26 @@ const AppHeader: FC<{source?: 'space' | 'manage';}> = ({source = 'manage'}) => {
        };
        item.href = '#';
      } else if (menu.path && menu.path !== '#') {
-        // 只有当 path 不是 '#' 时才设置 path
+        // Only set path when path is not '#'
        item.path = menu.path;
      }
      
      return item;
    });
  }
+  
  return (
    <Header className={styles.header}>
+      {/* Breadcrumb navigation */}
      <Breadcrumb separator=">" items={formatBreadcrumbNames() as BreadcrumbProps['items']} />
-      {/* 语言切换和主题切换按钮 */}
-      <Space>
-        {/* <Button
-          size="small" 
-          type="default"
-          onClick={handleLanguageChange}
-        >
-          {t(`language.${language === 'en' ? 'zh' : 'en'}`)}
-        </Button> */}
-      
-        {/* 用户信息下拉菜单 */}
-        <Dropdown
-          menu={{ 
-            items: userMenuItems
-          }}
-        >
-          <div className="rb:cursor-pointer">{user.username}</div>
-        </Dropdown>
-      </Space>
+      {/* User info dropdown menu */}
+      <Dropdown
+        menu={{
+          items: userMenuItems
+        }}
+      >
+        <div className="rb:cursor-pointer">{user.username}</div>
+      </Dropdown>
      <SettingModal
        ref={settingModalRef}
      />