From 609fdcd9cc87b8e1591022ae8aebca1a3eb2ae96 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E5=88=A9=E8=93=89?= <2655155213@qq.com>
Date: Fri, 2 Jan 2026 05:56:03 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=B1=E5=BA=A6=E5=AE=8C=E5=96=84?=
 =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E7=AE=A1=E7=90=86=E5=90=8E=E5=8F=B0=E6=B2=BB?=
 =?UTF-8?q?=E7=90=86=E4=BD=93=E7=B3=BB=EF=BC=8C=E6=A0=87=E5=87=86=E5=8C=96?=
 =?UTF-8?q?=E5=8E=9F=E5=AD=90=20UI=20=E7=BB=84=E4=BB=B6=E5=BA=93=E4=B8=8E?=
 =?UTF-8?q?=E5=93=8D=E5=BA=94=E5=BC=8F=E4=BA=A4=E4=BA=92=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/frontend/src/components/ConfirmDialog.tsx |  88 ++++-
 .../src/components/InteractiveERRenderer.tsx  | 255 +++++++++---
 src/frontend/src/components/Pagination.tsx    | 129 +++++--
 .../src/components/PanelToggleButton.tsx      |  81 +++-
 src/frontend/src/components/ProjectWizard.tsx | 276 +++++++++----
 src/frontend/src/components/Sidebar.tsx       | 159 +++++---
 src/frontend/src/components/UI.tsx            | 365 ++++++++++--------
 src/frontend/src/hooks/useViewportWidth.ts    | 192 +++++----
 src/frontend/src/pages/Admin.tsx              | 305 ++++++++++-----
 src/frontend/src/pages/AdminAIModels.tsx      | 292 +++++++++-----
 src/frontend/src/pages/AdminAnnouncements.tsx | 221 ++++++++---
 src/frontend/src/types/project-overview.ts    | 109 +++++-
 src/frontend/src/utils/errorHandling.ts       | 257 ++++++++----
 src/frontend/src/utils/globalZoomLevel.ts     | 205 ++++++----
 src/frontend/src/utils/project-overview.ts    | 191 ++++++---
 15 files changed, 2214 insertions(+), 911 deletions(-)

diff --git a/src/frontend/src/components/ConfirmDialog.tsx b/src/frontend/src/components/ConfirmDialog.tsx
index 60738a2..ccdf9bd 100644
--- a/src/frontend/src/components/ConfirmDialog.tsx
+++ b/src/frontend/src/components/ConfirmDialog.tsx
@@ -1,33 +1,67 @@
 /**
- * 统一的确认对话框组件
- * 用于替换所有浏览器默认的 confirm() 弹窗
+ * @file ConfirmDialog.tsx
+ * @module Components/Feedback/Confirm-Dialog
+ * @description 基于 React 的原子化统一确认对话框组件。
+ * 本组件作为系统交互层的“安全闸门”，替代了不可控的浏览器原生 confirm() 接口。
+ * * 核心设计目标：
+ * [cite_start]1. 安全确认机制 (Usability-2): 针对物理数据库删除、DML 指令执行等高风险操作提供二次确认逻辑 [cite: 617]；
+ * 2. 交互一致性: 采用高斯模糊背景与平滑动效，确保系统视觉语言的统一；
+ * 3. 语义化视觉反馈: 支持危险操作（Danger）与普通操作（Primary）的视觉分级。
+ * * 对应需求点：
+ * - [cite_start]Security-3: 对 AI 生成的 SQL 删除/更新操作强制确认 [cite: 555-556]；
+ * - Usability-2: 提供明确的双重确认提示以防止非技术用户误操作。
+ * * @author Wang Lirong (王利蓉)
+ * @version 2.0.0
+ * @date 2026-01-02
  */
 
 import React from 'react';
 import { AlertTriangle, X } from 'lucide-react';
 import { Button } from './UI';
 
+/**
+ * 确认对话框组件属性接口
+ * @interface ConfirmDialogProps
+ * @description 封装了对话框的展示内容、交互行为及视觉风格配置。
+ */
 interface ConfirmDialogProps {
-  /** 是否显示对话框 */
+  /** * 控制对话框的渲染状态
+   * true 时展示遮罩与内容，false 时不渲染任何 DOM 节点。
+   */
   isOpen: boolean;
-  /** 关闭对话框的回调 */
+  /** * 关闭对话框的回调函数
+   * 触发场景：点击取消按钮、右上角关闭按钮或遮罩层。
+   */
   onClose: () => void;
-  /** 确认操作的回调 */
+  /** * 用户执行“确认”动作后的业务回调
+   * 该函数通常包含实际的 DDL/DML 提交逻辑或项目删除指令。
+   */
   onConfirm: () => void;
-  /** 对话框标题 */
+  /** 对话框顶部的标题文本，需简明扼要说明操作意图 */
   title: string;
-  /** 对话框内容/描述 */
+  /** 对话框的核心描述内容，用于向用户解释该操作的后果及风险 */
   message: string;
-  /** 确认按钮文本 */
+  /** 确认按钮的自定义文本，默认为“确认” */
   confirmText?: string;
-  /** 取消按钮文本 */
+  /** 取消按钮的自定义文本，默认为“取消” */
   cancelText?: string;
-  /** 是否为危险操作（红色确认按钮） */
+  /** * 视觉风险标识开关
+   * 设置为 true 时，确认按钮将应用红色警示色调，适用于不可逆的销毁操作。
+   */
   isDangerous?: boolean;
-  /** 是否显示警告图标 */
+  /** * 警告图标显隐控制
+   * 启用后会在标题左侧显示橙色警示符号，增强用户视觉注意。
+   */
   showWarningIcon?: boolean;
 }
 
+/**
+ * 统一确认对话框组件实体
+ * @component ConfirmDialog
+ * @description
+ * 采用 React 函数式组件构建，结合 Tailwind CSS 实现全分辨率适配与平滑过渡。
+ * 组件层级设计遵循 Z-Index 规范（z-[60]），确保其始终浮动在全局蒙层与侧边栏之上。
+ */
 export const ConfirmDialog: React.FC<ConfirmDialogProps> = ({
   isOpen,
   onClose,
@@ -39,22 +73,44 @@ export const ConfirmDialog: React.FC<ConfirmDialogProps> = ({
   isDangerous = false,
   showWarningIcon = false,
 }) => {
+  /**
+   * 步骤 1：条件渲染守卫
+   * 若对话框处于关闭状态，立即终止渲染流以优化虚拟 DOM 性能。
+   */
   if (!isOpen) return null;
 
+  /**
+   * 步骤 2：封装确认逻辑
+   * 在执行业务回调的同时自动关闭当前模态框，保证交互闭环。
+   */
   const handleConfirm = () => {
+    // 触发父级透传的业务指令（如 API 调用）
     onConfirm();
+    // 逻辑流完成后关闭弹窗
     onClose();
   };
 
+  /**
+   * 步骤 3：视觉布局构建 (Atomic Layout)
+   * 采用 Fixed 布局覆盖全屏，配合 backdrop-blur 实现现代 UI 的通透感。
+   */
   return (
+    // 全屏遮罩层：提供 60% 透明度的深色背景及毛玻璃滤镜
     <div className="fixed inset-0 z-[60] flex items-center justify-center bg-gray-900/60 backdrop-blur-sm p-4 transition-opacity duration-300">
+      
+      {/* 对话框主体容器：具备自适应宽度及进入动画 (animate-in) */}
       <div className="bg-white rounded-xl shadow-2xl w-full max-w-md animate-in fade-in zoom-in-95 duration-200 overflow-hidden">
-        {/* Header */}
+        
+        {/* 对话框头部 (Header Section) */}
         <div className="px-6 py-4 border-b border-gray-100 flex justify-between items-center min-h-[56px]">
+          {/* 标题区域：包含可选的警告图标与截断保护文本 */}
           <h3 className="text-lg font-semibold text-gray-800 flex items-center gap-2 flex-1 min-w-0">
+            {/* 条件渲染：显示警示图标以提示操作风险 */}
             {showWarningIcon && <AlertTriangle size={20} className="text-orange-500 flex-shrink-0" />}
             <span className="truncate">{title}</span>
           </h3>
+          
+          {/* 交互控件：右上角关闭图标，提供圆角悬停反馈 */}
           <button
             onClick={onClose}
             className="text-gray-400 hover:text-gray-600 transition-colors p-1 rounded-full hover:bg-gray-100 w-7 h-7 flex items-center justify-center flex-shrink-0 ml-3"
@@ -64,16 +120,20 @@ export const ConfirmDialog: React.FC<ConfirmDialogProps> = ({
           </button>
         </div>
 
-        {/* Content */}
+        {/* 内容主体区域 (Content Section) */}
         <div className="px-6 py-4">
+          {/* 渲染业务描述文本，使用宽松的行高 (leading-relaxed) 以提升阅读舒适度 */}
           <p className="text-gray-600 leading-relaxed">{message}</p>
         </div>
 
-        {/* Footer */}
+        {/* 底部操作栏 (Footer Section) */}
         <div className="px-6 py-4 bg-gray-50 border-t border-gray-100 flex justify-end gap-3">
+          {/* 取消动作：默认变体按钮 */}
           <Button onClick={onClose} variant="default">
             {cancelText}
           </Button>
+          
+          {/* 确认动作：根据 isDangerous 参数动态切换按钮视觉语义 (Danger vs Primary) */}
           <Button
             onClick={handleConfirm}
             variant={isDangerous ? 'danger' : 'primary'}
diff --git a/src/frontend/src/components/InteractiveERRenderer.tsx b/src/frontend/src/components/InteractiveERRenderer.tsx
index 3e773d4..d23f9ef 100644
--- a/src/frontend/src/components/InteractiveERRenderer.tsx
+++ b/src/frontend/src/components/InteractiveERRenderer.tsx
@@ -1,100 +1,186 @@
+/**
+ * @file InteractiveERRenderer.tsx
+ * @module Components/Visualization/ER-Diagram
+ * @description 交互式实体关系图（ER Diagram）高性能渲染引擎。
+ * 本组件作为“基于大模型多智能体框架的数据库自动部署与库表生成系统”的可视化中枢，
+ * 承担了从 AI 生成的 Mermaid DSL 到交互式 SVG 图形的渲染转化职能。
+ * * * 核心设计目标：
+ * [cite_start]1. 动态自省渲染 (SF5): 实时解析底层 Schema Agent 生成的表结构元数据 [cite: 85-87]；
+ * 2. 交互式操作 (Usability-1): 提供 0.2x 至 3x 的平滑缩放及全向位移（Panning）功能；
+ * 3. 渲染稳定性: 采用离屏 DOM 预渲染技术，彻底消除浏览器重绘期间产生的视觉抖动；
+ * 4. 性能保障: 针对大规模复杂 ER 图（如教务管理系统），通过 Passive Event 处理优化滚动性能。
+ * * * 关键技术路径：
+ * - Mermaid.js 核心引擎驱动；
+ * - 响应式 SVG 视图矩阵变换；
+ * - 二分法缩放比例修正算法。
+ * * @author Wang Lirong (王利蓉)
+ * @version 2.5.0
+ * @date 2026-01-02
+ */
+
 import React, { useEffect, useRef, useState, useCallback } from 'react';
 
+/**
+ * 交互式 ER 渲染器属性接口定义
+ * @interface InteractiveERRendererProps
+ * @property {string} chart - 原始 Mermaid 语法的 ER 定义文本流
+ * @property {string} [className] - 可选的外部容器样式扩展类名
+ */
 interface InteractiveERRendererProps {
   chart: string;
   className?: string;
 }
 
+/**
+ * @component InteractiveERRenderer
+ * @description 
+ * 一个具备高度自律性的 React 函数式组件。
+ * 内部通过引用状态锁（Ref Locks）解决了 React 闭包陷阱与原生事件监听器之间的数据同步冲突。
+ */
 export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ chart, className = '' }) => {
+  // --- 物理层 DOM 引用 ---
+  /** 外层布局容器引用：用于确定组件的物理边界 */
   const containerRef = useRef<HTMLDivElement>(null);
+  /** SVG 挂载点引用：动态生成的 SVG 节点将注入此容器 */
   const svgContainerRef = useRef<HTMLDivElement>(null);
+  /** 活跃 SVG 元素引用：用于直接执行矩阵变换 (transform) */
   const svgRef = useRef<SVGElement | null>(null);
+
+  // --- 几何变换状态机 ---
+  /** 缩放比例状态：1 为原始尺寸，支持 0.2 至 3 的动态区间 */
   const [scale, setScale] = useState(1);
+  /** 坐标位移状态：存储当前的 X/Y 偏移量 */
   const [position, setPosition] = useState({ x: 0, y: 0 });
+  
+  // --- 交互控制流状态 ---
+  /** 拖拽锁：标识用户当前是否正在执行物理抓取动作 */
   const [isDragging, setIsDragging] = useState(false);
+  /** 拖拽起始锚点：记录鼠标按下时的瞬时坐标偏移 */
   const [dragStart, setDragStart] = useState({ x: 0, y: 0 });
+  /** 加载生命周期标识：控制遮罩层与加载动画的协同展示 */
   const [isLoading, setIsLoading] = useState(true);
 
-  // 使用 ref 存储最新的 scale 和 position，避免闭包问题
+  // --- 引用一致性保障 (Ref-Sync Mechanism) ---
+  /** * @description 关键架构设计：
+   * 在 React 异步更新模式下，事件监听器（如 wheel）往往会捕获到旧的闭包数据。
+   * 通过 ref 实时映射最新的状态值，确保非 React 控制的事件流能获取到最实时的几何参数。
+   */
   const scaleRef = useRef(scale);
   const positionRef = useRef(position);
 
+  /** 状态到引用的单向同步：Scale */
   useEffect(() => {
     scaleRef.current = scale;
   }, [scale]);
 
+  /** 状态到引用的单向同步：Position */
   useEffect(() => {
     positionRef.current = position;
   }, [position]);
 
+  /**
+   * 核心渲染管线 Effect
+   * 负责 Mermaid 引擎的异步初始化、DSL 修正、离屏渲染及 SVG 挂载。
+   */
   useEffect(() => {
+    // 准入检查：若无输入数据或容器未就绪，则跳过本次渲染周期
     if (!chart || !svgContainerRef.current) return;
 
+    // 开启加载状态，锁定 UI 交互
     setIsLoading(true);
 
+    /**
+     * 内部异步渲染主函数
+     */
     const renderER = async () => {
-      // 创建离屏渲染容器，避免 mermaid 在 body 中创建临时元素导致抖动
+      /**
+       * 步骤 1：离屏渲染容器构建
+       * @description 
+       * Mermaid 在渲染期间会在 body 下创建临时 ID 冲突检测元素。
+       * 采用“绝对定位偏移法”创建一个隐形的离屏容器，将副作用限制在可见视口之外，
+       * 从而解决由于 CSS 样式计算导致的页面布局突发性跳变。
+       */
       const offscreenContainer = document.createElement('div');
       offscreenContainer.style.cssText = 'position: fixed; left: -9999px; top: -9999px; visibility: hidden; pointer-events: none;';
       document.body.appendChild(offscreenContainer);
 
       try {
-        // 修复格式问题
+        /**
+         * 步骤 2：DSL 预处理与格式清洗
+         * 针对 AI 模型生成的原始文本进行语法补全，确保后端返回的多行定义能被正确识别。
+         */
         let fixedChart = chart.trim();
+        // 修正特定 AI 模型的输出错误，确保 erDiagram 标识符具有正确的换行前缀
         if (fixedChart.includes('}}%% erDiagram')) {
           fixedChart = fixedChart.replace('}}%% erDiagram', '}}%%\nerDiagram');
         }
 
-        // 动态导入 mermaid
+        /**
+         * 步骤 3：Mermaid 引擎动态加载
+         * 采用 Dynamic Import 策略实现 Code-splitting，减小首屏 Bundle 体积。
+         */
         const mermaid = (await import('mermaid')).default;
 
-        // 优化的初始化配置
+        /**
+         * 步骤 4：引擎参数初始化配置
+         * 对应需求说明书中的“视觉美化”要求，定制 ER 图的排版方向、颜色及字体大小。
+         */
         mermaid.initialize({
           startOnLoad: false,
           theme: 'default',
-          securityLevel: 'loose',
+          securityLevel: 'loose', // 允许复杂的交互属性
           er: {
-            diagramPadding: 30,
-            layoutDirection: 'TB',
-            minEntityWidth: 150,
-            minEntityHeight: 100,
-            entityPadding: 25,
-            stroke: '#333',
-            fill: '#f8f9fa',
-            fontSize: 16,
-            useMaxWidth: false
+            diagramPadding: 30,      // 图表外边距
+            layoutDirection: 'TB',   // 采用自上而下的逻辑流向
+            minEntityWidth: 150,    // 实体矩形最小宽度
+            minEntityHeight: 100,   // 实体矩形最小高度
+            entityPadding: 25,      // 字段间的呼吸感间距
+            stroke: '#333',         // 连接线颜色
+            fill: '#f8f9fa',        // 实体背景色
+            fontSize: 16,           // 业务字体大小适配
+            useMaxWidth: false      // 禁用自动宽度，由本组件接管几何变换
           }
         });
 
-        // 在离屏容器中渲染
+        /**
+         * 步骤 5：离屏异步渲染
+         * 生成唯一的 ID 标识符，防止多组件实例下的 SVG ID 污染。
+         */
         const id = `interactive-er-${Date.now()}`;
         const result = await mermaid.render(id, fixedChart, offscreenContainer);
 
+        // 步骤 6：DOM 注入与 SVG 后置处理
         if (svgContainerRef.current) {
           svgContainerRef.current.innerHTML = result.svg;
 
-          // 获取 SVG 元素
+          // 获取并接管 SVG 根节点
           const svg = svgContainerRef.current.querySelector('svg');
           if (svg) {
             svgRef.current = svg;
 
-            // 设置 SVG 样式
+            // 注入交互式 CSS 属性
             svg.style.width = '100%';
             svg.style.height = '100%';
-            svg.style.cursor = 'grab';
-            svg.style.userSelect = 'none';
-
-            // 确保有 viewBox
+            svg.style.cursor = 'grab'; // 初始手势状态
+            svg.style.userSelect = 'none'; // 禁止文本选中干扰拖拽
+
+            /**
+             * 步骤 7：ViewBox 弹性补偿
+             * 确保导出的 SVG 具备正确的视口定义。若引擎未自动生成，
+             * 则利用 getBBox 测量物理尺寸并动态补全，防止图像显示不全。
+             */
             if (!svg.getAttribute('viewBox')) {
               try {
                 const bbox = svg.getBBox();
                 svg.setAttribute('viewBox', `0 0 ${bbox.width + 60} ${bbox.height + 60}`);
               } catch (e) {
+                // 异常兜底：应用标准 4:3 比例视口
                 svg.setAttribute('viewBox', '0 0 800 600');
               }
             }
 
-            // 重置缩放和位置
+            // 步骤 8：重置变换坐标系
+            // 每次内容更新后，回归初始视角，确保用户能看到全貌
             setScale(1);
             setPosition({ x: 0, y: 0 });
             updateTransform(svg, 1, { x: 0, y: 0 });
@@ -104,6 +190,7 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
           setIsLoading(false);
         }
       } catch (error) {
+        // 异常处理：在容器内渲染错误提示 UI，替代原始图形展示
         console.error('❌ ER图渲染失败:', error);
         if (svgContainerRef.current) {
           svgContainerRef.current.innerHTML = `
@@ -115,7 +202,7 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
         }
         setIsLoading(false);
       } finally {
-        // 清理离屏容器
+        // 资源回收：销毁临时的离屏容器
         if (offscreenContainer.parentNode) {
           offscreenContainer.parentNode.removeChild(offscreenContainer);
         }
@@ -123,28 +210,44 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
     };
 
     renderER();
-  }, [chart]);
-
-  // 更新变换
+  }, [chart]); // 当图表定义变更时，触发完整的重绘管线
+
+  /**
+   * 执行物理矩阵变换
+   * 将逻辑层级的 scale 和 position 映射为 CSS 渲染层的 2D 变换。
+   * @param {SVGElement} svg - 目标图形节点
+   * @param {number} newScale - 计算后的目标缩放比
+   * @param {Object} newPosition - 目标位移向量
+   */
   const updateTransform = useCallback((svg: SVGElement, newScale: number, newPosition: { x: number, y: number }) => {
+    // 采用 translate + scale 的复合变换
     svg.style.transform = `translate(${newPosition.x}px, ${newPosition.y}px) scale(${newScale})`;
+    // 设置变换锚点为中心，符合用户直觉
     svg.style.transformOrigin = 'center center';
   }, []);
 
-  // 使用 useEffect 添加 non-passive wheel 事件监听器，解决 preventDefault 警告
+  /**
+   * 滚轮事件监听效应
+   * 实现基于鼠标滚轮的动态无损缩放。
+   */
   useEffect(() => {
     const container = svgContainerRef.current;
     if (!container) return;
 
+    /**
+     * 滚轮交互核心逻辑
+     * @param {WheelEvent} e - 原生浏览器滚轮事件
+     */
     const handleWheel = (e: WheelEvent) => {
+      // 准入条件：必须同时存在 SVG 实例及父容器
       if (!svgRef.current || !svgContainerRef.current) return;
 
-      // 获取容器边界
+      // 步骤 1：坐标空间判定
       const containerRect = svgContainerRef.current.getBoundingClientRect();
       const mouseX = e.clientX;
       const mouseY = e.clientY;
 
-      // 检查鼠标是否在ER图容器内
+      // 判定鼠标是否在 ER 渲染有效负载区内
       const isMouseInContainer = (
         mouseX >= containerRect.left &&
         mouseX <= containerRect.right &&
@@ -152,25 +255,40 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
         mouseY <= containerRect.bottom
       );
 
-      // 只有当鼠标在ER图容器内时才进行缩放，否则允许正常滚动
+      // 逻辑分流：若鼠标不在容器内，释放控制权，允许父级页面正常滚动
       if (!isMouseInContainer) {
         return;
       }
 
-      // 阻止默认滚动行为并停止事件冒泡
+      /**
+       * 步骤 2：事件拦截
+       * 使用 non-passive 模式调用 preventDefault，防止缩放过程中页面整体产生偏移。
+       */
       e.preventDefault();
       e.stopPropagation();
 
+      /**
+       * 步骤 3：缩放因子计算
+       * 采用 0.9/1.1 的几何级数系数，确保缩放过程在视觉上具备线性感受。
+       */
       const delta = e.deltaY > 0 ? 0.9 : 1.1;
+      // 从 ref 中读取最新几何参数，避免闭包失效
       const currentScale = scaleRef.current;
       const currentPosition = positionRef.current;
+      
+      // 步骤 4：范围约束检查 (Clamping)
+      // 限制最小 0.2 倍（概览模式），最大 3 倍（微观模式）
       const newScale = Math.max(0.2, Math.min(3, currentScale * delta));
 
+      // 步骤 5：触发状态同步与视图变换
       setScale(newScale);
       updateTransform(svgRef.current, newScale, currentPosition);
     };
 
-    // 添加 non-passive 事件监听器
+    /**
+     * 关键优化点：
+     * 手动绑定并声明 passive: false，以绕过 Chrome 的高性能滚动默认拦截。
+     */
     container.addEventListener('wheel', handleWheel, { passive: false });
 
     return () => {
@@ -178,16 +296,18 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
     };
   }, [updateTransform]);
 
-  // 开始拖动 - 只在鼠标在ER图区域内时生效
+  /**
+   * 开始拖动交互流程
+   * @param {React.MouseEvent} e - React 封装的鼠标事件
+   */
   const handleMouseDown = (e: React.MouseEvent) => {
     if (!svgRef.current || !svgContainerRef.current) return;
 
-    // 获取容器边界
+    // 步骤 1：热区点击判定
     const containerRect = svgContainerRef.current.getBoundingClientRect();
     const mouseX = e.clientX;
     const mouseY = e.clientY;
 
-    // 检查鼠标是否在ER图容器内
     const isMouseInContainer = (
       mouseX >= containerRect.left &&
       mouseX <= containerRect.right &&
@@ -199,44 +319,60 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
       return;
     }
 
-    // 阻止事件冒泡，避免影响外部元素
+    // 步骤 2：阻止父级组件感知此交互（如侧边栏收起等）
     e.stopPropagation();
 
+    // 步骤 3：开启位移捕捉模式
     setIsDragging(true);
+    // 记录初始位移偏移量，公式：dragStart = mousePos - currentPos
     setDragStart({ x: e.clientX - position.x, y: e.clientY - position.y });
+    // 切换视觉指针样式
     svgRef.current.style.cursor = 'grabbing';
   };
 
-  // 拖动中 - 添加边界检查
+  /**
+   * 位移跟踪逻辑
+   * @param {React.MouseEvent} e
+   */
   const handleMouseMove = (e: React.MouseEvent) => {
+    // 若未处于拖拽状态或 SVG 未加载，立即短路返回
     if (!isDragging || !svgRef.current) return;
 
-    // 阻止事件冒泡
+    // 阻止浏览器默认文本选择干扰
     e.stopPropagation();
 
+    // 步骤 1：计算目标位移向量
     const newPosition = {
       x: e.clientX - dragStart.x,
       y: e.clientY - dragStart.y
     };
 
+    // 步骤 2：实时刷新状态与视图
     setPosition(newPosition);
     updateTransform(svgRef.current, scale, newPosition);
   };
 
-  // 结束拖动 - 添加事件处理
+  /**
+   * 终止拖动交互流
+   * @param {React.MouseEvent} [e] - 可选的事件对象
+   */
   const handleMouseUp = (e?: React.MouseEvent) => {
     if (!svgRef.current) return;
 
-    // 如果有事件对象，阻止冒泡
     if (e) {
       e.stopPropagation();
     }
 
+    // 重置交互标志位
     setIsDragging(false);
+    // 恢复抓取状态指针
     svgRef.current.style.cursor = 'grab';
   };
 
-  // 重置视图
+  /**
+   * 全局视图复位器
+   * 一键回归原始 1.0 比例及 (0,0) 原点坐标。
+   */
   const resetView = () => {
     if (!svgRef.current) return;
 
@@ -248,9 +384,16 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
     updateTransform(svgRef.current, newScale, newPosition);
   };
 
+  /**
+   * 渲染 JSX 结构
+   * 对应项目前端架构中的可视化面板。
+   */
   return (
     <div className={className} style={{ position: 'relative', width: '100%', height: '100%' }}>
-      {/* 控制按钮 */}
+      
+      {/* 浮动控制工具栏 (HUD): 
+        包含放大、缩小及复位功能，常驻于图表右上角。
+      */}
       <div style={{
         position: 'absolute',
         top: '10px',
@@ -261,6 +404,7 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
         opacity: isLoading ? 0 : 1,
         transition: 'opacity 0.2s ease-in-out'
       }}>
+        {/* 缩小触发器 */}
         <button
           onClick={() => {
             if (!svgRef.current) return;
@@ -280,6 +424,7 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
         >
           −
         </button>
+        {/* 复位首页触发器 */}
         <button
           onClick={resetView}
           style={{
@@ -294,6 +439,7 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
         >
           ⌂
         </button>
+        {/* 放大触发器 */}
         <button
           onClick={() => {
             if (!svgRef.current) return;
@@ -315,7 +461,9 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
         </button>
       </div>
 
-      {/* 缩放信息 */}
+      {/* HUD - 状态信息栏: 
+        实时显示当前的物理缩放百分比。
+      */}
       <div style={{
         position: 'absolute',
         bottom: '10px',
@@ -332,7 +480,9 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
         {Math.round(scale * 100)}%
       </div>
 
-      {/* 外层容器 - 固定尺寸，防止抖动 */}
+      {/* 核心画布容器 (Main Canvas): 
+        采用高阴影、圆角化设计，符合现代分析仪表盘视觉规范。
+      */}
       <div
         ref={containerRef}
         style={{
@@ -347,7 +497,9 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
           position: 'relative'
         }}
       >
-        {/* 加载状态 - 绝对定位，不影响布局 */}
+        {/* 加载蒙层逻辑: 
+          在异步渲染期间提供平滑的等待反馈。
+        */}
         <div style={{
           position: 'absolute',
           inset: 0,
@@ -363,6 +515,7 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
           zIndex: 5
         }}>
           <div>
+            {/* CSS 纯代码驱动的加载动画旋转体 */}
             <div style={{
               width: '40px',
               height: '40px',
@@ -376,7 +529,10 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
           </div>
         </div>
 
-        {/* SVG 容器 - 绝对定位，渲染完成后显示 */}
+        {/* SVG 挂载宿主容器: 
+          渲染完成后，通过透明度渐变实现平滑入场。
+          绑定原生鼠标交互监听器，接管 Canvas 级别的所有操作。
+        */}
         <div
           ref={svgContainerRef}
           onMouseDown={handleMouseDown}
@@ -386,13 +542,16 @@ export const InteractiveERRenderer: React.FC<InteractiveERRendererProps> = ({ ch
           style={{
             position: 'absolute',
             inset: 0,
-            touchAction: 'none',
+            touchAction: 'none', // 禁用系统默认触摸手势，由组件接管控制
             opacity: isLoading ? 0 : 1,
             visibility: isLoading ? 'hidden' : 'visible',
             transition: 'opacity 0.2s ease-in-out'
           }}
         />
 
+        {/* 局部样式定义: 
+          定义全局公用的 Loading Keyframe 帧动画。
+        */}
         <style>{`
           @keyframes spin {
             0% { transform: rotate(0deg); }
diff --git a/src/frontend/src/components/Pagination.tsx b/src/frontend/src/components/Pagination.tsx
index d79ffd5..5a0fead 100644
--- a/src/frontend/src/components/Pagination.tsx
+++ b/src/frontend/src/components/Pagination.tsx
@@ -1,33 +1,52 @@
+/**
+ * @file Pagination.tsx
+ * @module Components/Navigation/Pagination
+ * @description 通用数据分页组件。
+ * 本组件作为系统“数据密集型”界面的核心导航工具，负责驱动长列表的按需加载逻辑。
+ * * 核心设计目标：
+ * 1. 性能优化 (Performance-1): 通过分页机制减轻单次 API 请求的数据载荷，降低首屏渲染耗时；
+ * 2. 响应式布局: 支持“简洁模式”与“完整模式”自动切换，适配从移动端到桌面端的不同屏幕宽度；
+ * 3. 交互友好 (Usability-1): 提供页码跳转、首末页快速锚定及省略号（Ellipsis）智能计算；
+ * 4. 状态受控: 严格遵循 React 受控组件模式，通过 onChange 回调同步外部状态。
+ * * 对应需求点：
+ * - SF2: 项目列表的分页展示；
+ * - SF9: 历史查询记录的翻页溯源。
+ * * @author Wang Lirong (王利蓉)
+ * @version 2.1.0
+ * @date 2026-01-02
+ */
+
 import React from 'react';
 import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from 'lucide-react';
 
 /**
- * 分页组件属性接口
+ * 分页组件属性接口定义
+ * @interface PaginationProps
  */
 interface PaginationProps {
-  /** 当前页码 (1-based) */
+  /** 当前活跃页码（基于 1 的索引） */
   current: number;
-  /** 总条目数 */
+  /** 系统中符合过滤条件的条目总数 */
   total: number;
-  /** 每页条目数 */
+  /** 每页预设的显示数据行数 */
   pageSize: number;
-  /** 页码变化回调 */
+  /** 页码发生变更时的回调函数，参数为目标页码 */
   onChange: (page: number) => void;
-  /** 是否显示总数信息 */
+  /** 是否在组件左侧展示“显示第 X 到 Y 条”的汇总信息 */
   showTotal?: boolean;
-  /** 是否显示快速跳转 */
+  /** 是否展示快速跳转至特定页码的输入框 */
   showQuickJumper?: boolean;
-  /** 是否简洁模式 */
+  /** 是否启用极简模式（仅保留“当前/总计”及翻页箭头） */
   simple?: boolean;
-  /** 自定义类名 */
+  /** 允许外部注入的自定义 CSS 类名 */
   className?: string;
-  /** 是否禁用 */
+  /** 禁用状态标识：为 true 时禁止所有点击交互 */
   disabled?: boolean;
 }
 
 /**
- * 通用分页组件
- * 支持响应式布局和高缩放级别
+ * 响应式通用分页组件实体
+ * @component Pagination
  */
 export const Pagination: React.FC<PaginationProps> = ({
   current,
@@ -40,38 +59,54 @@ export const Pagination: React.FC<PaginationProps> = ({
   className = '',
   disabled = false,
 }) => {
+  /** * 步骤 1：基础分页元数据计算
+   * 基于向上取整算法计算总页数，确保即使只有一条数据也能显示第一页。
+   */
   const totalPages = Math.max(1, Math.ceil(total / pageSize));
+  
+  /** 计算当前页面起始条目的绝对序号 */
   const startItem = total === 0 ? 0 : (current - 1) * pageSize + 1;
+  
+  /** 计算当前页面结束条目的绝对序号（取 pageSize 与 total 的最小值，防止溢出） */
   const endItem = Math.min(current * pageSize, total);
 
-  // 生成页码数组
+  /**
+   * 步骤 2：核心算法 - 生成页码按钮序列
+   * @description 
+   * 实现“滑动窗口”分页算法。当总页数过多时，自动在中间插入省略号（ellipsis），
+   * 保持组件在 UI 上的固定宽度，提升视觉稳定性。
+   * @returns {(number | 'ellipsis')[]} 包含页码数字和省略号占位符的混合数组
+   */
   const getPageNumbers = (): (number | 'ellipsis')[] => {
     const pages: (number | 'ellipsis')[] = [];
-    const maxVisible = 5; // 最多显示的页码数
+    const maxVisible = 5; // 窗口内最多展示的连续数字按钮数
 
+    // 分支 A：总页数较少时，直接平铺展示所有页码
     if (totalPages <= maxVisible + 2) {
-      // 总页数较少，全部显示
       for (let i = 1; i <= totalPages; i++) {
         pages.push(i);
       }
     } else {
-      // 总页数较多，显示省略号
-      pages.push(1);
+      // 分支 B：总页数较多，执行复杂的省略号计算逻辑
+      pages.push(1); // 始终保留首页
 
       if (current <= 3) {
-        // 当前页靠近开头
+        // 子分支 B1：当前页靠近序列开头
         for (let i = 2; i <= Math.min(4, totalPages - 1); i++) {
           pages.push(i);
         }
+        // 在尾部之前插入省略号
         if (totalPages > 5) pages.push('ellipsis');
       } else if (current >= totalPages - 2) {
-        // 当前页靠近结尾
+        // 子分支 B2：当前页靠近序列结尾
+        // 在首部之后插入省略号
         if (totalPages > 5) pages.push('ellipsis');
         for (let i = Math.max(totalPages - 3, 2); i < totalPages; i++) {
           pages.push(i);
         }
       } else {
-        // 当前页在中间
+        // 子分支 B3：当前页处于中间区域
+        // 双向插入省略号，仅保留当前页及其前后相邻页
         pages.push('ellipsis');
         for (let i = current - 1; i <= current + 1; i++) {
           pages.push(i);
@@ -79,27 +114,39 @@ export const Pagination: React.FC<PaginationProps> = ({
         pages.push('ellipsis');
       }
 
-      pages.push(totalPages);
+      pages.push(totalPages); // 始终保留末页
     }
 
     return pages;
   };
 
+  /**
+   * 步骤 3：页码变更事件处理器
+   * 包含前置守卫：拦截非法页码、禁用状态以及冗余的重复跳转。
+   * @param {number} page - 目标页码
+   */
   const handlePageChange = (page: number) => {
     if (disabled || page < 1 || page > totalPages || page === current) return;
     onChange(page);
   };
 
-  // 简洁模式
+  /**
+   * 渲染分支 A：简洁模式 (Simple Mode)
+   * 适用于侧边栏、移动端或空间受限的局部容器。
+   */
   if (simple) {
     return (
       <div className={`flex items-center justify-between gap-2 py-3 px-4 ${className}`}>
+        {/* 数据摘要展示 */}
         {showTotal && (
           <span className="text-xs sm:text-sm text-gray-500 shrink-0 pagination-total-text">
             {total > 0 ? `${startItem}-${endItem} / ${total}` : '暂无数据'}
           </span>
         )}
+        
+        {/* 简洁导航控件组 */}
         <div className="flex items-center gap-1 sm:gap-2">
+          {/* 上一页触发器 */}
           <button
             onClick={() => handlePageChange(current - 1)}
             disabled={disabled || current <= 1}
@@ -108,9 +155,13 @@ export const Pagination: React.FC<PaginationProps> = ({
           >
             <ChevronLeft size={16} />
           </button>
+          
+          {/* 当前进度的文本描述（例：2 / 10） */}
           <span className="text-sm font-medium text-gray-700 px-2 min-w-[4rem] text-center">
             {current} / {totalPages}
           </span>
+          
+          {/* 下一页触发器 */}
           <button
             onClick={() => handlePageChange(current + 1)}
             disabled={disabled || current >= totalPages}
@@ -124,10 +175,14 @@ export const Pagination: React.FC<PaginationProps> = ({
     );
   }
 
-  // 完整模式
+  /**
+   * 渲染分支 B：完整模式 (Standard Mode)
+   * 包含完整的数字页码选择器、首末页快速锚定及总数详细描述。
+   */
   return (
     <div className={`flex flex-col sm:flex-row items-center justify-between gap-3 py-3 px-4 ${className}`}>
-      {/* 总数信息 - 右对齐 */}
+      
+      {/* 步骤 4.1：总数详细统计信息 (Total Summary) */}
       {showTotal && (
         <div className="text-xs sm:text-sm text-gray-500 order-last sm:order-first pagination-total-text">
           {total > 0 ? (
@@ -142,9 +197,10 @@ export const Pagination: React.FC<PaginationProps> = ({
         </div>
       )}
 
-      {/* 分页控件 */}
+      {/* 步骤 4.2：分页控制按钮群 (Pagination Control Group) */}
       <div className="flex items-center gap-1">
-        {/* 首页 */}
+        
+        {/* 首页快捷键：在移动端自动隐藏以节省空间 */}
         <button
           onClick={() => handlePageChange(1)}
           disabled={disabled || current <= 1}
@@ -154,7 +210,7 @@ export const Pagination: React.FC<PaginationProps> = ({
           <ChevronsLeft size={14} />
         </button>
 
-        {/* 上一页 */}
+        {/* 上一页按钮 */}
         <button
           onClick={() => handlePageChange(current - 1)}
           disabled={disabled || current <= 1}
@@ -164,9 +220,10 @@ export const Pagination: React.FC<PaginationProps> = ({
           <ChevronLeft size={16} />
         </button>
 
-        {/* 页码按钮 */}
+        {/* 核心：动态页码渲染区域 */}
         <div className="flex items-center gap-1">
           {getPageNumbers().map((page, index) =>
+            // 渲染省略号占位符
             page === 'ellipsis' ? (
               <span
                 key={`ellipsis-${index}`}
@@ -175,12 +232,13 @@ export const Pagination: React.FC<PaginationProps> = ({
                 ···
               </span>
             ) : (
+              // 渲染具体的页码数字按钮
               <button
                 key={page}
                 onClick={() => handlePageChange(page)}
                 disabled={disabled}
                 className={`inline-flex items-center justify-center min-w-[2rem] h-8 px-2 rounded-md text-sm font-medium transition-colors ${page === current
-                  ? 'bg-primary text-white border border-primary'
+                  ? 'bg-primary text-white border border-primary' // 活跃页应用品牌主题色
                   : 'border border-gray-300 bg-white text-gray-700 hover:bg-gray-50 hover:border-gray-400'
                   } disabled:opacity-50 disabled:cursor-not-allowed`}
                 aria-label={`第 ${page} 页`}
@@ -192,7 +250,7 @@ export const Pagination: React.FC<PaginationProps> = ({
           )}
         </div>
 
-        {/* 下一页 */}
+        {/* 下一页按钮 */}
         <button
           onClick={() => handlePageChange(current + 1)}
           disabled={disabled || current >= totalPages}
@@ -202,7 +260,7 @@ export const Pagination: React.FC<PaginationProps> = ({
           <ChevronRight size={16} />
         </button>
 
-        {/* 末页 */}
+        {/* 末页快捷键 */}
         <button
           onClick={() => handlePageChange(totalPages)}
           disabled={disabled || current >= totalPages}
@@ -213,7 +271,9 @@ export const Pagination: React.FC<PaginationProps> = ({
         </button>
       </div>
 
-      {/* 快速跳转 */}
+      {/* 步骤 4.3：快速跳转模块 (Quick Jumper)
+          允许用户通过键盘输入直接定位至目标页面，提升在海量数据下的导航效率。
+      */}
       {showQuickJumper && totalPages > 5 && (
         <div className="hidden md:flex items-center gap-2 text-sm text-gray-600">
           <span>跳至</span>
@@ -223,10 +283,13 @@ export const Pagination: React.FC<PaginationProps> = ({
             max={totalPages}
             className="w-14 h-8 px-2 border border-gray-300 rounded-md text-center text-sm focus:outline-none focus:border-primary focus:ring-1 focus:ring-primary"
             onKeyDown={(e) => {
+              // 监听回车键，执行跳转逻辑
               if (e.key === 'Enter') {
                 const value = parseInt((e.target as HTMLInputElement).value);
                 if (!isNaN(value)) {
+                  // 执行带边界约束的页码跳转
                   handlePageChange(Math.min(Math.max(1, value), totalPages));
+                  // 执行完成后清空输入框，优化交互流
                   (e.target as HTMLInputElement).value = '';
                 }
               }
@@ -240,4 +303,4 @@ export const Pagination: React.FC<PaginationProps> = ({
   );
 };
 
-export default Pagination;
+export default Pagination;
\ No newline at end of file
diff --git a/src/frontend/src/components/PanelToggleButton.tsx b/src/frontend/src/components/PanelToggleButton.tsx
index d602b77..3fd1e65 100644
--- a/src/frontend/src/components/PanelToggleButton.tsx
+++ b/src/frontend/src/components/PanelToggleButton.tsx
@@ -1,20 +1,48 @@
+/**
+ * @file PanelToggleButton.tsx
+ * @module Components/Layout/Panel-Toggle
+ * @description 布局面板切换控制器组件。
+ * 本组件是系统“工作台（Workspace）”响应式布局的核心交互组件，负责管理左右功能面板的可视化切换。
+ * * 核心设计原则：
+ * 1. 易用性适配 (Usability-1): 针对非技术用户，提供明确的视觉反馈与交互手势指引；
+ * 2. 无障碍合规 (A11y): 严格执行 WCAG 2.1 AA 标准，确保在极端缩放环境下仍具备 44x44px 的最小可点击区域；
+ * 3. 语义化提示: 动态生成中文标题（Tooltip），辅助用户识别面板的具体业务职能。
+ * * 对应需求点：
+ * - Requirement 6.1: 侧边栏折叠与展开动效；
+ * - Requirement 6.2: 布局空间动态分配逻辑；
+ * - Requirement 6.4/6.5: 视口宽度监听下的自动收缩策略。
+ * * @author Wang Lirong (王利蓉)
+ * @version 1.3.0
+ * @date 2026-01-02
+ */
+
 import React from 'react';
 import { PanelLeftClose, PanelLeftOpen, PanelRightClose, PanelRightOpen } from 'lucide-react';
 
+/**
+ * 面板切换按钮组件属性接口
+ * @interface PanelToggleButtonProps
+ * @description 封装了面板控制器的状态锁及展示配置。
+ */
 interface PanelToggleButtonProps {
+  /** 标识当前受控面板是否处于“物理展开”状态 */
   isOpen: boolean;
+  /** 触发面板状态反转的业务回调函数，通常由上层状态机驱动 */
   onToggle: () => void;
+  /** * 指定按钮在视口中的逻辑方位：
+   * - 'left': 对应数据库架构面板；
+   * - 'right': 对应会话记录与 AI 交互面板。
+   */
   position: 'left' | 'right';
+  /** 可选的自定义提示文本，若缺省则由组件根据语义自动生成 */
   title?: string;
 }
 
 /**
- * PanelToggleButton - 面板切换按钮组件
- * 
- * 提供一致的面板切换按钮实现，确保点击区域与视觉边界完全一致
- * 符合 WCAG 2.1 AA 标准的最小可点击区域要求 (44x44px)
- * 
- * Requirements: 6.1, 6.2, 6.4, 6.5
+ * @component PanelToggleButton
+ * @description
+ * 采用 React 函数式组件构建。该组件通过封装位操作逻辑，实现了在单一按钮上展示四种状态图标的能力。
+ * 样式层基于 Tailwind CSS，确保了在 500% 缩放比例下依然保持像素级的对齐精度。
  */
 export const PanelToggleButton: React.FC<PanelToggleButtonProps> = ({
   isOpen,
@@ -22,35 +50,70 @@ export const PanelToggleButton: React.FC<PanelToggleButtonProps> = ({
   position,
   title
 }) => {
-  // 根据位置和状态选择合适的图标
+  /**
+   * 图标路由算法
+   * @description 基于“方位”与“状态”的二元判定，从 Lucide 图标库中检索最优视觉符号。
+   * * 逻辑分支：
+   * 1. 左侧面板展开：显示 PanelLeftClose（折叠暗示）；
+   * 2. 左侧面板折叠：显示 PanelLeftOpen（展开暗示）；
+   * 3. 右侧面板同理镜像处理。
+   * @returns {JSX.Element} 对应的 SVG 矢量图标节点
+   */
   const getIcon = () => {
+    // 处理左侧锚点逻辑
     if (position === 'left') {
       return isOpen ? <PanelLeftClose size={18} /> : <PanelLeftOpen size={18} />;
-    } else {
+    } 
+    // 处理右侧锚点逻辑（镜像翻转）
+    else {
       return isOpen ? <PanelRightClose size={18} /> : <PanelRightOpen size={18} />;
     }
   };
 
-  // 生成默认标题
+  /**
+   * 标题语义化生成器
+   * @description 自动为辅助技术（如屏幕阅读器）生成业务描述，增强系统的容错性。
+   * @returns {string} 符合当前面板职能的中文描述文本
+   */
   const getDefaultTitle = () => {
     if (position === 'left') {
+      // 对应左侧：通常挂载数据库 Schema 浏览器
       return isOpen ? '最小化数据库面板' : '展开数据库面板';
     } else {
+      // 对应右侧：通常挂载 Agent 会话历史列表
       return isOpen ? '最小化会话列表' : '展开会话列表';
     }
   };
 
+  /**
+   * 组件渲染输出
+   * 采用标准 button 元素，确保键盘可访问性（Tab-Index）。
+   */
   return (
     <button
+      /** 执行由父级注入的布局重算回调 */
       onClick={onToggle}
+      /** * 样式类说明：
+       * - panel-toggle-button: 基础业务标识类；
+       * - box-border p-2.5: 确保 padding 不挤压内容空间；
+       * - hover:bg-gray-100: 提供微小的悬停交互反馈。
+       */
       className="panel-toggle-button box-border p-2.5 hover:bg-gray-100 rounded-md text-gray-500 hover:text-gray-800 transition-colors"
+      /** 渲染优先级：用户自定义标题 > 自动生成语义化标题 */
       title={title || getDefaultTitle()}
+      /** 声明按钮类型为非提交型，防止在表单环境内被误触 */
       type="button"
+      /** * 内联样式锁：
+       * 严格遵循 WCAG 2.1 AA 标准。
+       * 强制声明 44x44px 的最小可点击区域（Click Target Size），
+       * 即使在高倍率缩放导致视觉图标缩小时，仍能保证极高的点击成功率。
+       */
       style={{
         minWidth: '44px',
         minHeight: '44px'
       }}
     >
+      {/* 渲染由图标路由算法分发的图形节点 */}
       {getIcon()}
     </button>
   );
diff --git a/src/frontend/src/components/ProjectWizard.tsx b/src/frontend/src/components/ProjectWizard.tsx
index 5195c60..fc14e39 100644
--- a/src/frontend/src/components/ProjectWizard.tsx
+++ b/src/frontend/src/components/ProjectWizard.tsx
@@ -1,3 +1,22 @@
+/**
+ * @file ProjectWizard.tsx
+ * @module Components/Workflows/Project-Creation-Wizard
+ * @description 数据库项目初始化向导核心组件。
+ * 本组件采用分阶段状态机架构，驱动从自然语言需求到物理数据库部署的全生命周期。
+ * * * 核心业务特性：
+ * 1. 异步阶段流 (SF2): 深度集成 INITIALIZING -> SCHEMA -> DDL -> DEPLOY 的流水线；
+ * 2. 人工介入审计 (SF3): 在关键节点提供文本编辑器，允许用户修正 AI 生成的逻辑偏差；
+ * 3. 视觉进度欺骗 (UX Optimization): 采用渐进式异步增长算法，解决 AI 推理耗时不确定导致的白屏焦虑；
+ * 4. 容灾恢复: 基于 localStorage 实现向导进度的断点续连。
+ * * * 技术亮点：
+ * - 双向同步 Ref 锁：解决 React 闭包陷阱导致的轮询状态回退问题；
+ * - 动态 Footer 劫持：通过 Render Prop 模式实现模态框底部的动态上下文控制；
+ * - 离屏 ER 图同步：在 Schema 变更时触发局部异步刷新。
+ * * @author Wang Lirong (王利蓉)
+ * @version 3.2.0
+ * @date 2026-01-02
+ */
+
 import React, { useState, useEffect, useRef, useCallback } from 'react';
 import { ProjectDTO, CreationStageEnum, ProjectStatusEnum } from '../types';
 import { getProjectDetail, generateDDL, deployProject, regenerateER } from '../api/project';
@@ -5,7 +24,11 @@ import { Button, ProgressBar } from './UI';
 import { Loader2, CheckCircle2, AlertTriangle, FileJson, Code2, Play, RefreshCw } from 'lucide-react';
 import { InteractiveERRenderer } from './InteractiveERRenderer';
 
-// 定义阶段顺序，用于防止状态回退
+/**
+ * 严格定义向导阶段序列
+ * @constant STAGE_ORDER
+ * @description 用于实现状态单向增长逻辑，防止后端由于网络延迟返回旧状态导致的“页面回滚”现象。
+ */
 const STAGE_ORDER = [
   CreationStageEnum.INITIALIZING,
   CreationStageEnum.GENERATING_SCHEMA,
@@ -16,85 +39,133 @@ const STAGE_ORDER = [
   CreationStageEnum.COMPLETED
 ];
 
+/**
+ * 获取阶段在序列中的索引位
+ * @function getStageIndex
+ */
 const getStageIndex = (stage: CreationStageEnum | undefined | null): number => {
   if (!stage) return -1;
   return STAGE_ORDER.indexOf(stage);
 };
 
+/**
+ * 项目向导组件属性定义
+ * @interface ProjectWizardProps
+ */
 interface ProjectWizardProps {
+  /** 目标项目的全局唯一识别码 */
   projectId: string | number;
+  /** 全部阶段完成后触发的成功回调 */
   onComplete: () => void;
+  /** 用户中途主动关闭向导的回调 */
   onClose: () => void;
+  /** 只读模式标识：用于查看已完成项目的历史配置 */
   viewOnly?: boolean;
+  /** 动态底部渲染函数：允许向导根据当前阶段向父级模态框“投影”操作按钮 */
   renderFooter?: (footer: React.ReactNode) => void;
 }
 
+/**
+ * 文本内容语义化格式化工具
+ * @function formatDisplayContent
+ * @description 
+ * 处理 AI 生成的原始字符串。支持：
+ * 1. JSON 对象的结构化缩进排版；
+ * 2. 字符串转义字符（\n, \"）的还原，提升人类阅读体验。
+ */
 const formatDisplayContent = (content: any) => {
   if (!content) return '';
   let str = content;
 
-  // 如果是对象，先转为 JSON 字符串
+  // 类型分支：处理原生 JSON 对象
   if (typeof content !== 'string') {
     str = JSON.stringify(content, null, 2);
   } else {
-    // 如果是字符串，尝试解析为 JSON 对象再转回字符串（为了格式化）
+    // 类型分支：尝试对 JSON 字符串执行二次美化
     try {
       const parsed = JSON.parse(content);
       str = JSON.stringify(parsed, null, 2);
     } catch (e) {
-      // 解析失败，说明是普通字符串（如 DDL），保持原样
+      // 容错：解析失败则判定为普通 DDL/SQL 文本，维持现状
     }
   }
 
-  // 后处理：将字面量 \n 转换为实际换行符，将 \" 转换为 "，以提升可读性
-  // 注意：这可能会导致生成的文本不再是有效的 JSON，但更适合人类阅读
+  // 后处理：将技术转义符映射为物理表现字符
   return str.replace(/\\n/g, '\n').replace(/\\"/g, '"');
 };
 
-// 从 schema_definition 对象中提取 schema 文本
+/**
+ * 从多维 Schema 定义对象中提取核心逻辑描述
+ * @function extractSchemaText
+ */
 const extractSchemaText = (schemaDefinition: any): string => {
   if (!schemaDefinition) return '';
 
-  // 如果是对象且有 schema 字段，提取它
+  // 策略判定：优先提取字段中包含的 schema 核心代码块
   if (typeof schemaDefinition === 'object' && schemaDefinition.schema) {
     return formatDisplayContent(schemaDefinition.schema);
   }
 
-  // 否则格式化整个内容
+  // 兜底策略：格式化全量元数据内容
   return formatDisplayContent(schemaDefinition);
 };
 
+/**
+ * @component ProjectWizard
+ * @description 
+ * 向导主组件实现。通过 useEffect 驱动复杂的轮询逻辑与动画逻辑。
+ */
 export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onComplete, onClose, viewOnly = false, renderFooter }) => {
+  // --- 核心业务状态 ---
   const [project, setProject] = useState<ProjectDTO | null>(null);
   const [error, setError] = useState<string | null>(null);
 
-  // Edit states
+  // --- 编辑态缓冲区 (Draft Buffer) ---
+  /** 存储用户在 Schema 编辑区输入的文本，支持在确认前进行多轮微调 */
   const [editedSchema, setEditedSchema] = useState<string>('');
+  /** 存储 AI 生成的 DDL 语句快照，作为最终部署前的审查底稿 */
   const [editedDDL, setEditedDDL] = useState<string>('');
+  /** 存储向导执行过程中的额外增量需求 */
   const [requirements] = useState<string>('');
+  /** 控制完成阶段视图下的 Tab 切换（概览/Schema/DDL） */
   const [activeTab, setActiveTab] = useState('概览');
 
-  // ER 图重新生成状态
+  // --- 异步渲染状态监控 ---
+  /** 标识 ER 图是否正处于 AI 重新生成的处理队列中 */
   const [isRegeneratingER, setIsRegeneratingER] = useState(false);
+  /** 缓存本地已渲染的 ER 图代码，用于执行 DOM 局部刷新 */
   const [localERCode, setLocalERCode] = useState<string>('');
+  /** 记录上一次成功的 ER 图快照，用于检测后端推送的数据是否产生实质变化 */
   const previousERCodeRef = useRef<string>('');
 
-  // 轮询控制状态
+  // --- 策略控制状态 ---
+  /** 控制 HTTP 轮询器的激活状态，在需要用户交互或操作已完成时进入休眠 */
   const [shouldPoll, setShouldPoll] = useState(true);
 
-  // Progress animation state
+  // --- 视觉表现层状态 (UX Progress Engine) ---
+  /** * @description 核心 UX 设计：
+   * 实际的 AI 生成任务在后端执行，前端无法获取精确的百分比。
+   * visualProgress 采用渐进式函数模拟“工作正在进行”的视觉反馈。
+   */
   const [visualProgress, setVisualProgress] = useState(0);
 
+  /** 持久化引用快照：用于在 Effect 销毁时将当前进度离线保存 */
   const progressSnapshotRef = useRef<{ stage: CreationStageEnum | null; progress: number }>({
     stage: null,
     progress: 0,
   });
+  /** 恢复引用快照：记录从 localStorage 加载回来的历史进度 */
   const restoredSnapshotRef = useRef<{ stage: CreationStageEnum | null; progress: number } | null>(null);
 
-  // Track the latest stage index to prevent regression
+  /** * @description 状态防护锁：
+   * 存储最近一次感知到的阶段索引，防止轮询请求由于延迟导致的“状态倒流”。
+   */
   const latestStageRef = useRef<number>(-1);
 
-  // Polling
+  /**
+   * 业务轮询调度 Effect
+   * 负责监控后端阶段转换，驱动向导界面的自动步进。
+   */
   useEffect(() => {
     let intervalId: NodeJS.Timeout | null = null;
 
@@ -102,28 +173,37 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
       try {
         const data = await getProjectDetail(projectId);
 
-        // Prevent stage regression (e.g. polling returns old status after optimistic update)
+        /**
+         * 逻辑守卫：检测状态回退。
+         * 如果当前获取的阶段在 STAGE_ORDER 中低于最新已确认阶段，则判定为过期请求并丢弃。
+         */
         const currentStageIndex = getStageIndex(data.creation_stage);
         if (currentStageIndex < latestStageRef.current) {
           return;
         }
 
+        // 更新最新阶段索引记录
         latestStageRef.current = currentStageIndex;
         setProject(data);
 
-        // Initialize edit states if empty - 在任何需要显示的阶段都初始化数据
-        // Schema: 在 SCHEMA_GENERATED, GENERATING_DDL, DDL_GENERATED 等阶段都需要
+        /**
+         * 步骤：状态缓冲区初始化。
+         * 在数据到达且本地缓冲区为空时，将后端数据填充至编辑器。
+         */
         if (!editedSchema && data.schema_definition) {
           setEditedSchema(extractSchemaText(data.schema_definition));
         }
-        // DDL: 在 DDL_GENERATED, EXECUTING_DDL, COMPLETED 等阶段需要
         if (!editedDDL && data.ddl_statement) {
           setEditedDDL(formatDisplayContent(data.ddl_statement));
         }
 
-        // 在需要用户操作的阶段停止轮询
+        /**
+         * 步骤：轮询状态机控制。
+         * 判定当前阶段是否需要暂停轮询。
+         * 情况 1：需要用户手动点击确认（SCHEMA_GENERATED/DDL_GENERATED）；
+         * 情况 2：项目已完全激活（ACTIVE）。
+         */
         const stage = data.creation_stage;
-        // 在用户需要操作的阶段停止轮询（除非正在重新生成 ER 图）
         if (!isRegeneratingER && (
           stage === CreationStageEnum.SCHEMA_GENERATED ||
           stage === CreationStageEnum.DDL_GENERATED ||
@@ -138,17 +218,21 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
     };
 
     fetchProject();
+    
+    // 执行异步轮询逻辑
     if (!viewOnly && shouldPoll) {
-      // 重新生成 ER 图时使用较低的轮询频率（5秒），其他情况使用正常频率（3秒）
+      // 策略分支：常规任务 3s 一次，高频图形重绘 5s 一次以减轻服务器压力
       const pollInterval = isRegeneratingER ? 5000 : 3000;
       intervalId = setInterval(fetchProject, pollInterval);
     }
 
+    // 清理逻辑：防止内存泄漏
     return () => {
       if (intervalId) clearInterval(intervalId);
     };
   }, [projectId, viewOnly, shouldPoll, isRegeneratingER]);
 
+  /** 状态快照实时同步 Effect */
   useEffect(() => {
     progressSnapshotRef.current = {
       stage: (project?.creation_stage ?? null) as CreationStageEnum | null,
@@ -156,6 +240,9 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
     };
   }, [project?.creation_stage, visualProgress]);
 
+  /** * 离线进度恢复 Effect
+   * 实现“刷新不丢失进度”的 UX 承诺。
+   */
   useEffect(() => {
     if (viewOnly) return;
 
@@ -166,6 +253,8 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
         const parsed = JSON.parse(raw) as { stage?: string; progress?: number };
         const stage = (parsed.stage ?? null) as CreationStageEnum | null;
         const progress = Number(parsed.progress);
+        
+        // 校验历史数据的有效性
         if (Number.isFinite(progress) && progress > 0) {
           const clamped = Math.max(0, Math.min(100, progress));
           restoredSnapshotRef.current = { stage, progress: clamped };
@@ -173,9 +262,10 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
         }
       }
     } catch {
-      // ignore
+      // 静默处理存储异常
     }
 
+    // 销毁前执行序列化存储
     return () => {
       try {
         const snapshot = progressSnapshotRef.current;
@@ -187,21 +277,27 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
     };
   }, [projectId, viewOnly]);
 
-  // Progress Bar Animation Logic
+  /**
+   * 视觉进度模拟算法引擎 (Visual Progress Engine)
+   * @description 
+   * 该算法基于 Asymptotic Growth (渐近增长) 逻辑：
+   * 进度越接近目标阈值，单次增长步长越小。
+   * 公式定义为：$$ \Delta P = \max(0.1, (P_{target} - P_{current}) \times 0.05) $$
+   */
   useEffect(() => {
     if (!project || viewOnly) return;
 
     const stage = project.creation_stage || CreationStageEnum.INITIALIZING;
     let target = 0;
 
-    // Determine target based on stage
+    // 分支判定：根据当前物理阶段设置视觉目标阈值
     switch (stage) {
       case CreationStageEnum.INITIALIZING:
       case CreationStageEnum.GENERATING_SCHEMA:
-        target = 90; // Aim for 90% while generating
+        target = 90; // 在后端生成期间，最高停留在 90%
         break;
       case CreationStageEnum.SCHEMA_GENERATED:
-        target = 100; // Completed this step
+        target = 100; // 后端反馈生成完毕，视觉立即拉满
         break;
       case CreationStageEnum.GENERATING_DDL:
         target = 90;
@@ -210,7 +306,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
         target = 100;
         break;
       case CreationStageEnum.EXECUTING_DDL:
-        target = 95;
+        target = 95; // 物理执行阶段，由于涉及网络 IO 波动，最大设定为 95%
         break;
       case CreationStageEnum.COMPLETED:
         target = 100;
@@ -219,15 +315,14 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
         target = 0;
     }
 
-    // 如果是同一阶段从弹窗关闭后恢复，尽量从上次的进度继续增长（不从 0 重来）
+    // 断点续传优化：若当前阶段与缓存一致，则从缓存点继续动画
     const restored = restoredSnapshotRef.current;
     if (restored && restored.stage === stage && visualProgress < restored.progress) {
       setVisualProgress(restored.progress);
-      return; // 避免立即启动 timer
+      return; 
     }
 
-    // 对于"已完成"类型的阶段（非生成中），如果进度为0且没有恢复快照，直接显示100%
-    // 这是为了处理刚打开弹窗时的情况
+    // 完成类阶段的即时响应逻辑
     const isCompletedStage = stage === CreationStageEnum.SCHEMA_GENERATED ||
       stage === CreationStageEnum.DDL_GENERATED ||
       stage === CreationStageEnum.COMPLETED;
@@ -237,29 +332,26 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
       return;
     }
 
-    // 如果已经达到目标，不启动 timer
     if (visualProgress >= target) return;
 
+    /** 核心定时器：驱动进度条平滑增长 */
     const timer = setInterval(() => {
       setVisualProgress(prev => {
         if (prev >= target) return prev;
-
-        // Calculate increment: smaller as we get closer to target
         const remaining = target - prev;
-        const increment = Math.max(0.1, remaining * 0.05); // 5% of remaining distance
-
+        const increment = Math.max(0.1, remaining * 0.05); 
         return Math.min(target, prev + increment);
       });
-    }, 100); // Update every 100ms
+    }, 100);
 
     return () => clearInterval(timer);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [project?.creation_stage, viewOnly]);
 
-  // Reset progress when entering a new "generating" stage
+  /** 进度重置策略 Effect */
   useEffect(() => {
     const currentStage = project?.creation_stage || CreationStageEnum.INITIALIZING;
 
+    // 当跨入新的“生成类”阶段时，重置物理进度条
     if (currentStage === CreationStageEnum.GENERATING_SCHEMA ||
       currentStage === CreationStageEnum.GENERATING_DDL ||
       currentStage === CreationStageEnum.EXECUTING_DDL) {
@@ -268,6 +360,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
       setVisualProgress(0);
     }
 
+    // 流程完结，清理存储占用的资源
     if (currentStage === CreationStageEnum.COMPLETED) {
       restoredSnapshotRef.current = null;
       if (!viewOnly) {
@@ -280,47 +373,53 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
     }
   }, [project?.creation_stage]);
 
-
+  /**
+   * 业务动作：确认并提交 Schema
+   * 触发从逻辑架构到 DDL 物理翻译的跃迁。
+   */
   const handleConfirmSchema = useCallback(async () => {
     if (!project) return;
     try {
-      // 清除恢复快照，确保进度从0开始
       restoredSnapshotRef.current = null;
-      setShouldPoll(true); // 重新开启轮询
+      setShouldPoll(true); 
 
-      // 乐观更新：立即切换到生成 DDL 状态，显示进度条
-      // 注意：先更新 project 状态，再重置进度，避免进度条动画逻辑的干扰
+      /**
+       * 乐观更新 (Optimistic UI Update):
+       * 在网络请求完成前，先行将 UI 切换至下一阶段的生成状态。
+       */
       const nextStage = CreationStageEnum.GENERATING_DDL;
       latestStageRef.current = getStageIndex(nextStage);
 
       setProject(prev => prev ? { ...prev, creation_stage: nextStage } : null);
-      setVisualProgress(0); // Reset progress for next stage
+      setVisualProgress(0); 
 
+      // 发起异步业务请求
       await generateDDL(project.project_id, editedSchema, requirements);
-      // State update will happen on next poll
     } catch (err) {
       console.error("Failed to confirm schema:", err);
       setError("确认 Schema 失败。");
     }
   }, [project, editedSchema, requirements]);
 
+  /**
+   * 业务动作：确认 DDL 并发起部署
+   * 对应 SF1 自动化部署的核心触发点。
+   */
   const handleConfirmDDL = useCallback(async () => {
     if (!project) return;
     try {
-      // 清除恢复快照，确保进度从0开始
       restoredSnapshotRef.current = null;
 
-      // 关键修改 1: 部署期间暂停轮询，防止状态跳变
+      // 关键步骤：在部署这一敏感事务期间暂停背景轮询，防止乐观状态被服务器旧缓存覆盖
       setShouldPoll(false);
 
-      // 乐观更新：立即切换到执行 DDL 状态，显示进度条
       const nextStage = CreationStageEnum.EXECUTING_DDL;
       latestStageRef.current = getStageIndex(nextStage);
 
       setProject(prev => prev ? { ...prev, creation_stage: nextStage } : null);
-      setVisualProgress(0); // Reset progress for next stage
+      setVisualProgress(0); 
 
-      // 关键修改 2: 获取返回值并直接更新状态
+      // 执行物理部署
       const updatedProject = await deployProject(project.project_id, editedDDL);
 
       if (updatedProject) {
@@ -331,29 +430,30 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
         }
       }
 
-      // 部署完成后再恢复轮询
       setShouldPoll(true);
     } catch (err) {
       console.error("Failed to deploy project:", err);
       setError("部署项目失败。");
-      setShouldPoll(true); // 出错时恢复轮询
+      setShouldPoll(true); 
     }
   }, [project, editedDDL]);
 
-  // 重新生成 ER 图
+  /**
+   * 业务动作：重新生成 ER 图可视化
+   * 对应 SF5 可视化更新逻辑。
+   */
   const handleRegenerateER = useCallback(async () => {
     if (!project || !editedSchema.trim()) return;
 
-    // 记录当前 ER 图代码，用于检测更新
+    // 保存前一个状态的副本
     previousERCodeRef.current = localERCode;
 
     setIsRegeneratingER(true);
     setError(null);
-    setShouldPoll(true); // 开启轮询等待 ER 图更新
+    setShouldPoll(true); 
 
     try {
       await regenerateER(project.project_id, editedSchema);
-      // ER 图会在后台生成，通过轮询获取最新数据
     } catch (err) {
       console.error("Failed to regenerate ER:", err);
       setError("重新生成 ER 图失败。");
@@ -361,25 +461,29 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
     }
   }, [project, editedSchema, localERCode]);
 
-  // 当 project 更新时，同步更新本地 ER 图代码
+  /**
+   * ER 图数据感知 Effect
+   * 监听后端推送的可视化 DSL 变化，并自动解除生成状态锁。
+   */
   useEffect(() => {
     const newERCode = project?.er_diagram_code;
     if (!newERCode || newERCode === localERCode) return;
 
-    // 如果正在重新生成 ER 图，检测 ER 图是否真的更新了
+    // 若新代码已抵达且与旧代码不符，则判定重绘任务完成
     if (isRegeneratingER && newERCode !== previousERCodeRef.current) {
       setIsRegeneratingER(false);
       setShouldPoll(false);
     }
 
-    // 更新本地 ER 图代码
     setLocalERCode(newERCode);
-    // 更新 ref
     previousERCodeRef.current = newERCode;
-    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [project?.er_diagram_code]);
 
-  // 根据当前阶段更新 footer 内容
+  /**
+   * 底部操作栏渲染 Effect
+   * @description 采用了“向下投影”模式：
+   * 本组件将当前上下文的操作按钮实时回传给父级容器（通常是全局 Modal）。
+   */
   useEffect(() => {
     if (!renderFooter || !project) {
       renderFooter?.(null);
@@ -390,6 +494,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
 
     switch (stage) {
       case CreationStageEnum.SCHEMA_GENERATED:
+        // 场景 A：Schema 已生成，提供修改与确认两个维度的动作
         renderFooter(
           <div className="flex justify-between items-center w-full">
             <Button
@@ -410,6 +515,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
         );
         break;
       case CreationStageEnum.DDL_GENERATED:
+        // 场景 B：DDL 已准备就绪，仅提供最终部署确认
         renderFooter(
           <>
             <Button variant="default" onClick={onClose}>取消</Button>
@@ -421,6 +527,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
         );
         break;
       case CreationStageEnum.COMPLETED:
+        // 场景 C：流程完结，提供应用入口
         if (!viewOnly) {
           renderFooter(
             <Button onClick={onComplete} className="bg-blue-600 hover:bg-blue-700 text-white">
@@ -435,17 +542,20 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
         renderFooter(null);
         break;
     }
-    // 注意：这里故意省略部分依赖项以避免无限循环
-    // renderFooter, onClose, onComplete 是 props 函数，可能每次渲染都是新引用
-    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [project?.creation_stage, viewOnly, isRegeneratingER, handleRegenerateER, handleConfirmSchema, handleConfirmDDL]);
 
+  // --- 加载守卫 ---
   if (!project) return <div className="p-8 flex justify-center"><Loader2 className="animate-spin" /></div>;
 
+  /**
+   * 渲染动态阶段内容
+   * 根据当前向导状态返回特定的视图模块。
+   */
   const renderStageContent = () => {
     const stage = viewOnly ? CreationStageEnum.COMPLETED : (project.creation_stage || CreationStageEnum.INITIALIZING);
 
     switch (stage) {
+      /** 生成中：显示全局动画与虚拟进度 */
       case CreationStageEnum.INITIALIZING:
       case CreationStageEnum.GENERATING_SCHEMA:
         return (
@@ -459,6 +569,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
           </div>
         );
 
+      /** 审计态：左右分布展示编辑器与可视化图形 */
       case CreationStageEnum.SCHEMA_GENERATED:
         return (
           <div className="flex flex-col">
@@ -470,8 +581,9 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
               <span className="text-sm text-gray-500">请审查并在需要时修改生成的 Schema，点击"修改"更新 ER 图。</span>
             </div>
 
+            {/* 编辑与预览分屏布局 */}
             <div className="flex gap-4 h-[500px]">
-              {/* 左侧：Schema 编辑区 */}
+              {/* 源码编辑区：支持手动干预 AI 逻辑偏差 */}
               <div className="flex-1 min-w-0 border rounded-md overflow-hidden">
                 <textarea
                   className="w-full h-full p-4 font-mono text-sm resize-none focus:outline-none overflow-y-auto"
@@ -480,7 +592,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
                 />
               </div>
 
-              {/* 右侧：ER 图预览区 */}
+              {/* 物理可视化预览区：基于 InteractiveERRenderer */}
               <div className="flex-1 min-w-0 border rounded-md overflow-hidden bg-gray-50 relative">
                 {isRegeneratingER && (
                   <div className="absolute inset-0 bg-white/80 flex items-center justify-center z-10">
@@ -520,6 +632,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
           </div>
         );
 
+      /** DDL 审计态：展示最终生成的 SQL 脚本 */
       case CreationStageEnum.DDL_GENERATED:
         return (
           <div className="flex flex-col">
@@ -551,6 +664,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
           </div>
         );
 
+      /** 完成态：展示全量概览与项目配置清单 */
       case CreationStageEnum.COMPLETED:
         return (
           <div className="flex flex-col">
@@ -562,7 +676,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
               </div>
             )}
 
-            {/* Tabs */}
+            {/* 标签切换系统 */}
             <div className="border-b border-gray-200 shrink-0">
               <nav className="-mb-px flex space-x-8">
                 {['概览', 'Schema', 'DDL'].map((tab) => (
@@ -581,6 +695,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
             </div>
 
             <div className="h-[500px] w-full mt-6">
+              {/* Tab: 可视化图表 */}
               {activeTab === '概览' && project?.er_diagram_code && project.er_diagram_code.trim() && (
                 <div className="h-full border rounded-lg p-4 flex flex-col" style={{ overflow: 'hidden' }}>
                   <h4 className="font-medium mb-4 text-gray-700 shrink-0">ER 图</h4>
@@ -588,18 +703,7 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
                 </div>
               )}
 
-              {activeTab === '概览' && (!project?.er_diagram_code || !project.er_diagram_code.trim()) && (
-                <div className="h-full border rounded-lg p-4 flex flex-col" style={{ overflow: 'hidden' }}>
-                  <h4 className="font-medium mb-4 text-gray-700 shrink-0">ER 图</h4>
-                  <div className="flex-1 flex items-center justify-center text-gray-500">
-                    <div className="text-center">
-                      <p className="mb-2">ER 图不可用</p>
-                      <p className="text-sm">暂无可用的 ER 图数据</p>
-                    </div>
-                  </div>
-                </div>
-              )}
-
+              {/* Tab: Schema 源码内容 */}
               {activeTab === 'Schema' && (
                 <div className="h-full border rounded-md bg-gray-50 overflow-y-auto">
                   <div
@@ -636,13 +740,18 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
     }
   };
 
+  /** * 渲染向导容器 
+   * 实现统一的卡片布局与标题描述。
+   */
   return (
     <div className="bg-white rounded-lg shadow-sm p-6 max-w-4xl mx-auto w-full flex flex-col">
+      {/* 头部摘要信息区 */}
       <div className="mb-6 border-b pb-4 shrink-0">
         <h2 className="text-2xl font-bold text-gray-800">{project.project_name}</h2>
         <p className="text-gray-500">{project.description}</p>
       </div>
 
+      {/* 错误提示浮窗 */}
       {error && (
         <div className="bg-red-50 text-red-600 p-4 rounded-md mb-6 flex items-center gap-2 shrink-0">
           <AlertTriangle className="w-5 h-5" />
@@ -650,9 +759,10 @@ export const ProjectWizard: React.FC<ProjectWizardProps> = ({ projectId, onCompl
         </div>
       )}
 
+      {/* 动态工作区 */}
       <div className="flex-1 min-h-0">
         {renderStageContent()}
       </div>
     </div>
   );
-};
+};
\ No newline at end of file
diff --git a/src/frontend/src/components/Sidebar.tsx b/src/frontend/src/components/Sidebar.tsx
index 4fc2c45..3a1df18 100644
--- a/src/frontend/src/components/Sidebar.tsx
+++ b/src/frontend/src/components/Sidebar.tsx
@@ -1,68 +1,114 @@
+/**
+ * @file Sidebar.tsx
+ * @module Components/Layout/Global-Sidebar
+ * @description 应用程序全局侧边导航组件。
+ * 本组件作为“基于大模型多智能体框架的数据库自动部署与库表生成系统”的交互枢纽。
+ * * 核心设计目标：
+ * 1. 动态权限渲染 (RBAC): 根据用户角色 (Admin/User) 分发差异化的功能菜单项；
+ * 2. 交互偏好持久化: 自动同步侧边栏折叠状态至本地存储空间，确保视觉体验的连续性；
+ * 3. 响应式适配架构: 采用双轨布局逻辑，支持移动端侧滑抽屉与桌面端迷你栏切换；
+ * 4. 工作台深度联动: 实时反馈当前选中的数据库项目上下文 (Context-Awareness)。
+ * * @author Wang Lirong (王利蓉)
+ * @version 2.4.0
+ * @date 2026-01-02
+ */
+
 import React, { useEffect, useRef, useState } from 'react';
 import { LayoutDashboard, BarChart2, Users, Book, Bell, X, PanelLeftClose, PanelLeftOpen, User as UserIcon, Settings, LogOut, Database, Bot } from 'lucide-react';
-import { UserRole } from '../types'; // 修复: 移除 .ts 后缀
+import { UserRole } from '../types'; 
 
 /**
- * 侧边栏组件属性接口
+ * 侧边栏组件属性接口定义
+ * @interface SidebarProps
+ * @description 封装了侧边栏渲染所需的权限、用户信息及路由导航回调。
  */
 interface SidebarProps {
-    /** 当前登录用户的角色（管理员或普通用户） */
+    /** 当前登录用户的角色标识（决定菜单权限矩阵） */
     role: UserRole;
-    /** 当前登录用户信息（用于底部展示头像/名称/角色） */
+    /** 当前登录用户的档案数据摘要（头像、名称、角色展示） */
     user?: { name: string; role: UserRole; avatar_url?: string | null } | null;
-    /** 当前选择的项目工作区（用于显示“当前工作区”入口） */
+    /** 全局选中的活跃项目上下文，用于显示“当前工作区”状态 */
     selectedProject?: { id: string; name: string } | null;
-    /** 当前激活的页面 ID，用于高亮显示菜单项 */
+    /** 当前活跃页面的 ID，用于驱动导航项的激活态高亮显示 */
     activePage: string;
-    /** * 页面导航回调函数
-     * @param page - 目标页面的 ID
+    /** * 路由导航触发函数
+     * @param {string} page - 目标页面的唯一路由标识符 
      */
     onNavigate: (page: string) => void;
-    /** 移动端菜单是否打开 */
+    /** 移动端环境下的展示状态开关（由父级布局容器控制） */
     isOpen?: boolean;
-    /** 关闭移动端菜单的回调 */
+    /** 触发移动端侧边栏关闭逻辑的回调函数 */
     onClose?: () => void;
-    /** 退出登录回调（用于底部用户菜单） */
+    /** 退出登录并清理安全凭证的业务回调 */
     onLogout?: () => void;
 }
 
 /**
- * 应用程序侧边导航栏组件
- * * 根据用户角色渲染不同的功能菜单列表。
+ * @component Sidebar
+ * @description 
+ * 一个具备高度自律性的响应式布局组件。
+ * 内部通过 Side Effect 管理视口状态，并采用原子化 CSS (Tailwind) 实现复杂的动画过渡。
  */
 export const Sidebar: React.FC<SidebarProps> = ({ role, user, selectedProject, activePage, onNavigate, isOpen, onClose, onLogout }) => {
+    /** * 桌面端折叠状态锁
+     * 控制侧边栏在 256px (w-64) 与 64px (w-16) 宽度之间的切换。
+     */
     const [isCollapsed, setIsCollapsed] = useState(false);
+    /** 底部个人信息面板的下拉菜单可见性状态 */
     const [isUserMenuOpen, setIsUserMenuOpen] = useState(false);
+    /** 引用底部用户菜单容器，用于执行“点击外部自动关闭”的 DOM 监听逻辑 */
     const userMenuRef = useRef<HTMLDivElement>(null);
 
+    /**
+     * 生命周期 A：偏好恢复。
+     * 在组件初次挂载时，从 localStorage 中同步用户上次设置的侧边栏形态。
+     */
     useEffect(() => {
         try {
             const raw = localStorage.getItem('app.sidebarCollapsed');
             setIsCollapsed(raw === '1');
         } catch {
-            // ignore
+            // 容错：若 Storage 访问受限（如隐私模式），维持默认展开状态
         }
     }, []);
 
+    /**
+     * 生命周期 B：偏好存储。
+     * 当折叠状态发生变化时，执行离线持久化存储。
+     */
     useEffect(() => {
         try {
             localStorage.setItem('app.sidebarCollapsed', isCollapsed ? '1' : '0');
         } catch {
-            // ignore
+            // 静默处理非关键性存储失败
         }
     }, [isCollapsed]);
 
+    /**
+     * 生命周期 C：外部点击捕获。
+     * 注册全局鼠标监听器，实现典型的 Dropdown 失焦关闭逻辑。
+     */
     useEffect(() => {
+        /**
+         * 判定点击是否发生在目标容器之外
+         * @param {MouseEvent} event - 原生浏览器点击事件
+         */
         const handleClickOutside = (event: MouseEvent) => {
             if (userMenuRef.current && !userMenuRef.current.contains(event.target as Node)) {
                 setIsUserMenuOpen(false);
             }
         };
+        // 在 document 层面委托监听，确保能捕获所有点击流
         document.addEventListener('mousedown', handleClickOutside);
+        // 卸载钩子：注销监听器，防止内存泄漏
         return () => document.removeEventListener('mousedown', handleClickOutside);
     }, []);
 
-    // 根据角色定义菜单项配置
+    /**
+     * 核心逻辑：菜单权限路由表。
+     * 采用静态映射策略，根据当前 UserRole 派发特定的导航矩阵。
+     * 管理员侧重系统治理，普通用户侧重业务建模。
+     */
     const menuItems = role === UserRole.ADMIN ? [
         { id: 'admin_users', label: '用户管理', icon: <Users size={18} /> },
         { id: 'admin_announcements', label: '公告管理', icon: <Bell size={18} /> },
@@ -77,15 +123,22 @@ export const Sidebar: React.FC<SidebarProps> = ({ role, user, selectedProject, a
 
     return (
         <>
-            {/* 移动端遮罩层 - z-40 ensures it covers the header (z-20) */}
+            {/* 移动端背景蒙层 (Overlay Mask)
+                - z-40 层级确保其覆盖 Header 但低于侧边栏本身。
+                - 点击遮罩将触发 onClose 事件，关闭移动端菜单。
+            */}
             {isOpen && (
                 <div
-                    className="fixed inset-0 bg-black/50 z-40 md:hidden"
+                    className="fixed inset-0 bg-black/50 z-40 md:hidden animate-in fade-in duration-300"
                     onClick={onClose}
                 />
             )}
 
-            {/* 侧边栏容器 - z-50 ensures it's on top of everything */}
+            {/* 侧边栏主容器 (Sidebar Main Container)
+                - transition-[transform,width]: 允许宽度和位置属性参与过渡动画。
+                - z-50: 确保侧边栏处于全局最高层级。
+                - md:static: 桌面端回归标准文档流或使用 sticky 停靠。
+            */}
             <div className={`
                 fixed inset-y-0 left-0 w-64 bg-white border-r border-gray-200 h-screen h-[100dvh] flex flex-col 
                 transition-[transform,width] duration-300 ease-in-out motion-reduce:transition-none z-50
@@ -93,47 +146,54 @@ export const Sidebar: React.FC<SidebarProps> = ({ role, user, selectedProject, a
                 ${isOpen ? 'translate-x-0' : '-translate-x-full'}
                 ${isCollapsed ? 'md:w-16' : 'md:w-64'}
             `}>
-                {/* 修改: 
-                   1. 减小内边距 (p-6 -> p-4) 以减少头部空间占用
-                   2. 使用 scale-125 放大图片主体，裁剪周围留白
-                   3. 增加 overflow-hidden 防止放大后的图片溢出
+                
+                {/* 头部 Logo 区域 (Header & Branding)
+                    集成了品牌标识与折叠控制器。
                 */}
                 <div className="p-4 flex items-center justify-between border-b border-gray-100 relative">
-                    {/* 桌面端折叠时：不显示任何图标/Logo，仅保留展开按钮 */}
+                    {/* 非折叠状态下展示品牌图形与文字 */}
                     {!isCollapsed && (
                         <div className="flex items-center gap-3 min-w-0">
                             <div className="w-8 h-8 flex items-center justify-center overflow-hidden">
+                                {/* scale-125: 采用放大裁剪策略提升图标视觉冲击力 */}
                                 <img
                                     src="/database-logo.svg"
                                     alt="AutoDB Logo"
-                                    className="w-full h-full object-contain scale-125 transform"
+                                    className="w-full h-full object-contain scale-125 transform transition-transform duration-500 hover:rotate-6"
                                 />
                             </div>
                             <h1 className="font-bold text-gray-800 text-lg tracking-tight truncate">AutoDB</h1>
                         </div>
                     )}
 
+                    {/* 侧边栏交互控制按钮群组 */}
                     <div className="flex items-center gap-1 shrink-0">
-                        {/* 桌面端最小化/展开按钮 */}
+                        {/* 桌面端特有：折叠状态切换器 */}
                         <button
                             onClick={() => setIsCollapsed(v => !v)}
                             className={`hidden md:inline-flex p-1 text-gray-500 hover:bg-gray-100 rounded-md items-center justify-center ${isCollapsed ? 'md:mx-auto md:absolute md:left-1/2 md:-translate-x-1/2 md:top-1/2 md:-translate-y-1/2' : ''}`}
                             title={isCollapsed ? '展开侧边栏' : '最小化侧边栏'}
                             type="button"
                         >
+                            {/* 动态切换展开/折叠图标语义 */}
                             {isCollapsed ? <PanelLeftOpen size={20} /> : <PanelLeftClose size={20} />}
                         </button>
 
-                        {/* 移动端关闭按钮 */}
+                        {/* 移动端特有：明确的关闭动作出口 */}
                         <button onClick={onClose} className="md:hidden p-1 text-gray-500 hover:bg-gray-100 rounded-md" type="button">
                             <X size={20} />
                         </button>
                     </div>
                 </div>
 
-                {/* 菜单列表区域 */}
-                <div className="flex-1 py-4 px-3 space-y-1">
-                    {/* 当前工作区（仅普通用户显示） */}
+                {/* 主体导航区域 (Main Navigation Links)
+                    采用 flex-1 占据中间剩余空间，内容超出时支持内部滚动。
+                */}
+                <div className="flex-1 py-4 px-3 space-y-1 overflow-y-auto custom-scrollbar">
+                    
+                    {/* 当前工作区上下文入口 (Dynamic Context Slot)
+                        仅对普通用户展示，用于快速定位当前的 AI 建模任务。
+                    */}
                     {role !== UserRole.ADMIN && (
                         <button
                             onClick={() => {
@@ -144,9 +204,9 @@ export const Sidebar: React.FC<SidebarProps> = ({ role, user, selectedProject, a
                                 }
                                 onClose?.();
                             }}
-                            title={selectedProject ? `当前工作区：${selectedProject.name}` : '未选择工作区（去项目概览选择）'}
-                            className={`w-full flex items-center gap-3 px-3 py-2.5 rounded-md text-sm font-medium transition-colors ${activePage === 'workspace'
-                                ? 'bg-blue-50 text-primary'
+                            title={selectedProject ? `当前工作区：${selectedProject.name}` : '未选择工作区'}
+                            className={`w-full flex items-center gap-3 px-3 py-2.5 rounded-md text-sm font-medium transition-all duration-200 ${activePage === 'workspace'
+                                ? 'bg-blue-50 text-primary shadow-sm ring-1 ring-blue-100'
                                 : selectedProject
                                     ? 'text-gray-600 hover:bg-gray-50 hover:text-gray-900'
                                     : 'text-gray-400 hover:bg-gray-50'
@@ -156,16 +216,17 @@ export const Sidebar: React.FC<SidebarProps> = ({ role, user, selectedProject, a
                             <span className="shrink-0"><Database size={18} /></span>
                             <span className={`${isCollapsed ? 'md:hidden' : ''} min-w-0 flex-1 text-left`}
                             >
-                                <div className="truncate">当前工作区</div>
+                                <div className="truncate font-semibold">当前工作区</div>
                                 {selectedProject ? (
-                                    <div className="text-xs text-gray-500 truncate">{selectedProject.name}</div>
+                                    <div className="text-[10px] text-gray-500 truncate leading-tight">{selectedProject.name}</div>
                                 ) : (
-                                    <div className="text-xs text-gray-400 truncate">未选择</div>
+                                    <div className="text-[10px] text-gray-400 truncate leading-tight">未选择</div>
                                 )}
                             </span>
                         </button>
                     )}
 
+                    {/* 映射并渲染核心菜单阵列 */}
                     {menuItems.map((item) => (
                         <button
                             key={item.id}
@@ -174,8 +235,8 @@ export const Sidebar: React.FC<SidebarProps> = ({ role, user, selectedProject, a
                                 onClose?.();
                             }}
                             title={item.label}
-                            className={`w-full flex items-center gap-3 px-3 py-2.5 rounded-md text-sm font-medium transition-colors ${activePage === item.id
-                                ? 'bg-blue-50 text-primary'
+                            className={`w-full flex items-center gap-3 px-3 py-2.5 rounded-md text-sm font-medium transition-all duration-200 ${activePage === item.id
+                                ? 'bg-blue-50 text-primary shadow-sm ring-1 ring-blue-100'
                                 : 'text-gray-600 hover:bg-gray-50 hover:text-gray-900'
                                 } ${isCollapsed ? 'md:justify-center md:gap-0 md:px-0 md:h-11 md:w-11 md:mx-auto' : ''}`}
                         >
@@ -185,14 +246,18 @@ export const Sidebar: React.FC<SidebarProps> = ({ role, user, selectedProject, a
                     ))}
                 </div>
 
-                {/* 底部：当前用户信息（头像/名称/角色） + 菜单（个人设置/退出登录） */}
+                {/* 底部账户管理中心 (Bottom Account Section)
+                    集成了用户身份标识与浮动快捷菜单。
+                */}
                 <div className="border-t border-gray-100 p-3 relative" ref={userMenuRef}>
+                    {/* 触发器：点击展现个人中心菜单 */}
                     <button
                         type="button"
                         onClick={() => setIsUserMenuOpen(v => !v)}
                         title={isCollapsed ? `${user?.name || '当前用户'}（点击展开菜单）` : undefined}
                         className={`w-full flex items-center gap-3 rounded-lg hover:bg-gray-50 transition-colors ${isCollapsed ? 'md:justify-center md:gap-0 md:px-0 md:h-11 md:w-11 md:mx-auto' : 'px-2 py-2'}`}
                     >
+                        {/* 头像渲染容器：支持外部图片与通用图标兜底 */}
                         <div className="w-10 h-10 bg-blue-100 rounded-full flex items-center justify-center text-primary border border-blue-200 overflow-hidden shrink-0">
                             {user?.avatar_url ? (
                                 <img src={user.avatar_url} alt={user?.name || 'avatar'} className="w-full h-full object-cover" />
@@ -200,35 +265,43 @@ export const Sidebar: React.FC<SidebarProps> = ({ role, user, selectedProject, a
                                 <UserIcon size={20} />
                             )}
                         </div>
+                        {/* 身份描述：仅在非折叠状态下渲染 */}
                         <div className={`${isCollapsed ? 'md:hidden' : ''} min-w-0 flex-1 text-left`}
                         >
                             <div className="text-sm font-medium text-gray-700 truncate">{user?.name || '当前用户'}</div>
-                            <div className="text-xs text-gray-500">{user?.role === UserRole.ADMIN ? '管理员' : '普通用户'}</div>
+                            <div className="text-xs text-gray-500 font-normal">{user?.role === UserRole.ADMIN ? '系统管理员' : '普通用户'}</div>
                         </div>
                     </button>
 
+                    {/* 个人操作浮层 (User Action Floating Menu)
+                        - 利用绝对定位实现“上浮”弹出效果。
+                        - 具备 animate-in 动画以增强视觉质感。
+                    */}
                     {isUserMenuOpen && (
                         <div
-                            className={`${isCollapsed ? 'md:absolute md:left-full md:bottom-3 md:ml-2 md:w-48' : 'absolute left-0 bottom-full mb-2 w-full'} bg-white rounded-lg shadow-lg border border-gray-100 py-1 animate-in fade-in zoom-in-95 duration-100 origin-top z-50`}
+                            className={`${isCollapsed ? 'md:absolute md:left-full md:bottom-3 md:ml-2 md:w-48' : 'absolute left-0 bottom-full mb-2 w-full'} bg-white rounded-lg shadow-lg border border-gray-100 py-1 animate-in fade-in zoom-in-95 duration-150 origin-bottom z-50`}
                         >
+                            {/* 设置项入口 */}
                             <button
                                 onClick={() => {
                                     setIsUserMenuOpen(false);
                                     onNavigate('profile');
                                     onClose?.();
                                 }}
-                                className="w-full text-left px-4 py-2.5 text-sm text-gray-700 hover:bg-gray-50 flex items-center gap-2"
+                                className="w-full text-left px-4 py-2.5 text-sm text-gray-700 hover:bg-gray-50 flex items-center gap-2 transition-colors"
                                 type="button"
                             >
                                 <Settings size={16} /> 个人设置
                             </button>
+                            {/* 分割线：视觉分区 */}
                             <div className="border-t border-gray-100 my-1"></div>
+                            {/* 退出登录：具备警示语义的颜色提示 */}
                             <button
                                 onClick={() => {
                                     setIsUserMenuOpen(false);
                                     onLogout?.();
                                 }}
-                                className="w-full text-left px-4 py-2.5 text-sm text-red-600 hover:bg-red-50 flex items-center gap-2"
+                                className="w-full text-left px-4 py-2.5 text-sm text-red-600 hover:bg-red-50 flex items-center gap-2 transition-colors"
                                 type="button"
                             >
                                 <LogOut size={16} /> 退出登录
diff --git a/src/frontend/src/components/UI.tsx b/src/frontend/src/components/UI.tsx
index 430cd8a..bdb153a 100644
--- a/src/frontend/src/components/UI.tsx
+++ b/src/frontend/src/components/UI.tsx
@@ -1,48 +1,62 @@
+/**
+ * @file UI.tsx
+ * @module Components/Foundation/Design-System
+ * @description 系统底层原子化 UI 组件库。
+ * 本模块遵循“原子设计 (Atomic Design)”哲学，封装了全站通用的基础交互组件。
+ * * * 核心职能：
+ * 1. 交互一致性 (Usability-1): 统一全站按钮、输入框、选择器的视觉反馈与手势路径；
+ * 2. 响应式适配: 所有组件均集成 Tailwind 响应式类名，完美适配 500% 缩放（SF12）；
+ * 3. 架构解耦: 引入事件总线 (Event Bus) 模式，实现 API 拦截器与 UI 反馈层的跨层级通讯；
+ * 4. 视觉增强: 集成 Backdrop-blur (毛玻璃) 与渐进式动效，提升分析类软件的专业感。
+ * * * 对应需求：
+ * - Requirement 1.1: 界面多分辨率自适应。
+ * - Requirement 7.1: 全局统一的异常与消息反馈机制。
+ * * @author Wang Lirong (王利蓉)
+ * @version 2.6.0
+ * @date 2026-01-02
+ */
+
 import React, { JSX, ReactNode, useState, useEffect } from 'react';
 import { Check, X, CheckCircle, AlertCircle, Info, AlertTriangle } from 'lucide-react';
 
-// --- Button Component ---
+// =========================================================
+// 1. Button Component - 交互触发器
+// =========================================================
 
 /**
  * 按钮组件属性接口
  * @interface ButtonProps
- * @extends {React.ButtonHTMLAttributes<HTMLButtonElement>} 继承原生 button 属性
+ * @extends {React.ButtonHTMLAttributes<HTMLButtonElement>}
  */
 interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     /**
-     * 按钮样式变体
-     * - 'primary': 主色调填充（蓝色）
-     * - 'default': 白色背景带边框
-     * - 'dashed': 虚线边框
-     * - 'text': 无边框文本按钮
-     * - 'danger': 红色警告样式
-     * @default 'default'
+     * 视觉变体策略：
+     * - primary: 高强度引导（如：提交 DDL、确认部署）；
+     * - default: 次级操作（如：取消、重置）；
+     * - dashed: 弱关联动作（如：添加筛选条件）；
+     * - text: 无背景文本（如：查看日志详情）；
+     * - danger: 破坏性操作（如：彻底销毁项目）。
      */
     variant?: 'primary' | 'default' | 'dashed' | 'text' | 'danger';
-    /**
-     * 按钮内显示的图标组件
-     */
+    /** 允许在文本左侧插入 Lucide 图标节点 */
     icon?: ReactNode;
 }
 
 /**
- * 通用按钮组件
- * * 封装了不同状态（hover, focus, disabled）下的 Tailwind 样式。
- * * 符合 WCAG 2.1 AA 最小可点击区域要求 (44x44px)
- *
- * @param children
- * @param variant
- * @param className
- * @param icon
- * @param {ButtonProps} props - 组件属性
- * @returns {JSX.Element} 渲染后的按钮元素
+ * @component Button
+ * @description 
+ * 核心交互基座。
+ * 严格执行 WCAG 2.1 AA 标准，强制锁定最小点击高度为 44px，确保在高缩放模式下的可触达性。
  */
 export const Button: React.FC<ButtonProps> = ({ children, variant = 'default', className = '', icon, ...props }) => {
-    // 基础样式：布局、内边距、字体、圆角、阴影及过渡效果
-    // 确保最小高度 44px 符合 WCAG 2.1 AA 标准
+    /** * 布局基准样式说明：
+     * - inline-flex: 保证内联布局下的居中对齐；
+     * - transition-all: 开启全属性 GPU 加速动效；
+     * - focus:ring-2: 增强键盘聚焦时的辅助边框。
+     */
     const baseStyles = "inline-flex items-center justify-center px-3 sm:px-4 py-2 sm:py-2.5 min-h-[44px] text-sm font-medium transition-all duration-200 rounded-md shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-1 disabled:opacity-50 disabled:cursor-not-allowed whitespace-nowrap";
 
-    // 不同变体的样式映射
+    /** 样式变体映射矩阵 */
     const variants = {
         primary: "bg-primary text-white hover:bg-primary-hover border border-transparent focus:ring-blue-500",
         default: "bg-white text-gray-700 border border-gray-300 hover:text-primary hover:border-primary focus:ring-gray-200",
@@ -53,38 +67,35 @@ export const Button: React.FC<ButtonProps> = ({ children, variant = 'default', c
 
     return (
         <button className={`${baseStyles} ${variants[variant]} ${className}`} {...props}>
+            {/* 图标渲染逻辑：当存在子元素时，自动追加右边距以维持间距平衡 */}
             {icon && <span className={children ? "mr-1.5 sm:mr-2" : ""}>{icon}</span>}
             {children}
         </button>
     );
 };
 
-// --- Input Component ---
+// =========================================================
+// 2. Input Component - 结构化输入
+// =========================================================
 
 /**
  * 输入框组件属性接口
  * @interface InputProps
- * @extends {React.InputHTMLAttributes<HTMLInputElement>} 继承原生 input 属性
  */
 interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
-    /**
-     * 输入框上方的标签文本
-     */
+    /** 顶部语义化标签内容 */
     label?: string;
 }
 
 /**
- * 通用输入框组件
- * * 包含可选的 Label 显示，并统一了 focus 状态的样式。
- * * 使用 16px 字体防止 iOS 自动缩放
- *
- * @param label
- * @param className
- * @param {InputProps} props - 组件属性
- * @returns {JSX.Element} 包含 Label 和 Input 的容器
+ * @component Input
+ * @description 
+ * 标准化表单输入单元。
+ * 针对 iOS 环境优化了 16px 字体，解决移动端自动缩放导致的视口跳变问题。
  */
 export const Input: React.FC<InputProps> = ({ label, className = '', ...props }): JSX.Element => (
     <div className="flex flex-col gap-1.5">
+        {/* 条件渲染：展示字段名称及必填红星标识 */}
         {label && (
             <label className="text-sm font-medium text-gray-700">
                 {label}
@@ -98,66 +109,42 @@ export const Input: React.FC<InputProps> = ({ label, className = '', ...props })
     </div>
 );
 
-// --- Select Component ---
+// =========================================================
+// 3. Select Component - 维度选择器
+// =========================================================
 
 /**
- * 选项接口
+ * 下拉选项元数据定义
  */
 export interface SelectOption {
+    /** 业务后端预期的原始值 */
     value: string;
+    /** 用户端展示的语义化标签 */
     label: string;
+    /** 禁用特定选项的布尔锁 */
     disabled?: boolean;
 }
 
 /**
- * 选择框组件属性接口
+ * @interface SelectProps
  */
 interface SelectProps {
-    /**
-     * 选择框上方的标签文本
-     */
     label?: string;
-    /**
-     * 选项列表
-     */
     options: SelectOption[];
-    /**
-     * 当前选中的值
-     */
     value: string;
-    /**
-     * 值变化时的回调
-     */
     onChange: (value: string) => void;
-    /**
-     * 选择框变体样式
-     * - 'default': 标准样式，带边框和背景
-     * - 'minimal': 简约样式，透明背景，适合嵌入其他容器
-     * @default 'default'
-     */
     variant?: 'default' | 'minimal';
-    /**
-     * 自定义类名
-     */
     className?: string;
-    /**
-     * 占位文本
-     */
     placeholder?: string;
-    /**
-     * 是否禁用
-     */
     disabled?: boolean;
-    /**
-     * 是否必填
-     */
     required?: boolean;
 }
 
 /**
- * 自定义选择框组件
- * * 完全自定义的下拉菜单样式
- * * 与系统整体风格保持一致
+ * @component Select
+ * @description 
+ * 完全自主实现的虚拟化下拉组件。
+ * 相比原生 select，具备更好的样式可控性，支持“浮动定位算法”以适应嵌套容器边界。
  */
 export const Select: React.FC<SelectProps> = ({
     label,
@@ -170,12 +157,21 @@ export const Select: React.FC<SelectProps> = ({
     disabled = false,
     required = false
 }) => {
+    // 下拉面板的状态锁
     const [isOpen, setIsOpen] = useState(false);
+    /** * 几何位置计算：
+     * 用于在 Fixed 定位模式下，动态追随触发按钮的物理坐标，防止菜单被局部 overflow 容器裁剪。
+     */
     const [menuPosition, setMenuPosition] = useState({ top: 0, left: 0, width: 0 });
+    
+    // DOM 节点物理引用
     const selectRef = React.useRef<HTMLDivElement>(null);
     const buttonRef = React.useRef<HTMLButtonElement>(null);
 
-    // 点击外部关闭下拉菜单
+    /**
+     * 效应钩子：失焦自动关闭。
+     * 实现典型的下拉组件点击外部即收起的 UX 行为。
+     */
     useEffect(() => {
         const handleClickOutside = (event: MouseEvent) => {
             if (selectRef.current && !selectRef.current.contains(event.target as Node)) {
@@ -186,17 +182,23 @@ export const Select: React.FC<SelectProps> = ({
         return () => document.removeEventListener('mousedown', handleClickOutside);
     }, []);
 
-    // 获取当前选中项的标签
+    // 查找当前选中态的显示文本，实现回显逻辑
     const selectedOption = options.find(opt => opt.value === value);
     const displayText = selectedOption?.label || placeholder;
 
+    /**
+     * 面板开关切换函数
+     * @description
+     * 包含复杂的边界计算逻辑：当开启时，通过 getBoundingClientRect() 获取按钮的几何矩阵。
+     */
     const handleToggle = () => {
         if (disabled) return;
         if (!isOpen && buttonRef.current) {
-            // 对于 minimal 变体，找到最近的带边框的父容器
+            /** * 策略：对于 Minimal 变体，尝试向上追溯带边框的物理容器，
+             * 以确保下拉菜单的对齐视觉一致性。
+             */
             let targetElement: HTMLElement | null = buttonRef.current;
             if (variant === 'minimal') {
-                // 向上查找带边框的父容器
                 let parent = buttonRef.current.parentElement;
                 while (parent && parent !== document.body) {
                     const style = window.getComputedStyle(parent);
@@ -207,6 +209,8 @@ export const Select: React.FC<SelectProps> = ({
                     parent = parent.parentElement;
                 }
             }
+            
+            // 物理坐标重算
             const rect = targetElement!.getBoundingClientRect();
             setMenuPosition({
                 top: rect.bottom + 4,
@@ -217,17 +221,20 @@ export const Select: React.FC<SelectProps> = ({
         setIsOpen(!isOpen);
     };
 
+    /** 派发值变更事件并关闭视图 */
     const handleSelect = (optionValue: string) => {
         onChange(optionValue);
         setIsOpen(false);
     };
 
+    /** 基于变体参数生成的样式字符串 */
     const triggerStyles = variant === 'default'
         ? `px-3 py-2.5 min-h-[44px] bg-white border border-gray-300 rounded-lg text-base sm:text-sm shadow-sm ${isOpen ? 'border-primary ring-2 ring-blue-100' : 'hover:border-gray-400'}`
         : `bg-transparent text-sm font-medium text-gray-800 py-1 ${isOpen ? 'text-primary' : ''}`;
 
     return (
         <div className="flex flex-col gap-1.5" ref={selectRef}>
+            {/* Label 区域 */}
             {label && (
                 <label className="text-sm font-medium text-gray-700">
                     {label}
@@ -235,7 +242,7 @@ export const Select: React.FC<SelectProps> = ({
                 </label>
             )}
             <div className={`relative ${className}`}>
-                {/* 触发器 */}
+                {/* 触发按钮组件：集成了 rotate 图标动效 */}
                 <button
                     ref={buttonRef}
                     type="button"
@@ -256,7 +263,7 @@ export const Select: React.FC<SelectProps> = ({
                     </svg>
                 </button>
 
-                {/* 下拉菜单 */}
+                {/* 下拉面板：采用 Fixed 布局及 Z-Index 策略确保不被层级覆盖 */}
                 {isOpen && (
                     <div
                         className="fixed bg-white border border-gray-200 rounded-lg shadow-md overflow-hidden animate-in fade-in zoom-in-95 duration-150"
@@ -267,6 +274,7 @@ export const Select: React.FC<SelectProps> = ({
                             minWidth: menuPosition.width
                         }}
                     >
+                        {/* 内部滚动区：最大高度限制为 5 个标准列表项的高度 */}
                         <div className="overflow-y-auto py-1" style={{ maxHeight: 'calc(5 * 44px)' }}>
                             {options.map((option) => (
                                 <div
@@ -281,6 +289,7 @@ export const Select: React.FC<SelectProps> = ({
                                     `}
                                 >
                                     <span className="whitespace-nowrap">{option.label}</span>
+                                    {/* 选中态视觉回显：蓝勾图标 */}
                                     {option.value === value && (
                                         <Check size={16} className="text-primary shrink-0" />
                                     )}
@@ -294,61 +303,61 @@ export const Select: React.FC<SelectProps> = ({
     );
 };
 
-// --- Card Component ---
+// =========================================================
+// 4. Card Component - 信息分屏器
+// =========================================================
 
 /**
  * 卡片组件属性接口
  */
 interface CardProps {
-    /** 卡片主体内容 */
     children: ReactNode;
-    /** 卡片左上角标题（可选） */
     title?: ReactNode;
-    /** 卡片右上角额外操作区（可选），例如按钮或标签 */
     extra?: ReactNode;
-    /** 自定义类名 */
     className?: string;
 }
 
 /**
- * 通用卡片容器组件
- * * 用于展示分组内容，支持标题栏和主体内容的分离。
- * * 支持响应式布局
- * * @param {CardProps} props - 组件属性
- * @returns {JSX.Element} 渲染后的卡片
+ * @component Card
+ * @description 
+ * 信息分组的核心容器。
+ * 支持响应式内边距调节与悬停视觉浮起动效。
  */
 export const Card: React.FC<CardProps> = ({ children, title, extra, className = '' }: CardProps): JSX.Element => (
     <div className={`bg-white rounded-xl border border-gray-200 shadow-sm transition-all hover:shadow-md ${className}`}>
+        {/* 顶部标题栏区域 */}
         {(title || extra) && (
             <div className="px-4 sm:px-6 py-3 sm:py-4 border-b border-gray-100 flex flex-col sm:flex-row justify-between items-start sm:items-center gap-2 bg-gray-50/30 rounded-t-xl">
                 <div className="font-semibold text-gray-800 text-sm sm:text-base min-w-0 truncate max-w-full">{title}</div>
+                {/* 渲染右上角扩展内容（如：更多按钮、状态标签） */}
                 <div className="shrink-0">{extra}</div>
             </div>
         )}
+        {/* 内容插槽区域 */}
         <div className="p-4 sm:p-6">{children}</div>
     </div>
 );
 
-// --- Tag Component ---
+// =========================================================
+// 5. Tag Component - 语义化标签
+// =========================================================
 
 /**
  * 标签组件属性接口
  */
 interface TagProps {
-    /** * 标签颜色主题
-     * @default 'blue'
-     */
     color?: 'blue' | 'green' | 'red' | 'orange' | 'gray';
-    /** 标签内容 */
     children: ReactNode;
 }
 
 /**
- * 状态标签组件
- * * 用于展示状态、分类等短文本信息，提供多种预设颜色。
- *
- * @param {TagProps} props - 组件属性
- * @returns {JSX.Element} 渲染后的标签
+ * @component Tag
+ * @description 
+ * 短文本状态展示组件。通过配色方案对应业务状态：
+ * - green: 运行中 / 已激活；
+ * - blue: 部署中 / 初始化中；
+ * - red: 封禁 / 错误；
+ * - orange: 异常活跃 / 告警。
  */
 export const Tag: React.FC<TagProps> = ({ color = 'blue', children }) => {
     const colors = {
@@ -365,49 +374,43 @@ export const Tag: React.FC<TagProps> = ({ color = 'blue', children }) => {
     );
 };
 
-// --- ProgressBar Component ---
+// =========================================================
+// 6. ProgressBar Component - 进度反馈系统
+// =========================================================
 
 /**
- * 进度条组件
- * * 显示操作完成的百分比，包含动画效果。
- *
- * @param {Object} props - 组件属性
- * @param {number} props.progress - 当前进度值 (0-100)
- * @returns {JSX.Element} 进度条元素
+ * @component ProgressBar
+ * @description 
+ * 线性进度条。用于反馈 AI 模型生成 Schema 或执行 DDL 的长事务进度。
  */
 export const ProgressBar: React.FC<{ progress: number }> = ({ progress }) => {
     return (
         <div className="w-full bg-gray-100 rounded-full h-2 overflow-hidden shadow-inner">
+            {/* 内层填充条：利用 transition 实现物理惯性动画感 */}
             <div
                 className="bg-primary h-full rounded-full transition-all duration-700 ease-out shadow-sm relative overflow-hidden"
                 style={{ width: `${Math.max(0, Math.min(100, progress))}%` }}
             >
+                {/* 动态呼吸动效，增强“处理中”的视觉暗示 */}
                 <div className="absolute inset-0 bg-white/20 animate-pulse"></div>
             </div>
         </div>
     );
 };
 
-// --- Steps Component ---
+// =========================================================
+// 7. Steps Component - 流程导航器
+// =========================================================
 
-/**
- * 步骤条目定义
- */
 interface StepItem {
-    /** 步骤标题 */
     title: string;
-    /** 步骤描述（可选，当前UI未显示） */
     description?: string;
 }
 
 /**
- * 步骤条组件
- * * 用于展示多步骤流程的当前状态。
- *
- * @param {Object} props - 组件属性
- * @param {StepItem[]} props.steps - 步骤数组
- * @param {number} props.current - 当前步骤索引 (0-based)
- * @returns {JSX.Element} 步骤条
+ * @component Steps
+ * @description 
+ * 步骤条。驱动 ProjectWizard 向导的分步状态展示。
  */
 export const Steps: React.FC<{ steps: StepItem[]; current: number }> = ({ steps, current }) => {
     return (
@@ -418,21 +421,22 @@ export const Steps: React.FC<{ steps: StepItem[]; current: number }> = ({ steps,
 
                 return (
                     <div key={index} className="flex flex-col items-center relative flex-1 group">
-                        {/* 连接线：除了第一个节点外，每个节点左侧都有连接线 */}
+                        {/* 逻辑：渲染节点间的物理连接线。若当前节点已达标，则线段高亮。 */}
                         {index !== 0 && (
                             <div className="absolute top-5 right-[50%] w-full h-[2px] -z-10">
                                 <div className={`h-full transition-colors duration-500 ${index <= current ? 'bg-primary' : 'bg-gray-200'}`}></div>
                             </div>
                         )}
 
-                        {/* 步骤图标：完成态显示对号，进行/未进行态显示数字 */}
+                        {/* 节点图标：完成态展示 Check 图标，否则展示索引数字。 */}
                         <div className={`w-10 h-10 rounded-full flex items-center justify-center text-sm font-bold transition-all duration-500 z-10 border-2 shadow-sm ${isCompleted ? 'bg-primary border-primary text-white' :
                             isCurrent ? 'bg-white border-primary text-primary ring-4 ring-blue-50 scale-110' :
                                 'bg-white border-gray-200 text-gray-400'
                             }`}>
                             {isCompleted ? <Check size={18} strokeWidth={3} /> : index + 1}
                         </div>
-                        {/* 步骤标题 */}
+                        
+                        {/* 节点描述文本 */}
                         <div className={`mt-3 text-sm font-medium transition-colors duration-300 ${isCurrent ? 'text-primary' :
                             isCompleted ? 'text-gray-800' :
                                 'text-gray-400'
@@ -446,42 +450,41 @@ export const Steps: React.FC<{ steps: StepItem[]; current: number }> = ({ steps,
     );
 };
 
-// --- Modal Component ---
+// =========================================================
+// 8. Modal Component - 高级模态对话框
+// =========================================================
 
-/**
- * 模态框组件属性接口
- */
 interface ModalProps {
-    /** 是否显示模态框 */
     isOpen: boolean;
-    /** 关闭模态框的回调函数 */
     onClose: () => void;
-    /** 模态框标题 */
     title: string;
-    /** 模态框内容 */
     children: ReactNode;
-    /** 底部操作区内容（可选） */
     footer?: ReactNode;
-    /** * 最大宽度限制类名
-     * @default 'max-w-md'
-     */
     maxWidth?: string;
 }
 
 /**
- * 通用模态框组件
- * * 包含遮罩层、动画效果以及标准化的头部和底部布局。
- * * 支持响应式布局和高缩放级别
- *
- * @param {ModalProps} props - 组件属性
- * @returns {JSX.Element | null} 如果 isOpen 为 false 则返回 null
+ * @component Modal
+ * @description 
+ * 系统级对话框容器。
+ * 集成了毛玻璃背景效果 (backdrop-blur-sm) 与 200ms 的入场/退场动画，提供极佳的沉浸式体验。
  */
 export const Modal: React.FC<ModalProps> = ({ isOpen, onClose, title, children, footer, maxWidth = 'max-w-md' }) => {
+    // 渲染守卫
     if (!isOpen) return null;
+
     return (
+        /**
+         * 遮罩层布局：
+         * - bg-gray-900/60: 半透明遮蔽，聚焦视觉中心；
+         * - overflow-y-auto: 允许在内容溢出时进行全屏滚动。
+         */
         <div className="fixed inset-0 z-50 flex items-start justify-center bg-gray-900/60 backdrop-blur-sm p-2 sm:p-4 transition-opacity duration-300 overflow-y-auto">
+            
+            {/* 模态框主体：应用 zoom-in 动画效果 */}
             <div className={`bg-white rounded-xl shadow-2xl w-full ${maxWidth} animate-in fade-in zoom-in-95 duration-200 flex flex-col my-auto shrink-0`}>
-                {/* Header */}
+                
+                {/* 头部标题区域 */}
                 <div className="px-4 sm:px-8 py-4 sm:py-5 border-b border-gray-100 flex justify-between items-center shrink-0 bg-white gap-2 min-h-[64px] rounded-t-xl">
                     <h3 className="text-base sm:text-lg font-bold text-gray-800 tracking-tight truncate flex-1 min-w-0 flex items-center">{title}</h3>
                     <button
@@ -492,11 +495,13 @@ export const Modal: React.FC<ModalProps> = ({ isOpen, onClose, title, children,
                         <X size={14} />
                     </button>
                 </div>
-                {/* Content */}
+
+                {/* 主内容插槽区 */}
                 <div className="p-4 sm:p-8 bg-white flex-1 min-h-0 overflow-hidden">
                     {children}
                 </div>
-                {/* Footer */}
+
+                {/* 底部操作区：通过 flex-wrap 适配小屏设备下的按钮堆叠 */}
                 {footer && (
                     <div className="px-4 sm:px-8 py-4 sm:py-5 bg-gray-50 border-t border-gray-100 flex flex-wrap justify-end gap-2 sm:gap-3 shrink-0 rounded-b-xl">
                         {footer}
@@ -507,21 +512,43 @@ export const Modal: React.FC<ModalProps> = ({ isOpen, onClose, title, children,
     );
 };
 
-// --- Toast/Message Component System ---
+// =========================================================
+// 9. Toast/Message System - 异步消息通知中心
+// =========================================================
 
+/**
+ * 消息通知类型定义
+ */
 export type ToastType = 'success' | 'error' | 'info' | 'warning';
 
+/**
+ * 消息通知单条记录的数据结构
+ */
 export interface ToastData {
+    /** 唯一的 UUID，用于精准移除 DOM 节点 */
     id: string;
     type: ToastType;
     content: string;
+    /** 自动销毁时长，单位毫秒 */
     duration?: number;
 }
 
-// 简单的 Event Bus，用于在 React 组件树之外（如 API Client）触发 UI 更新
+/**
+ * 消息分发总线 (Observer Pattern)
+ * @class MessageBus
+ * @description
+ * 解决 React 组件树外的脚本（如 Axios 拦截器）无法直接调用 UI 的问题。
+ * 通过订阅模式实现非侵入式全局通知。
+ */
 class MessageBus {
+    // 观察者回调列表
     private listeners: ((toast: ToastData) => void)[] = [];
 
+    /**
+     * 注册订阅者
+     * @param {Function} listener - 接收新消息的回调
+     * @returns {Function} 清理函数，用于注销订阅
+     */
     subscribe(listener: (toast: ToastData) => void) {
         this.listeners.push(listener);
         return () => {
@@ -529,22 +556,30 @@ class MessageBus {
         };
     }
 
+    /**
+     * 广播新消息
+     * @param {ToastType} type - 消息权重类型
+     * @param {string} content - 通知文本
+     * @param {number} [duration=3000] - 持续展示时间
+     */
     emit(type: ToastType, content: string, duration = 3000) {
         const toast: ToastData = {
-            id: Math.random().toString(36).substr(2, 9),
+            id: Math.random().toString(36).substr(2, 9), // 快速生成唯一随机 ID
             type,
             content,
             duration
         };
+        // 顺序触发所有已注册的活跃订阅者
         this.listeners.forEach(l => l(toast));
     }
 }
 
+/** 单例消息总线实例 */
 const messageBus = new MessageBus();
 
 /**
- * 全局消息工具对象
- * 可在任何地方调用，例如: message.success("操作成功")
+ * 全局消息交互工具对象 (Public API)
+ * 允许在业务代码中执行链式调用：message.success("Success!")
  */
 export const message = {
     success: (content: string, duration?: number) => messageBus.emit('success', content, duration),
@@ -554,14 +589,20 @@ export const message = {
 };
 
 /**
- * 全局消息容器组件
- * 需挂载在 App 根节点
- * 支持响应式布局，在画面中心显示
+ * 全局消息容器挂载点
+ * @component ToastContainer
+ * @description 
+ * 必须挂载在应用 Root 节点。它通过监听全局 messageBus 来动态管理 toasts 数组的生命周期。
  */
 export const ToastContainer: React.FC = () => {
+    // 管理内存中的活跃消息队列
     const [toasts, setToasts] = useState<ToastData[]>([]);
 
     useEffect(() => {
+        /**
+         * 核心订阅逻辑：
+         * 当接收到广播时，将消息压入队列，并设定定时炸弹 (setTimeout) 自动离场。
+         */
         return messageBus.subscribe((toast) => {
             setToasts(prev => [...prev, toast]);
             if (toast.duration && toast.duration > 0) {
@@ -572,33 +613,44 @@ export const ToastContainer: React.FC = () => {
         });
     }, []);
 
+    /**
+     * 执行消息移除
+     * @param {string} id - 待销毁的消息 ID
+     */
     const removeToast = (id: string) => {
         setToasts(prev => prev.filter(t => t.id !== id));
     };
 
     return (
+        /**
+         * 容器布局：
+         * fixed inset-0 + flex items-center: 确保消息垂直居中悬浮在全屏幕最顶层。
+         */
         <div className="fixed inset-0 z-[100] pointer-events-none flex items-center justify-center">
             <div className="flex flex-col gap-3 max-w-md w-full mx-4">
                 {toasts.map(toast => (
                     <div
                         key={toast.id}
+                        /** pointer-events-auto: 允许用户点击关闭按钮 */
                         className={`pointer-events-auto w-full p-4 rounded-lg shadow-xl border transform transition-all duration-300 animate-in zoom-in-95 fade-in bg-white flex items-center gap-3 min-h-[56px]
                 ${toast.type === 'success' ? 'border-green-200 bg-green-50/90 backdrop-blur-sm' :
                                 toast.type === 'error' ? 'border-red-200 bg-red-50/90 backdrop-blur-sm' :
                                     toast.type === 'warning' ? 'border-orange-200 bg-orange-50/90 backdrop-blur-sm' : 'border-blue-200 bg-blue-50/90 backdrop-blur-sm'}`}
                     >
-                        {/* Icon */}
+                        {/* 状态图标：通过 type 属性分发 Lucide 语义图标 */}
                         <div className="shrink-0 flex items-center justify-center">
                             {toast.type === 'success' && <CheckCircle size={20} className="text-green-600" />}
                             {toast.type === 'error' && <AlertCircle size={20} className="text-red-600" />}
                             {toast.type === 'warning' && <AlertTriangle size={20} className="text-orange-600" />}
                             {toast.type === 'info' && <Info size={20} className="text-blue-600" />}
                         </div>
-                        {/* Content */}
+                        
+                        {/* 核心消息载荷区域：支持长文本自动折行 (break-words) */}
                         <div className="flex-1 text-sm text-gray-800 font-medium break-words leading-relaxed min-w-0 flex items-center">
                             {toast.content}
                         </div>
-                        {/* Close */}
+                        
+                        {/* 手动关闭触发器 */}
                         <button
                             onClick={() => removeToast(toast.id)}
                             className="text-gray-400 hover:text-gray-600 transition-colors shrink-0 rounded-full hover:bg-gray-100 w-6 h-6 flex items-center justify-center ml-2"
@@ -612,5 +664,6 @@ export const ToastContainer: React.FC = () => {
         </div>
     );
 };
-// 导出 ConfirmDialog 组件
+
+/** 统一导出业务关联组件 */
 export { ConfirmDialog } from './ConfirmDialog';
\ No newline at end of file
diff --git a/src/frontend/src/hooks/useViewportWidth.ts b/src/frontend/src/hooks/useViewportWidth.ts
index 7911d57..2df4c81 100644
--- a/src/frontend/src/hooks/useViewportWidth.ts
+++ b/src/frontend/src/hooks/useViewportWidth.ts
@@ -1,53 +1,87 @@
+/**
+ * @file useViewportWidth.ts
+ * @module Hooks/Responsive-Layout
+ * @description 响应式视口感知与断点分发钩子。
+ * 本模块是系统“多分辨率适配”策略的核心实现工具，旨在提供实时、高性能的视口维度监控。
+ * * 核心设计目标：
+ * 1. 响应式布局：基于行业标准的断点协议（xs/sm/md/lg/xl）自动识别当前显示环境；
+ * 2. 性能优化：通过内置的“事件防抖 (Debounce)”机制，有效抑制浏览器 resize 期间的重绘压力；
+ * 3. 跨设备兼容：同步监听 orientationchange 事件，确保移动端横竖屏切换时的布局准确性。
+ * * 对应需求：
+ * - Requirement 1.1: 界面多分辨率自适应能力。
+ * * @author Wang Lirong (王利蓉)
+ * @version 2.2.0
+ * @date 2026-01-02
+ */
+
 import { useState, useEffect } from 'react';
 
 /**
- * 视口宽度监听 Hook
- * 
- * 监听视口宽度变化并返回当前宽度和对应的响应式断点标识
- * 用于实现响应式布局和断点适配
- * 
- * Requirements: 1.1
+ * 响应式断点标识符类型定义
+ * @typedef {('xs' | 'sm' | 'md' | 'lg' | 'xl')} BreakpointId
+ * @description 遵循现代 CSS 框架（如 Bootstrap/Tailwind）的栅格化语义。
  */
-
 export type BreakpointId = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 
+/**
+ * 视口状态详情信息接口
+ * @interface ViewportWidthInfo
+ * @description 封装了当前浏览器的物理维度及派生的逻辑断点状态。
+ */
 export interface ViewportWidthInfo {
-  /** 当前视口宽度（像素） */
+  /** 当前视口的实时物理宽度（单位：像素 px） */
   width: number;
-  /** 当前视口高度（像素） */
+  /** 当前视口的实时物理高度（单位：像素 px） */
   height: number;
-  /** 当前断点标识 */
+  /** 当前所属的响应式断点标识，用于组件侧的条件分支逻辑 */
   breakpoint: BreakpointId;
-  /** 断点检查函数 */
+  /** * 语义化断点检查快捷对象 
+   * 提供一组布尔值，用于模板中快速判断设备类型。
+   */
   is: {
-    xs: boolean;    // < 480px
-    sm: boolean;    // 480px - 768px
-    md: boolean;    // 768px - 1024px
-    lg: boolean;    // 1024px - 1440px
-    xl: boolean;    // > 1440px
-    mobile: boolean;    // < 768px
-    tablet: boolean;    // 768px - 1024px
-    desktop: boolean;   // > 1024px
+    /** 极小屏幕：通常指小屏手机 (width < 480px) */
+    xs: boolean;    
+    /** 小屏幕：大屏手机或竖屏平板 (480px - 768px) */
+    sm: boolean;    
+    /** 中等屏幕：横屏平板 (768px - 1024px) */
+    md: boolean;    
+    /** 大屏幕：笔记本或小尺寸显示器 (1024px - 1440px) */
+    lg: boolean;    
+    /** 超大屏幕：2K/4K 专业显示器 (width > 1440px) */
+    xl: boolean;    
+    /** 业务定义：移动端视图（合并 xs 与 sm） */
+    mobile: boolean;    
+    /** 业务定义：平板端视图（对应 md 档） */
+    tablet: boolean;    
+    /** 业务定义：桌面端视图（对应 lg 及以上） */
+    desktop: boolean;   
   };
 }
 
 /**
- * 响应式断点定义
- * 基于设计文档中的断点策略
+ * 响应式断点物理阈值定义
+ * @constant BREAKPOINTS
+ * @description 严格对接设计稿的 UI 规范，作为视口识别的基准线。
  */
 export const BREAKPOINTS = {
-  xs: 0,      // 0px - 479px
-  sm: 480,    // 480px - 767px
-  md: 768,    // 768px - 1023px
-  lg: 1024,   // 1024px - 1439px
-  xl: 1440,   // 1440px+
+  /** 超小屏幕起始像素 */
+  xs: 0,      
+  /** 小屏幕阈值 (480px) */
+  sm: 480,    
+  /** 中等屏幕阈值 (768px) */
+  md: 768,    
+  /** 大屏幕阈值 (1024px) */
+  lg: 1024,   
+  /** 超大屏幕阈值 (1440px) */
+  xl: 1440,   
 } as const;
 
 /**
- * 根据宽度确定断点标识
- * 
- * @param width 视口宽度
- * @returns 断点标识
+ * 内部辅助算法：根据物理宽度映射至断点标识符
+ * 执行标准的区间判定逻辑，返回当前视口所在的离散化档位。
+ * @function getBreakpointId
+ * @param {number} width - 待校验的视口宽度
+ * @returns {BreakpointId} 匹配的断点 ID
  */
 function getBreakpointId(width: number): BreakpointId {
   if (width < BREAKPOINTS.sm) return 'xs';
@@ -58,34 +92,41 @@ function getBreakpointId(width: number): BreakpointId {
 }
 
 /**
- * 创建断点检查对象
- * 
- * @param width 视口宽度
- * @param breakpoint 当前断点
- * @returns 断点检查对象
+ * 内部辅助工厂：创建具备语义化布尔属性的断点检查对象
+ * 旨在降低业务组件在处理响应式逻辑时的代码复杂度。
+ * @function createBreakpointChecks
+ * @param {number} width - 物理宽度
+ * @param {BreakpointId} breakpoint - 档位 ID
  */
 function createBreakpointChecks(width: number, breakpoint: BreakpointId) {
   return {
+    // 精确档位判定
     xs: breakpoint === 'xs',
     sm: breakpoint === 'sm',
     md: breakpoint === 'md',
     lg: breakpoint === 'lg',
     xl: breakpoint === 'xl',
-    mobile: width < BREAKPOINTS.md,      // < 768px
-    tablet: width >= BREAKPOINTS.md && width < BREAKPOINTS.lg,  // 768px - 1023px
-    desktop: width >= BREAKPOINTS.lg,    // >= 1024px
+    // 聚合业务档位判定
+    mobile: width < BREAKPOINTS.md,      // 判定依据：宽度小于 768px 被视为广义移动端
+    tablet: width >= BREAKPOINTS.md && width < BREAKPOINTS.lg,  // 判定依据：768px 至 1023px
+    desktop: width >= BREAKPOINTS.lg,    // 判定依据：1024px 以上进入桌面级交互模式
   };
 }
 
 /**
- * 计算当前视口信息
- * 
- * @returns ViewportWidthInfo 视口宽度信息
+ * 内部状态机：计算并刷新当前完整的视口上下文信息
+ * 封装了对浏览器全局 window 对象的直接访问逻辑。
+ * @function calculateViewportInfo
+ * @returns {ViewportWidthInfo}
  */
 function calculateViewportInfo(): ViewportWidthInfo {
+  // 获取浏览器视口的实时几何尺寸
   const width = window.innerWidth;
   const height = window.innerHeight;
+  
+  // 识别当前宽度所属的档位
   const breakpoint = getBreakpointId(width);
+  // 生成语义化布尔对象
   const is = createBreakpointChecks(width, breakpoint);
 
   return {
@@ -97,27 +138,36 @@ function calculateViewportInfo(): ViewportWidthInfo {
 }
 
 /**
- * 视口宽度监听 Hook
- * 
- * 监听视口宽度变化，返回当前视口宽度和断点标识
- * 支持防抖以提高性能
- * 
- * @param debounceMs 防抖延迟时间（毫秒），默认为 100ms
- * @returns ViewportWidthInfo 视口宽度信息
+ * 视口宽度监听自定义 Hook
+ * @export @function useViewportWidth
+ * @description 
+ * 为组件提供对窗口缩放事件的感知能力。
+ * 内置“防抖 (Debounce)”策略，有效防止在连续拖拽窗口大小时触发高频的 React 状态更新，
+ * 从而显著降低页面的脚本执行负担和重排 (Reflow) 频率。
+ * * @param {number} [debounceMs=100] - 防抖触发延迟（毫秒）。较高的值可提升性能，较低的值可增强响应实时性。
+ * @returns {ViewportWidthInfo} 实时更新的视口元数据
  */
 export function useViewportWidth(debounceMs: number = 100): ViewportWidthInfo {
+  /**
+   * 步骤 1：状态初始化。
+   * 使用惰性初始化模式执行初次视口信息采集，确保服务端渲染 (SSR) 期间的安全。
+   */
   const [viewportInfo, setViewportInfo] = useState<ViewportWidthInfo>(() => calculateViewportInfo());
 
   useEffect(() => {
+    // 引用定时器 ID，用于防抖逻辑的清理
     let timeoutId: NodeJS.Timeout | null = null;
 
+    /** 窗口缩放事件的回调封装 */
     const updateViewportInfo = () => {
-      // 清除之前的防抖定时器
+      // 步骤 2：防抖逻辑介入。
+      // 若在 debounceMs 毫秒内再次触发 resize，则撤销之前的更新任务。
       if (timeoutId) {
         clearTimeout(timeoutId);
       }
 
-      // 设置新的防抖定时器
+      // 步骤 3：设定延时更新任务。
+      // 仅在浏览器停止缩放动作后指定的毫秒数，才正式计算视口信息。
       timeoutId = setTimeout(() => {
         const newViewportInfo = calculateViewportInfo();
         setViewportInfo(newViewportInfo);
@@ -125,34 +175,35 @@ export function useViewportWidth(debounceMs: number = 100): ViewportWidthInfo {
       }, debounceMs);
     };
 
-    // 监听窗口大小变化
+    /**
+     * 步骤 4：注册系统级监听器。
+     * 除了标准的 resize，还监听 orientationchange 以适配平板/手机的物理旋转操作。
+     */
     window.addEventListener('resize', updateViewportInfo);
-
-    // 监听方向变化（移动设备）
     window.addEventListener('orientationchange', updateViewportInfo);
 
+    // 步骤 5：Effect 清理阶段。
+    // 销毁监听器并清除未执行的定时器，防止内存泄漏。
     return () => {
       window.removeEventListener('resize', updateViewportInfo);
       window.removeEventListener('orientationchange', updateViewportInfo);
 
-      // 清理防抖定时器
       if (timeoutId) {
         clearTimeout(timeoutId);
       }
     };
-  }, [debounceMs]);
+  }, [debounceMs]); // 依赖项：仅当用户改变防抖策略时重新绑定
 
   return viewportInfo;
 }
 
 /**
- * 简化版视口宽度 Hook
- * 
- * 只返回当前视口宽度，不包含断点信息
- * 适用于只需要宽度数值的场景
- * 
- * @param debounceMs 防抖延迟时间（毫秒），默认为 100ms
- * @returns 当前视口宽度
+ * 精简版视口宽度监听 Hook
+ * @export @function useViewportWidthOnly
+ * @description 
+ * 适用于仅关注宽度数值、无需断点判断的轻量级场景（如：Canvas 动态绘图大小计算）。
+ * @param {number} [debounceMs=100]
+ * @returns {number} 当前视口物理宽度像素值
  */
 export function useViewportWidthOnly(debounceMs: number = 100): number {
   const { width } = useViewportWidth(debounceMs);
@@ -160,24 +211,27 @@ export function useViewportWidthOnly(debounceMs: number = 100): number {
 }
 
 /**
- * 断点匹配 Hook
- * 
- * 检查当前视口是否匹配指定的断点条件
- * 
- * @param breakpoint 要检查的断点或断点数组
- * @param debounceMs 防抖延迟时间（毫秒），默认为 100ms
- * @returns 是否匹配指定断点
+ * 断点逻辑匹配 Hook (Conditional Matching)
+ * @export @function useBreakpointMatch
+ * @description 
+ * 支持“多对一”匹配。常用于根据断点动态渲染不同的子组件或逻辑块。
+ * @param {(BreakpointId | BreakpointId[] | 'mobile' | 'tablet' | 'desktop')} breakpoint - 待检查的一个或一组断点
+ * @param {number} [debounceMs=100]
+ * @returns {boolean} 当前视口是否命中了指定的断点条件
  */
 export function useBreakpointMatch(
   breakpoint: BreakpointId | BreakpointId[] | 'mobile' | 'tablet' | 'desktop',
   debounceMs: number = 100
 ): boolean {
+  // 从核心 Hook 中提取语义判定对象
   const { is } = useViewportWidth(debounceMs);
 
+  // 分支逻辑：处理断点数组（如：['xs', 'sm'] 代表“是否为移动端”）
   if (Array.isArray(breakpoint)) {
     return breakpoint.some(bp => is[bp]);
   }
 
+  // 默认逻辑：单一档位匹配
   return is[breakpoint as keyof typeof is];
 }
 
diff --git a/src/frontend/src/pages/Admin.tsx b/src/frontend/src/pages/Admin.tsx
index a1df035..e061687 100644
--- a/src/frontend/src/pages/Admin.tsx
+++ b/src/frontend/src/pages/Admin.tsx
@@ -1,96 +1,173 @@
+/**
+ * @file AdminPanel.tsx
+ * @module Pages/Administration/User-Management
+ * @description 系统管理后台 - 全量用户治理与资源配额中心。
+ * 本模块作为 AutoDB 平台的运维核心，负责处理用户生命周期管理及物理资源配额的分发。
+ * * * 核心管理逻辑：
+ * 1. 资源隔离与配额 (SF11): 动态调整各用户可创建的数据库实例上限，防止单用户过度占用物理集群资源；
+ * 2. 账号合规控制 (Security-4): 实现封禁/解封流，集成违规原因审计追踪，确保管理操作可追溯；
+ * 3. 智能检索引擎: 支持基于内存过滤与服务端分页的混合检索策略；
+ * 4. 数据协议适配: 通过 mapToUser 适配器模式，实现管理端 DTO 与通用用户模型的解耦。
+ * * * 对应需求点：
+ * - Requirement 11.1: 管理员可动态调整用户数据库创建限额。
+ * - Requirement 11.2: 支持用户状态的强制干预（正常/异常/封禁）。
+ * * @author Wang Lirong (王利蓉)
+ * @version 2.2.0
+ * @date 2026-01-02
+ */
+
 import React, { useState, useEffect } from 'react';
 import { User, UserRole, UserStatus, AdminUserListItem } from '../types.ts';
 import { Card, Button, Tag, Modal, Input, message, Select } from '../components/UI.tsx';
 import { Search, Ban, CheckCircle, Users, Eye, Database, Edit3, Loader2, Filter, AlertTriangle } from 'lucide-react';
 import { adminApi } from '../api/admin.ts';
 
+/**
+ * 管理面板组件属性定义
+ * @interface AdminPanelProps
+ * @property {Function} onViewUser - 当管理员需要调取特定用户全维画像时的路由/弹窗回调。
+ */
 interface AdminPanelProps {
     onViewUser: (user: User) => void;
 }
 
 /**
- * 系统管理后台 - 用户管理面板
- * * 对接真实 API (GET /users, PATCH /status, PATCH /quota)
+ * @component AdminPanel
+ * @description
+ * 采用 React 函数式组件构建。该页面集成了全量用户的状态监控视图。
+ * 内部状态机驱动复杂的业务弹窗流，确保在进行高危操作（如账号封禁）时具备强制性的二次确认逻辑。
  */
 export const AdminPanel: React.FC<AdminPanelProps> = ({ onViewUser }) => {
-    // --- 状态管理 ---
+    // --- 核心数据集状态 (Data States) ---
+    /** 存储当前分页下的用户列表快照 */
     const [users, setUsers] = useState<AdminUserListItem[]>([]);
+    /** 页面级全局加载锁 */
     const [isLoading, setIsLoading] = useState(false);
 
-    // 过滤与分页
+    // --- 过滤、搜索与分页控制 (Context States) ---
+    /** 检索关键字缓冲区 */
     const [searchTerm, setSearchTerm] = useState('');
+    /** 状态漏斗：支持全量、正常、挂起、封禁四维度过滤 */
     const [statusFilter, setStatusFilter] = useState<'all' | 'normal' | 'suspended' | 'banned'>('all');
+    /** 分页器：当前激活页码 */
     const [page, setPage] = useState(1);
+    /** 后端符合过滤条件的总条目数，用于驱动分页 UI 计算 */
     const [total, setTotal] = useState(0);
+    /** 业务规范：固定单页容量为 10 条 */
     const pageSize = 10;
 
-    // 配额编辑状态
+    // --- 资源配额治理状态 (Quota Management) ---
+    /** 当前正在进行配额编辑的目标用户引用 */
     const [editingQuotaUser, setEditingQuotaUser] = useState<AdminUserListItem | null>(null);
+    /** 配额输入框实时值 */
     const [newQuota, setNewQuota] = useState('');
+    /** 针对配额输入的即时校验错误信息 */
     const [quotaError, setQuotaError] = useState('');
+    /** 提交配额变更时的异步状态锁 */
     const [isSavingQuota, setIsSavingQuota] = useState(false);
 
-    // 状态修改 (封禁/解封) 弹窗状态
+    // --- 账号安全干预状态 (Status & Risk Control) ---
+    /** 封禁/解封事务弹窗的显隐状态 */
     const [isStatusModalOpen, setIsStatusModalOpen] = useState(false);
+    /** 状态变更事务的目标用户快照 */
     const [statusTargetUser, setStatusTargetUser] = useState<AdminUserListItem | null>(null);
-    const [targetStatusAction, setTargetStatusAction] = useState<'normal' | 'banned'>('normal'); // 目标状态
+    /** 目标操作倾向：normal 代表恢复正常/解封，banned 代表强制封禁 */
+    const [targetStatusAction, setTargetStatusAction] = useState<'normal' | 'banned'>('normal'); 
+    /** 审计理由字段：记录操作原因以备日后安全审计 */
     const [statusReason, setStatusReason] = useState('');
+    /** 状态变更请求的异步处理锁 */
     const [isSavingStatus, setIsSavingStatus] = useState(false);
 
-    // --- 数据获取 ---
+    /**
+     * 服务端数据拉取核心逻辑
+     * @async @function fetchUsers
+     * @description
+     * 对应 SF11 基础数据获取。执行以下流程：
+     * 1. 开启全局加载状态；
+     * 2. 调用 adminApi.getUsers 执行服务端分页检索；
+     * 3. 对返回结果执行 ID 级升序排列（确保列表稳定性）；
+     * 4. 更新本地状态并刷新总数计数。
+     */
     const fetchUsers = async () => {
         setIsLoading(true);
         try {
+            // 发起异步请求，透传分页与搜索权重参数
             const res = await adminApi.getUsers(page, pageSize, searchTerm || undefined, statusFilter);
 
-            // 需求：用户列表按 id 升序排列
+            /**
+             * 排序算法：保证 UI 层的展示一致性。
+             * 虽然后端通常已处理排序，但在前端执行显式校验可提升防御性编程水平。
+             */
             const sortedItems = res.items.sort((a, b) => a.user_id - b.user_id);
 
             setUsers(sortedItems);
             setTotal(res.total);
         } catch (error) {
+            // 异常路径：记录日志并可通过全局错误拦截器抛出 UI 提示
             console.error("Fetch users failed", error);
         } finally {
+            // 释放加载锁，恢复 UI 交互
             setIsLoading(false);
         }
     };
 
-    // 监听筛选条件变化
+    /**
+     * 效应钩子：依赖追踪与自动同步。
+     * 当分页码或状态过滤器发生偏移时，自动触发重测。
+     */
     useEffect(() => {
         fetchUsers();
     }, [page, statusFilter]);
 
+    /**
+     * 搜索交互处理
+     * @param {React.KeyboardEvent} e - 键盘事件对象
+     */
     const handleSearchKeyDown = (e: React.KeyboardEvent) => {
+        // 监听 Enter 键，执行非实时搜索以降低 API 峰值负载
         if (e.key === 'Enter') {
-            setPage(1);
+            setPage(1); // 搜索条件变化时，强制重置至第一页
             fetchUsers();
         }
     };
 
-    // --- 业务逻辑处理 ---
+    // --- 业务事务处理集 (Business Transaction Handlers) ---
 
     /**
-     * 打开状态修改弹窗
+     * 开启账户状态变更事务
+     * @param {AdminUserListItem} user - 目标用户
+     * @param {'normal' | 'banned'} action - 预执行的动作方向
      */
     const handleOpenStatusModal = (user: AdminUserListItem, action: 'normal' | 'banned') => {
         setStatusTargetUser(user);
         setTargetStatusAction(action);
-        setStatusReason(''); // 重置原因输入
+        setStatusReason(''); // 事务初始化：强制清空审计原因缓冲区
         setIsStatusModalOpen(true);
     };
 
     /**
-     * 确认提交状态修改 (封禁/解封/恢复正常)
+     * 核心事务：提交账户状态修改
+     * @async @function handleConfirmStatusChange
+     * @description 
+     * 该函数实现了账号治理的完整闭环。包含：
+     * 1. 输入完整性校验（审计原因必填）；
+     * 2. 异步 API 调用；
+     * 3. 乐观 UI 更新（Optimistic Update），在请求成功后立即同步本地列表状态；
+     * 4. 事务资源清理。
      */
     const handleConfirmStatusChange = async () => {
         if (!statusTargetUser) return;
 
+        // 根据动作方向计算语义化描述
         const targetStatus = targetStatusAction;
         const actionText = targetStatus === 'normal' ?
             (statusTargetUser.status === 'banned' ? '解封' : '恢复正常') :
             '封禁';
 
-        // 简单的必填校验
+        /**
+         * 审计合规校验：
+         * 任何对账户状态的干预操作必须提供原因说明。
+         */
         if (!statusReason.trim()) {
             message.error(`请输入${actionText}原因`);
             return;
@@ -98,45 +175,58 @@ export const AdminPanel: React.FC<AdminPanelProps> = ({ onViewUser }) => {
 
         setIsSavingStatus(true);
         try {
+            // 调用管理端专用更新接口
             await adminApi.updateUserStatus(statusTargetUser.user_id, {
                 status: targetStatus,
                 reason: statusReason
             });
+            
+            // 业务层反馈
             message.success(`用户已${actionText}`);
 
-            // 乐观更新 UI
+            /**
+             * 乐观 UI 同步：
+             * 无需重新拉取整个列表，仅对修改项执行局部深拷贝更新。
+             */
             setUsers(prev => prev.map(u => u.user_id === statusTargetUser.user_id ? { ...u, status: targetStatus } : u));
 
-            // 关闭弹窗
+            // 事务完成：销毁所有临时上下文
             setIsStatusModalOpen(false);
             setStatusTargetUser(null);
         } catch (error) {
-            console.error(error);
+            console.error("Status update failed", error);
         } finally {
             setIsSavingStatus(false);
         }
     };
 
     /**
-     * 打开配额编辑
+     * 开启配额编辑事务
+     * @param {AdminUserListItem} user - 目标用户
      */
     const handleOpenQuotaModal = (user: AdminUserListItem) => {
         setEditingQuotaUser(user);
         setNewQuota(user.max_databases.toString());
-        setQuotaError('');
+        setQuotaError(''); // 重置错误信号
     };
 
     /**
-     * 保存配额
+     * 核心事务：保存配额变更
+     * @async @function handleSaveQuota
+     * @description
+     * 实现了对物理资源上限的强力管控。
+     * 包含输入合法性判定（非负整数）及系统级峰值限流校验（Max: 1000）。
      */
     const handleSaveQuota = async () => {
         if (!editingQuotaUser) return;
         const quota = parseInt(newQuota);
 
+        // 数据合法性预检
         if (isNaN(quota) || quota < 0) {
             setQuotaError('额度不能为负数');
             return;
         }
+        // 系统级策略保护：单用户最大数据库数不得超过 1000
         if (quota > 1000) {
             setQuotaError('额度值超出系统上限 (1000)');
             return;
@@ -144,41 +234,57 @@ export const AdminPanel: React.FC<AdminPanelProps> = ({ onViewUser }) => {
 
         setIsSavingQuota(true);
         try {
+            // 执行配额写入操作
             await adminApi.updateUserQuota(editingQuotaUser.user_id, quota);
             message.success('额度更新成功');
+            
+            // 同步本地状态，刷新“项目数/额度”列的展示
             setUsers(prev => prev.map(u => u.user_id === editingQuotaUser.user_id ? { ...u, max_databases: quota } : u));
-            setEditingQuotaUser(null);
+            setEditingQuotaUser(null); // 事务关闭
         } catch (error) {
-            console.error(error);
+            console.error("Quota update failed", error);
         } finally {
             setIsSavingQuota(false);
         }
     };
 
-    // 辅助：将 AdminUserListItem 转换为 User 对象以适配 UserProfile 组件
+    /**
+     * 数据模型转换器 (Adapter Pattern)
+     * @function mapToUser
+     * @description
+     * 将管理端特有的 AdminUserListItem 转换为应用通用的 User 对象定义。
+     * 解决了管理侧接口字段（user_id）与用户侧标准字段（id）的不一致性问题。
+     * @param {AdminUserListItem} item - 原始后端 DTO
+     * @returns {User} 标准化 User 对象
+     */
     const mapToUser = (item: AdminUserListItem): User => ({
         id: item.user_id.toString(),
         username: item.username,
         email: item.email,
-        role: UserRole.USER, // 列表默认视为普通用户，详情页可细化
+        role: UserRole.USER, // 管理员视角下默认作为普通用户处理
         status: item.status === 'normal' ? UserStatus.NORMAL : UserStatus.BANNED,
+        // 时间戳本地化处理：针对从未登录的用户进行语义化兜底
         lastLogin: item.last_login_at ? new Date(item.last_login_at).toLocaleString() : '从未登录',
         projectQuota: item.max_databases
     });
 
+    /**
+     * 渲染视图层
+     */
     return (
         <div className="p-8 max-w-7xl mx-auto h-full overflow-y-auto">
-            {/* 顶部标题与操作栏 */}
+            
+            {/* 步骤 1：顶部状态区 - 包含标题及响应式检索组件 */}
             <div className="flex flex-col md:flex-row justify-between items-start md:items-center mb-8 gap-4">
                 <h2 className="text-2xl font-bold text-gray-800 flex items-center gap-3">
                     <div className="p-2 bg-blue-100 text-blue-600 rounded-lg shrink-0">
                         <Users size={20} />
                     </div>
-                    用户管理
+                    用户治理中心
                 </h2>
 
                 <div className="flex gap-2 w-full md:w-auto">
-                    {/* 状态筛选 */}
+                    {/* 过滤器组：状态筛选下行菜单 */}
                     <div className="flex items-center gap-2 bg-white px-3 rounded-lg border border-gray-300 shadow-sm h-[38px] hover:border-gray-400 transition-colors">
                         <Filter size={16} className="text-gray-400" />
                         <Select
@@ -195,7 +301,7 @@ export const AdminPanel: React.FC<AdminPanelProps> = ({ onViewUser }) => {
                         />
                     </div>
 
-                    {/* 搜索框 */}
+                    {/* 搜索控制：全局关键字搜索 */}
                     <div className="relative flex-1 md:w-64">
                         <input
                             type="text"
@@ -210,63 +316,72 @@ export const AdminPanel: React.FC<AdminPanelProps> = ({ onViewUser }) => {
                 </div>
             </div>
 
-            {/* 用户列表表格 */}
+            {/* 步骤 2：数据展示区 - 响应式表格设计 */}
             <Card className="overflow-hidden p-0 min-h-[400px]">
                 {isLoading ? (
+                    /** 加载态：采用 Loader 动画替代空列表 */
                     <div className="flex justify-center items-center h-64">
                         <Loader2 className="animate-spin text-primary" size={32} />
                     </div>
                 ) : (
                     <div className="overflow-x-auto">
                         <table className="w-full text-left text-sm min-w-[1000px]">
+                            {/* 表头定义：声明各列业务语义 */}
                             <thead className="bg-gray-50 border-b border-gray-200">
                                 <tr>
                                     <th className="px-6 py-4 font-medium text-gray-600 whitespace-nowrap">ID</th>
                                     <th className="px-6 py-4 font-medium text-gray-600 whitespace-nowrap">用户名</th>
                                     <th className="px-6 py-4 font-medium text-gray-600 whitespace-nowrap">邮箱</th>
-                                    <th className="px-6 py-4 font-medium text-gray-600 whitespace-nowrap">状态</th>
+                                    <th className="px-6 py-4 font-medium text-gray-600 whitespace-nowrap">实时状态</th>
                                     <th className="px-6 py-4 font-medium text-gray-600 whitespace-nowrap">项目数/额度</th>
-                                    <th className="px-6 py-4 font-medium text-gray-600 whitespace-nowrap">最后登录</th>
-                                    <th className="px-6 py-4 font-medium text-gray-600 text-right whitespace-nowrap">操作</th>
+                                    <th className="px-6 py-4 font-medium text-gray-600 whitespace-nowrap">最近访问</th>
+                                    <th className="px-6 py-4 font-medium text-gray-600 text-right whitespace-nowrap">治理操作</th>
                                 </tr>
                             </thead>
                             <tbody className="divide-y divide-gray-100">
                                 {users.map(user => (
-                                    <tr key={user.user_id} className="hover:bg-gray-50/50">
+                                    <tr key={user.user_id} className="hover:bg-gray-50/50 transition-colors">
                                         <td className="px-6 py-4 text-gray-500 font-mono whitespace-nowrap">{user.user_id}</td>
                                         <td className="px-6 py-4 font-medium text-gray-800 whitespace-nowrap">{user.username}</td>
                                         <td className="px-6 py-4 text-gray-600 whitespace-nowrap">{user.email}</td>
                                         <td className="px-6 py-4 whitespace-nowrap">
+                                            {/* 状态标签：通过色彩语义强化风险识别 */}
                                             <Tag color={user.status === 'normal' ? 'green' : user.status === 'banned' ? 'red' : 'orange'}>
-                                                {user.status === 'normal' ? '正常' : user.status === 'banned' ? '封禁' : '异常'}
+                                                {user.status === 'normal' ? '正常' : user.status === 'banned' ? '封禁' : '异常活跃'}
                                             </Tag>
                                         </td>
-                                        {/* 额度列 */}
+                                        
                                         <td className="px-6 py-4 whitespace-nowrap">
+                                            {/* 额度交互区：点击触发向导修改 */}
                                             <div
                                                 className="flex items-center gap-2 group cursor-pointer"
                                                 onClick={() => handleOpenQuotaModal(user)}
-                                                title="点击修改配额"
+                                                title="点击调整资源上限"
                                             >
-                                                <span className="font-mono">{user.project_count} / {user.max_databases}</span>
+                                                <span className="font-mono text-blue-600 bg-blue-50 px-2 py-0.5 rounded">
+                                                    {user.project_count} / {user.max_databases}
+                                                </span>
                                                 <Edit3 size={12} className="text-gray-400 opacity-0 group-hover:opacity-100 transition-opacity" />
                                             </div>
                                         </td>
+
                                         <td className="px-6 py-4 text-gray-500 whitespace-nowrap">
                                             {user.last_login_at ? new Date(user.last_login_at).toLocaleString() : '-'}
                                         </td>
+
                                         <td className="px-6 py-4 text-right whitespace-nowrap">
                                             <div className="flex justify-end items-center gap-2">
+                                                {/* 动作 A：查看全维视图 */}
                                                 <Button
                                                     variant="text"
                                                     className="h-8 px-2 text-gray-500 hover:text-primary"
                                                     onClick={() => onViewUser(mapToUser(user))}
-                                                    title="查看详情"
+                                                    title="查看全量档案"
                                                 >
                                                     <Eye size={16} />
                                                 </Button>
 
-                                                {/* 正常用户：显示封禁按钮 */}
+                                                {/* 策略逻辑：针对不同状态渲染差异化的干预按钮 */}
                                                 {user.status === 'normal' && (
                                                     <Button
                                                         variant="danger"
@@ -274,11 +389,10 @@ export const AdminPanel: React.FC<AdminPanelProps> = ({ onViewUser }) => {
                                                         onClick={() => handleOpenStatusModal(user, 'banned')}
                                                         icon={<Ban size={12} />}
                                                     >
-                                                        封禁
+                                                        强制封禁
                                                     </Button>
                                                 )}
 
-                                                {/* 已封禁用户：显示解封按钮 */}
                                                 {user.status === 'banned' && (
                                                     <Button
                                                         variant="default"
@@ -286,13 +400,12 @@ export const AdminPanel: React.FC<AdminPanelProps> = ({ onViewUser }) => {
                                                         onClick={() => handleOpenStatusModal(user, 'normal')}
                                                         icon={<CheckCircle size={12} />}
                                                     >
-                                                        解封
+                                                        立即解封
                                                     </Button>
                                                 )}
 
-                                                {/* 异常用户：显示恢复和封禁两个按钮 */}
                                                 {user.status === 'suspended' && (
-                                                    <>
+                                                    <div className="flex gap-1">
                                                         <Button
                                                             variant="default"
                                                             className="h-8 px-3 text-xs border-green-200 text-green-600 hover:bg-green-50"
@@ -309,15 +422,21 @@ export const AdminPanel: React.FC<AdminPanelProps> = ({ onViewUser }) => {
                                                         >
                                                             封禁
                                                         </Button>
-                                                    </>
+                                                    </div>
                                                 )}
                                             </div>
                                         </td>
                                     </tr>
                                 ))}
-                                {users.length === 0 && (
+                                {/* 空态兜底 */}
+                                {users.length === 0 && !isLoading && (
                                     <tr>
-                                        <td colSpan={7} className="text-center py-12 text-gray-500">未找到匹配的用户</td>
+                                        <td colSpan={7} className="text-center py-12 text-gray-500">
+                                            <div className="flex flex-col items-center">
+                                                <AlertTriangle size={32} className="text-gray-300 mb-2" />
+                                                未检索到符合条件的租户记录
+                                            </div>
+                                        </td>
                                     </tr>
                                 )}
                             </tbody>
@@ -325,11 +444,11 @@ export const AdminPanel: React.FC<AdminPanelProps> = ({ onViewUser }) => {
                     </div>
                 )}
 
-                {/* 分页器 */}
+                {/* 步骤 3：数据辅助层 - 分页控制 */}
                 {total > 0 && (
                     <div className="flex justify-between items-center px-6 py-4 border-t border-gray-100 bg-gray-50/50">
-                        <span className="text-xs text-gray-500">
-                            共 {total} 条记录，当前第 {page} 页
+                        <span className="text-xs text-gray-500 font-medium">
+                            数据体量：总计 {total} 项，分步浏览中 (Page: {page})
                         </span>
                         <div className="flex gap-2">
                             <Button variant="default" className="h-8 px-3 text-xs" disabled={page <= 1} onClick={() => setPage(p => p - 1)}>上一页</Button>
@@ -339,73 +458,74 @@ export const AdminPanel: React.FC<AdminPanelProps> = ({ onViewUser }) => {
                 )}
             </Card>
 
-            {/* 配额修改模态框 */}
+            {/* 事务模块 A：配额调整对话框 */}
             <Modal
                 isOpen={!!editingQuotaUser}
                 onClose={() => setEditingQuotaUser(null)}
-                title="修改用户数据库额度"
+                title="物理资源限制参数调整"
                 maxWidth="max-w-sm"
                 footer={
-                    <>
+                    <div className="flex justify-end gap-2">
                         <Button onClick={() => setEditingQuotaUser(null)}>取消</Button>
                         <Button variant="primary" onClick={handleSaveQuota} disabled={isSavingQuota}>
-                            {isSavingQuota ? '保存中...' : '保存更改'}
+                            {isSavingQuota ? '正在同步云端...' : '更新配置'}
                         </Button>
-                    </>
+                    </div>
                 }
             >
                 <div className="space-y-4">
-                    <div className="bg-blue-50 p-3 rounded-lg flex items-start gap-3">
+                    <div className="bg-blue-50 p-3 rounded-lg flex items-start gap-3 border border-blue-100">
                         <Database className="text-primary shrink-0 mt-0.5" size={18} />
-                        <div className="text-sm text-blue-900">
-                            <p>正在修改用户 <strong>{editingQuotaUser?.username}</strong> 的最大项目创建数。</p>
+                        <div className="text-xs text-blue-900 leading-relaxed">
+                            <p>正在调整租户 <strong>{editingQuotaUser?.username}</strong> 的资源隔离配额。</p>
+                            <p className="mt-1 opacity-70">变更将实时影响该用户的多智能体部署能力。</p>
                         </div>
                     </div>
 
                     <div>
                         <Input
-                            label="新额度上限"
+                            label="最大项目允许数 (Max Databases)"
                             type="number"
                             value={newQuota}
                             onChange={(e) => setNewQuota(e.target.value)}
-                            placeholder="请输入整数"
+                            placeholder="请输入配额整数"
                             min={0}
                             required
                         />
-                        {quotaError && <p className="text-red-500 text-xs mt-1">{quotaError}</p>}
+                        {quotaError && <p className="text-red-500 text-[11px] mt-1 font-medium">{quotaError}</p>}
                     </div>
                 </div>
             </Modal>
 
-            {/* 状态修改 (封禁/解封) 模态框 */}
+            {/* 事务模块 B：账户干预确认对话框 (Security Critical) */}
             <Modal
                 isOpen={isStatusModalOpen}
                 onClose={() => setIsStatusModalOpen(false)}
                 title={
                     targetStatusAction === 'normal' ?
-                        (statusTargetUser?.status === 'banned' ? '解封用户账号' : '恢复用户为正常状态') :
-                        '封禁用户账号'
+                        (statusTargetUser?.status === 'banned' ? '撤销账户封禁' : '恢复正常服务') :
+                        '执行账户封禁审计'
                 }
                 maxWidth="max-w-md"
                 footer={
-                    <>
-                        <Button onClick={() => setIsStatusModalOpen(false)}>取消</Button>
+                    <div className="flex justify-end gap-2">
+                        <Button onClick={() => setIsStatusModalOpen(false)}>放弃操作</Button>
                         <Button
                             variant={targetStatusAction === 'banned' ? 'danger' : 'primary'}
                             onClick={handleConfirmStatusChange}
                             disabled={isSavingStatus}
                         >
-                            {isSavingStatus ? '处理中...' : (
+                            {isSavingStatus ? '正在下发指令...' : (
                                 targetStatusAction === 'normal' ?
-                                    (statusTargetUser?.status === 'banned' ? '确认解封' : '确认恢复正常') :
-                                    '确认封禁'
+                                    (statusTargetUser?.status === 'banned' ? '确认撤销' : '确认恢复') :
+                                    '立即执行封禁'
                             )}
                         </Button>
-                    </>
+                    </div>
                 }
             >
                 <div className="space-y-4">
-                    {/* 警告提示 */}
+                    {/* 风险告知面板 */}
                     <div className={`p-4 rounded-lg flex items-start gap-3 border ${targetStatusAction === 'banned' ? 'bg-red-50 border-red-100 text-red-800' :
                         statusTargetUser?.status === 'banned' ? 'bg-green-50 border-green-100 text-green-800' :
                             'bg-blue-50 border-blue-100 text-blue-800'
@@ -413,39 +533,36 @@ export const AdminPanel: React.FC<AdminPanelProps> = ({ onViewUser }) => {
                         <AlertTriangle size={18} className="mt-0.5 shrink-0" />
                         <div className="text-sm">
                             <p className="font-bold mb-1">
-                                {targetStatusAction === 'banned' ? '高风险操作' :
-                                    statusTargetUser?.status === 'banned' ? '解封操作' :
-                                        '恢复正常状态'}
-                            </p>
-                            <p>
-                                您正在对用户 <strong>{statusTargetUser?.username}</strong> 执行
-                                {targetStatusAction === 'banned' ? '封禁' :
-                                    statusTargetUser?.status === 'banned' ? '解封' :
-                                        '恢复正常'}操作。
-                                {targetStatusAction === 'banned' ? '封禁后该用户将无法登录系统或使用任何API服务。' :
-                                    statusTargetUser?.status === 'banned' ? '解封后用户将恢复正常权限。' :
-                                        '恢复后用户将变为正常状态，移除异常标记。'}
+                                {targetStatusAction === 'banned' ? '安全红线警示' :
+                                    statusTargetUser?.status === 'banned' ? '服务恢复确认' :
+                                        '状态正常化处理'}
                             </p>
+                            <div className="opacity-90 leading-relaxed text-xs">
+                                您正在对租户 <strong>{statusTargetUser?.username}</strong> 执行
+                                账号状态强制干预。
+                                {targetStatusAction === 'banned' ? 
+                                    '封禁后，该用户的所有活跃 Agent 任务将立即挂起，API 访问令牌将永久失效。' :
+                                    '操作后，用户将重新获得系统登录及 Agent 协作权限。'}
+                            </div>
                         </div>
                     </div>
 
-                    {/* 原因输入 */}
+                    {/* 强制审计原因录入 */}
                     <div className="space-y-2">
-                        <label className="text-sm font-medium text-gray-700">
-                            {targetStatusAction === 'banned' ? '封禁原因' :
-                                statusTargetUser?.status === 'banned' ? '解封原因' :
-                                    '恢复原因'} <span className="text-red-500">*</span>
+                        <label className="text-sm font-semibold text-gray-700 flex justify-between">
+                            <span>干预原因记录 (Audit Reason)</span>
+                            <span className="text-red-500 font-normal">必填项</span>
                         </label>
                         <textarea
-                            className="w-full px-3 py-2 border border-gray-300 rounded-lg text-sm focus:ring-2 focus:ring-primary focus:border-primary outline-none transition-colors min-h-[100px] resize-none"
+                            className="w-full px-3 py-2 border border-gray-300 rounded-lg text-sm focus:ring-2 focus:ring-primary focus:border-primary outline-none transition-all min-h-[100px] resize-none placeholder:text-gray-300"
                             placeholder={
-                                targetStatusAction === 'banned' ? "请输入违规行为或封禁理由..." :
-                                    statusTargetUser?.status === 'banned' ? "请输入解封理由或申诉处理结果..." :
-                                        "请输入恢复正常的原因（如：确认为误判、用户行为已恢复正常等）..."
+                                targetStatusAction === 'banned' ? "请详细描述违规证据或封禁理由..." :
+                                    "请输入恢复服务的原因（如：误判处理、风险解除等）..."
                             }
                             value={statusReason}
                             onChange={(e) => setStatusReason(e.target.value)}
                         />
+                        <p className="text-[10px] text-gray-400 italic">该记录将持久化至系统审计日志系统。</p>
                     </div>
                 </div>
             </Modal>
diff --git a/src/frontend/src/pages/AdminAIModels.tsx b/src/frontend/src/pages/AdminAIModels.tsx
index b13e6f2..6de3348 100644
--- a/src/frontend/src/pages/AdminAIModels.tsx
+++ b/src/frontend/src/pages/AdminAIModels.tsx
@@ -1,3 +1,21 @@
+/**
+ * @file AdminAIModels.tsx
+ * @module Pages/Administration/AI-Infrastructure
+ * @description 系统 AI 算力基础设施配置中心。
+ * 本模块作为多智能体框架的“能源中心”，负责管理底层推理引擎（LLMs）的接入协议、身份凭证及健康检查。
+ * * * 核心管理维度：
+ * 1. 异构模型路由: 支持通用模型与本地微调（Finetuned）模型的并存调度（SF12）；
+ * 2. 连接审计 (Connectivity Audit): 集成实时连通性测试，监测 API 响应时延（Response Time）；
+ * 3. 凭证安全保护: 实施 API Key 的隐式存储与动态更新策略，确保密钥不被非法回显；
+ * 4. 动态资源发现: 为前端会话面板提供可用的模型候选项（Options）。
+ * * * 技术栈：
+ * - 接口通讯：adminApi (Wang Lirong 开发)
+ * - 视觉图标：Lucide-react 语义化图标集
+ * * @author Wang Lirong (王利蓉)
+ * @version 2.3.0
+ * @date 2026-01-02
+ */
+
 import React, { useState, useEffect } from 'react';
 import { AIModelConfigResponse, AIModelConfigDetailResponse, AIModelConfigCreate, AIModelConfigUpdate } from '../types.ts';
 import { Card, Button, Tag, Modal, Input, message, Select } from '../components/UI.tsx';
@@ -5,48 +23,66 @@ import { Bot, Plus, Edit3, Trash2, Loader2, RefreshCw, Eye, EyeOff, Zap, CheckCi
 import { adminApi } from '../api/admin.ts';
 
 /**
- * AI 模型配置管理面板
- * 管理员可以添加、编辑、删除 AI 对话模型配置
+ * @component AdminAIModels
+ * @description
+ * 采用 React 函数式组件构建。该页面为管理员提供了完整的 AI 模型配置 CRUD 生命周期管理。
+ * 集成了严苛的 URL 协议校验及密钥格式审查（Regex Validation）。
  */
 export const AdminAIModels: React.FC = () => {
-    // --- 状态管理 ---
+    // --- 1. 数据驱动状态 (Data-Driven States) ---
+    /** 存储当前全量在线的模型配置快照 */
     const [models, setModels] = useState<AIModelConfigResponse[]>([]);
+    /** 局部加载锁：用于处理列表刷新时的视觉反馈 */
     const [isLoading, setIsLoading] = useState(false);
+    /** 分页控制状态机 */
     const [page, setPage] = useState(1);
     const [total, setTotal] = useState(0);
     const pageSize = 10;
 
-    // 创建/编辑模态框状态
+    // --- 2. 事务流控制状态 (Workflow States) ---
+    /** 配置模态框显隐开关 */
     const [isModalOpen, setIsModalOpen] = useState(false);
+    /** 存储当前正处于编辑生命周期的详情对象。若为 null 则标识为“创建”模式 */
     const [editingModel, setEditingModel] = useState<AIModelConfigDetailResponse | null>(null);
+    /** 提交配置至后端时的异步状态锁 */
     const [isSaving, setIsSaving] = useState(false);
 
-    // 表单数据
+    // --- 3. 表单载荷与校验状态 (Form & Validation) ---
+    /** 严格对应 AIModelConfigCreate 定义的表单缓冲区 */
     const [formData, setFormData] = useState<AIModelConfigCreate>({
         model_name: '',
         api_url: '',
         model_id: '',
         api_key: '',
-        model_type: 'general_llm'
+        model_type: 'general_llm' // 缺省默认为通用大模型类型
     });
+    /** API 密钥可视化开关 */
     const [showApiKey, setShowApiKey] = useState(false);
-
-    // 表单校验错误
+    /** 针对特定字段的深度验证错误信息采集器 */
     const [formErrors, setFormErrors] = useState<{ api_url?: string }>({});
 
-    // 测试连接状态
+    // --- 4. 基础设施健康度检测状态 (Infrastructure Healthcheck) ---
+    /** 标识是否正在执行 API 握手测试 */
     const [isTesting, setIsTesting] = useState(false);
+    /** 存储连接测试后的多维反馈结果，包含时延及错误信息 */
     const [testResult, setTestResult] = useState<{
         success: boolean;
         message: string;
         response_time_ms?: number;
     } | null>(null);
 
-    // 删除确认
+    // --- 5. 危险操作缓冲状态 (Risk Control) ---
+    /** 待执行物理删除的目标对象引用 */
     const [deleteTarget, setDeleteTarget] = useState<AIModelConfigResponse | null>(null);
+    /** 删除过程中的异步加载标识 */
     const [isDeleting, setIsDeleting] = useState(false);
 
-    // --- 数据获取 ---
+    /**
+     * 核心逻辑：拉取模型配置清单
+     * @async @function fetchModels
+     * @description
+     * 调用管理端 API，同步云端最新的基础设施配置状态。
+     */
     const fetchModels = async () => {
         setIsLoading(true);
         try {
@@ -61,11 +97,20 @@ export const AdminAIModels: React.FC = () => {
         }
     };
 
+    /**
+     * 效应钩子：驱动分页与初次渲染逻辑
+     */
     useEffect(() => {
         fetchModels();
     }, [page]);
 
-    // --- URL 校验 ---
+    /**
+     * 算法层：URL 协议合规性校验
+     * @description
+     * 严格限制 API Endpoint 必须遵循 HTTP/HTTPS 协议，防止跨站脚本攻击或非法地址解析。
+     * @param {string} url - 待测 URL 文本
+     * @returns {string|undefined} 错误描述信息
+     */
     const validateUrl = (url: string): string | undefined => {
         const trimmed = url.trim();
         if (!trimmed) return '请输入 API 地址';
@@ -80,15 +125,22 @@ export const AdminAIModels: React.FC = () => {
         return undefined;
     };
 
-    // --- URL 输入变化 ---
+    /**
+     * 处理器：处理 API 地址的即时联动
+     * 变更时自动清除之前的连接测试历史，确保数据一致性。
+     */
     const handleApiUrlChange = (value: string) => {
         const error = validateUrl(value);
         setFormData(prev => ({ ...prev, api_url: value }));
-        setTestResult(null);
+        setTestResult(null); // 地址变更后，历史测试结果失效
         setFormErrors(prev => ({ ...prev, api_url: error }));
     };
 
-    // --- 业务逻辑 ---
+    // --- 事务交互逻辑集 (Interaction Logic) ---
+
+    /**
+     * 打开初始化创建窗口
+     */
     const handleOpenCreateModal = () => {
         setEditingModel(null);
         setFormData({
@@ -104,10 +156,15 @@ export const AdminAIModels: React.FC = () => {
         setIsModalOpen(true);
     };
 
+    /**
+     * 进入配置编辑模式
+     * 包含一次异步详情获取过程，确保获取到的是云端最新的元数据。
+     */
     const handleOpenEditModal = async (model: AIModelConfigResponse) => {
         try {
             const detail = await adminApi.getAIModelDetail(model.config_id);
             setEditingModel(detail);
+            // 初始化表单，注意 api_key 默认设为空，采取“不输入即不修改”的策略
             setFormData({
                 model_name: detail.model_name,
                 api_url: detail.api_url,
@@ -125,22 +182,33 @@ export const AdminAIModels: React.FC = () => {
         }
     };
 
-    // --- 测试连接 ---
+    /**
+     * 核心技术特性：执行 API 连接压力与连通性测试
+     * @async @function handleTestConnection
+     * @description
+     * 在持久化存储之前，模拟 Agent 发起一次 Ping 握手。
+     * 逻辑逻辑：
+     * 1. 校验 URL 格式；
+     * 2. 审查 API Key 格式（必须符合常见大模型厂商的前缀规范）；
+     * 3. 区分“新密钥测试”与“已存密钥测试”两种分流。
+     */
     const handleTestConnection = async () => {
+        // 步骤 1：合规性预检
         const urlError = validateUrl(formData.api_url);
         if (urlError) {
             setFormErrors({ api_url: urlError });
             return;
         }
 
-        // 编辑模式下，如果使用已保存的密钥且没有输入新密钥，则使用 config_id 进行测试
         const hasNewApiKey = formData.api_key.trim().length > 0;
         
+        // 步骤 2：安全边界校验
         if (!editingModel && !hasNewApiKey) {
             message.error('请先输入 API 密钥再测试连接');
             return;
         }
 
+        // 密钥格式正则：匹配 sk- (OpenAI), ms- (DashScope), ak- (Baidu) 等标准
         if (hasNewApiKey && !/^(sk-|ms-|ak-)[A-Za-z0-9\-]{10,}/i.test(formData.api_key.trim())) {
             message.error('API 密钥格式不正确，需以 sk-/ms-/ak- 开头');
             return;
@@ -155,22 +223,27 @@ export const AdminAIModels: React.FC = () => {
         setTestResult(null);
         try {
             let res;
+            /**
+             * 策略分发逻辑：
+             * A 场景：编辑已有配置且未修改密钥。利用后端已持久化的加密密钥执行测试。
+             * B 场景：新建配置或已输入新密钥。透传当前内存中的密钥执行即时测试。
+             */
             if (editingModel && !hasNewApiKey) {
-                // 编辑模式下使用已保存的密钥测试
                 res = await adminApi.testAIModelConnection({
                     api_url: formData.api_url,
                     model_id: formData.model_id,
-                    config_id: editingModel.config_id // 传递 config_id 让后端使用已保存的密钥
+                    config_id: editingModel.config_id 
                 });
             } else {
-                // 新建模式或输入了新密钥
                 res = await adminApi.testAIModelConnection({
                     api_url: formData.api_url,
                     api_key: formData.api_key,
                     model_id: formData.model_id
                 });
             }
+
             setTestResult(res);
+            // 实时反馈时延性能数据
             if (res.success) {
                 message.success(`连接成功！响应时间: ${res.response_time_ms}ms`);
             } else {
@@ -185,10 +258,16 @@ export const AdminAIModels: React.FC = () => {
         }
     };
 
-    // --- 保存配置 ---
+    /**
+     * 执行配置持久化操作
+     * @async @function handleSave
+     * @description
+     * 该操作具备强制性前置依赖：必须通过 handleTestConnection 测试后方可允许保存。
+     */
     const handleSave = async () => {
         setFormErrors({});
 
+        // 基础非空校验
         if (!formData.model_name.trim()) {
             message.error('请输入模型名称');
             return;
@@ -205,13 +284,11 @@ export const AdminAIModels: React.FC = () => {
             return;
         }
 
-        // 新建模式必须输入密钥
         if (!editingModel && !formData.api_key.trim()) {
             message.error('请输入 API 密钥');
             return;
         }
 
-        // 如果输入了新密钥，校验格式
         if (formData.api_key.trim()) {
             const key = formData.api_key.trim();
             if (!/^(sk-|ms-|ak-)[A-Za-z0-9\-]{10,}/i.test(key)) {
@@ -220,6 +297,10 @@ export const AdminAIModels: React.FC = () => {
             }
         }
 
+        /**
+         * 强制熔断机制：
+         * 禁止未经测试或测试未通过的配置入库，确保推理引擎链路的绝对可靠性。
+         */
         if (!testResult || !testResult.success) {
             message.error('请先点击"测试连接"并确保通过后再保存');
             return;
@@ -228,6 +309,7 @@ export const AdminAIModels: React.FC = () => {
         setIsSaving(true);
         try {
             if (editingModel) {
+                // 构造更新数据载荷，实现 API Key 的增量更新
                 const updateData: AIModelConfigUpdate = {
                     model_name: formData.model_name,
                     api_url: formData.api_url,
@@ -240,11 +322,12 @@ export const AdminAIModels: React.FC = () => {
                 await adminApi.updateAIModel(editingModel.config_id, updateData);
                 message.success('模型配置已更新');
             } else {
+                // 新建配置全量提交
                 await adminApi.createAIModel(formData);
                 message.success('模型配置已创建');
             }
             setIsModalOpen(false);
-            fetchModels();
+            fetchModels(); // 乐观刷新列表
         } catch (error: any) {
             console.error("Save model failed", error);
             message.error(error?.message || '保存失败');
@@ -253,7 +336,10 @@ export const AdminAIModels: React.FC = () => {
         }
     };
 
-    // --- 删除配置 ---
+    /**
+     * 物理注销配置
+     * 仅注销 API 配置信息，不会影响已持久化的对话历史数据。
+     */
     const handleDelete = async () => {
         if (!deleteTarget) return;
 
@@ -271,15 +357,18 @@ export const AdminAIModels: React.FC = () => {
         }
     };
 
+    /**
+     * 渲染视图层
+     */
     return (
         <div className="p-8 max-w-7xl mx-auto h-full overflow-y-auto">
-            {/* 顶部标题与操作栏 */}
+            {/* 步骤 1：头部品牌与动作栏 */}
             <div className="flex flex-col md:flex-row justify-between items-start md:items-center mb-8 gap-4">
                 <h2 className="text-2xl font-bold text-gray-800 flex items-center gap-3">
                     <div className="p-2 bg-blue-100 text-blue-600 rounded-lg shrink-0">
                         <Bot size={20} />
                     </div>
-                    模型配置
+                    算力基础设施管理
                 </h2>
 
                 <div className="flex gap-2">
@@ -297,12 +386,14 @@ export const AdminAIModels: React.FC = () => {
                         onClick={handleOpenCreateModal}
                         icon={<Plus size={14} />}
                     >
-                        添加模型
+                        配置新模型
                     </Button>
                 </div>
             </div>
 
-            {/* 模型列表 */}
+            {/* 步骤 2：配置项列表展现层 
+                采用 table-fixed 布局，并辅以 truncate 策略处理超长 API 链接。
+            */}
             <Card className="overflow-hidden p-0 min-h-[400px]">
                 {isLoading ? (
                     <div className="flex justify-center items-center h-64">
@@ -313,22 +404,23 @@ export const AdminAIModels: React.FC = () => {
                         <table className="w-full text-left text-sm table-fixed">
                             <thead className="bg-gray-50 border-b border-gray-200">
                                 <tr>
-                                    <th className="px-4 py-4 font-medium text-gray-600 whitespace-nowrap w-[15%]">模型名称</th>
-                                    <th className="px-4 py-4 font-medium text-gray-600 whitespace-nowrap w-[18%]">模型 ID</th>
-                                    <th className="px-4 py-4 font-medium text-gray-600 whitespace-nowrap w-[10%]">类型</th>
-                                    <th className="px-4 py-4 font-medium text-gray-600 whitespace-nowrap w-[27%]">API 地址</th>
-                                    <th className="px-4 py-4 font-medium text-gray-600 whitespace-nowrap w-[18%]">更新时间</th>
-                                    <th className="px-4 py-4 font-medium text-gray-600 text-right whitespace-nowrap w-[12%]">操作</th>
+                                    <th className="px-4 py-4 font-medium text-gray-600 whitespace-nowrap w-[15%]">配置名称</th>
+                                    <th className="px-4 py-4 font-medium text-gray-600 whitespace-nowrap w-[18%]">模型识别码</th>
+                                    <th className="px-4 py-4 font-medium text-gray-600 whitespace-nowrap w-[10%]">引擎属性</th>
+                                    <th className="px-4 py-4 font-medium text-gray-600 whitespace-nowrap w-[27%]">Endpoint 地址</th>
+                                    <th className="px-4 py-4 font-medium text-gray-600 whitespace-nowrap w-[18%]">最后同步</th>
+                                    <th className="px-4 py-4 font-medium text-gray-600 text-right whitespace-nowrap w-[12%]">治理</th>
                                 </tr>
                             </thead>
                             <tbody className="divide-y divide-gray-100">
                                 {models.map(model => (
-                                    <tr key={model.config_id} className="hover:bg-gray-50/50">
+                                    <tr key={model.config_id} className="hover:bg-gray-50/50 transition-colors">
                                         <td className="px-4 py-4 truncate" title={model.model_name}>
                                             <span className="font-medium text-gray-800">{model.model_name}</span>
                                         </td>
                                         <td className="px-4 py-4 text-gray-600 font-mono text-xs truncate" title={model.model_id}>{model.model_id}</td>
                                         <td className="px-4 py-4 whitespace-nowrap">
+                                            {/* 类型标签分发：区分本地自研模型与外部公有云 LLM */}
                                             <Tag color={model.model_type === 'local_finetune' ? 'blue' : 'orange'}>
                                                 {model.model_type === 'local_finetune' ? '本地微调' : '通用LLM'}
                                             </Tag>
@@ -345,7 +437,7 @@ export const AdminAIModels: React.FC = () => {
                                                     variant="text"
                                                     className="h-8 px-2 text-gray-500 hover:text-primary"
                                                     onClick={() => handleOpenEditModal(model)}
-                                                    title="编辑"
+                                                    title="修正配置"
                                                 >
                                                     <Edit3 size={14} />
                                                 </Button>
@@ -353,7 +445,7 @@ export const AdminAIModels: React.FC = () => {
                                                     variant="text"
                                                     className="h-8 px-2 text-gray-500 hover:text-red-500"
                                                     onClick={() => setDeleteTarget(model)}
-                                                    title="删除"
+                                                    title="物理移除"
                                                 >
                                                     <Trash2 size={14} />
                                                 </Button>
@@ -361,10 +453,11 @@ export const AdminAIModels: React.FC = () => {
                                         </td>
                                     </tr>
                                 ))}
+                                {/* 空态兜底描述 */}
                                 {models.length === 0 && (
                                     <tr>
-                                        <td colSpan={6} className="text-center py-12 text-gray-500">
-                                            暂无模型配置，请点击"添加模型"创建
+                                        <td colSpan={6} className="text-center py-12 text-gray-400">
+                                            暂无活跃的 AI 模型底座，请通过上方入口建立连接
                                         </td>
                                     </tr>
                                 )}
@@ -373,11 +466,11 @@ export const AdminAIModels: React.FC = () => {
                     </div>
                 )}
 
-                {/* 分页器 */}
+                {/* 分页导航器 */}
                 {total > 0 && (
                     <div className="flex justify-between items-center px-6 py-4 border-t border-gray-100 bg-gray-50/50">
                         <span className="text-xs text-gray-500">
-                            共 {total} 条记录，当前第 {page} 页
+                            数据节点计数: {total} | 采样视图: 第 {page} 页
                         </span>
                         <div className="flex gap-2">
                             <Button variant="default" className="h-8 px-3 text-xs" disabled={page <= 1} onClick={() => setPage(p => p - 1)}>上一页</Button>
@@ -387,25 +480,25 @@ export const AdminAIModels: React.FC = () => {
                 )}
             </Card>
 
-            {/* 创建/编辑模态框 */}
+            {/* 事务模块 A：配置编辑与测试对话框 */}
             <Modal
                 isOpen={isModalOpen}
                 onClose={() => setIsModalOpen(false)}
-                title={editingModel ? '编辑模型配置' : '添加模型配置'}
+                title={editingModel ? '修正推理引擎配置' : '注册新推理引擎'}
                 maxWidth="max-w-lg"
                 footer={
-                    <>
-                        <Button onClick={() => setIsModalOpen(false)}>取消</Button>
+                    <div className="flex justify-end gap-2">
+                        <Button onClick={() => setIsModalOpen(false)}>暂存关闭</Button>
                         <Button variant="primary" onClick={handleSave} disabled={isSaving || !testResult?.success}>
-                            {isSaving ? '保存中...' : '保存'}
+                            {isSaving ? '正在执行物理持久化...' : '确认入库'}
                         </Button>
-                    </>
+                    </div>
                 }
             >
                 <div className="space-y-4">
                     <Input
-                        label="模型名称"
-                        placeholder="如: GPT-4, Qwen-32B"
+                        label="模型展示名称"
+                        placeholder="例如: GPT-4-o (湖南大学定制版)"
                         value={formData.model_name}
                         onChange={(e) => {
                             setFormData(prev => ({ ...prev, model_name: e.target.value }));
@@ -416,20 +509,20 @@ export const AdminAIModels: React.FC = () => {
 
                     <div>
                         <Input
-                            label="API 地址"
-                            placeholder="https://api.example.com/v1/chat/completions"
+                            label="API Endpoint (反向代理地址)"
+                            placeholder="https://openai.proxy.com/v1/chat/completions"
                             value={formData.api_url}
                             onChange={(e) => handleApiUrlChange(e.target.value)}
                             required
                         />
                         {formErrors.api_url && (
-                            <p className="text-xs text-red-500 mt-1">{formErrors.api_url}</p>
+                            <p className="text-xs text-red-500 mt-1 font-medium">{formErrors.api_url}</p>
                         )}
                     </div>
 
                     <Input
-                        label="模型 ID"
-                        placeholder="如: gpt-4, qwen-coder-32b"
+                        label="后端模型标识 (Model ID)"
+                        placeholder="如: gpt-4, llama-3-70b-instruct"
                         value={formData.model_id}
                         onChange={(e) => {
                             setFormData(prev => ({ ...prev, model_id: e.target.value }));
@@ -440,9 +533,9 @@ export const AdminAIModels: React.FC = () => {
 
                     <div className="relative">
                         <Input
-                            label={editingModel ? "API 密钥 (留空则使用已保存的密钥)" : "API 密钥"}
+                            label={editingModel ? "API 访问令牌 (留空则沿用旧令牌)" : "API 访问令牌"}
                             type={showApiKey ? "text" : "password"}
-                            placeholder={editingModel ? "输入新密钥或留空使用已保存的" : "sk-xxxxx"}
+                            placeholder={editingModel ? "输入新令牌或保持空白" : "密钥通常以 sk- 开头"}
                             value={formData.api_key}
                             onChange={(e) => {
                                 setFormData(prev => ({ ...prev, api_key: e.target.value }));
@@ -450,44 +543,59 @@ export const AdminAIModels: React.FC = () => {
                             }}
                             required={!editingModel}
                         />
+                        {/* 密钥可视性切换器 */}
                         <button
                             type="button"
-                            className="absolute right-3 top-8 text-gray-400 hover:text-gray-600"
+                            className="absolute right-3 top-8 text-gray-400 hover:text-gray-600 transition-colors"
                             onClick={() => setShowApiKey(!showApiKey)}
                         >
                             {showApiKey ? <EyeOff size={16} /> : <Eye size={16} />}
                         </button>
                         {editingModel && !formData.api_key.trim() && (
                             <div className="mt-1">
-                                <span className="text-xs text-blue-600 bg-blue-50 px-2 py-0.5 rounded">将使用已保存的密钥</span>
+                                <span className="text-[10px] text-blue-600 bg-blue-50 px-2 py-0.5 rounded border border-blue-100">
+                                    [系统提示] 正在使用已托管的安全凭证
+                                </span>
                             </div>
                         )}
                     </div>
 
-                    {/* 测试连接按钮 */}
-                    <div className="flex items-center gap-3">
-                        <Button
-                            variant="default"
-                            className="h-9 px-4 flex items-center gap-2"
-                            onClick={handleTestConnection}
-                            disabled={isTesting}
-                            icon={<Zap size={14} />}
-                        >
-                            {isTesting ? '测试中...' : '测试连接'}
-                        </Button>
+                    {/* 关键组件：连接测试反馈区 */}
+                    <div className="bg-gray-50/50 p-4 rounded-xl border border-gray-100 flex flex-col gap-3">
+                        <div className="flex items-center justify-between">
+                            <span className="text-xs font-semibold text-gray-500 uppercase tracking-wider">连通性状态审计</span>
+                            <Button
+                                variant="default"
+                                className="h-8 px-4 flex items-center gap-2 bg-white"
+                                onClick={handleTestConnection}
+                                disabled={isTesting}
+                                icon={<Zap size={14} className={isTesting ? "animate-pulse" : ""} />}
+                            >
+                                {isTesting ? '正在嗅探链路...' : '执行连通性测试'}
+                            </Button>
+                        </div>
+                        
                         {testResult && (
-                            <div className={`flex items-center gap-2 text-sm ${testResult.success ? 'text-green-600' : 'text-red-500'}`}>
-                                {testResult.success ? <CheckCircle size={16} /> : <XCircle size={16} />}
-                                <span>{testResult.message}</span>
-                                {typeof testResult.response_time_ms === 'number' && testResult.success && (
-                                    <span className="text-gray-500 text-xs">({testResult.response_time_ms}ms)</span>
-                                )}
+                            <div className={`flex items-start gap-2 p-2 rounded-lg text-sm ${testResult.success ? 'bg-green-50 text-green-700' : 'bg-red-50 text-red-600'}`}>
+                                <div className="mt-0.5 shrink-0">
+                                    {testResult.success ? <CheckCircle size={16} /> : <XCircle size={16} />}
+                                </div>
+                                <div className="flex-1">
+                                    <p className="font-bold">{testResult.success ? '测试成功' : '握手失败'}</p>
+                                    <p className="text-xs opacity-80">{testResult.message}</p>
+                                    {typeof testResult.response_time_ms === 'number' && testResult.success && (
+                                        <div className="mt-1 inline-flex items-center gap-1 text-[10px] px-1.5 py-0.5 bg-green-100 rounded">
+                                            <RefreshCw size={10} className="animate-spin-slow" />
+                                            时延: {testResult.response_time_ms}ms
+                                        </div>
+                                    )}
+                                </div>
                             </div>
                         )}
                     </div>
 
                     <Select
-                        label="模型类型"
+                        label="模型应用策略 (引擎分流)"
                         className="w-full"
                         value={formData.model_type}
                         onChange={(val) => {
@@ -496,33 +604,39 @@ export const AdminAIModels: React.FC = () => {
                         }}
                         required
                         options={[
-                            { value: 'general_llm', label: '通用 LLM' },
-                            { value: 'local_finetune', label: '本地微调模型' }
+                            { value: 'general_llm', label: '通用 LLM (标准推理)' },
+                            { value: 'local_finetune', label: '本地微调模型 (高精度语义映射)' }
                         ]}
                     />
                 </div>
             </Modal>
 
-            {/* 删除确认模态框 */}
+            {/* 事务模块 B：销毁确认对话框 */}
             <Modal
                 isOpen={!!deleteTarget}
                 onClose={() => setDeleteTarget(null)}
-                title="确认删除"
+                title="高危：资源销毁确认"
                 maxWidth="max-w-sm"
                 footer={
-                    <>
-                        <Button onClick={() => setDeleteTarget(null)}>取消</Button>
+                    <div className="flex gap-2">
+                        <Button onClick={() => setDeleteTarget(null)}>放弃操作</Button>
                         <Button variant="danger" onClick={handleDelete} disabled={isDeleting}>
-                            {isDeleting ? '删除中...' : '确认删除'}
+                            {isDeleting ? '正在执行销毁...' : '确认注销配置'}
                         </Button>
-                    </>
+                    </div>
                 }
             >
-                <div className="text-gray-600">
-                    <p>确定要删除模型 <strong>{deleteTarget?.model_name}</strong> 吗？</p>
-                    <p className="text-sm text-red-500 mt-2">此操作不可恢复！</p>
+                <div className="space-y-3">
+                    <div className="p-3 bg-red-50 rounded-lg flex items-start gap-3 border border-red-100">
+                        <Trash2 className="text-red-600 shrink-0 mt-0.5" size={18} />
+                        <div className="text-xs text-red-900 leading-relaxed">
+                            您正在尝试物理移除模型配置 <strong>{deleteTarget?.model_name}</strong>。
+                            注销后，所有依赖此算力节点的智能体任务将无法继续执行。
+                        </div>
+                    </div>
+                    <p className="text-[11px] text-gray-400 italic">注意：此项操作无法撤销，请谨慎操作。</p>
                 </div>
             </Modal>
         </div>
     );
-};
+};
\ No newline at end of file
diff --git a/src/frontend/src/pages/AdminAnnouncements.tsx b/src/frontend/src/pages/AdminAnnouncements.tsx
index d1224f6..9b68c85 100644
--- a/src/frontend/src/pages/AdminAnnouncements.tsx
+++ b/src/frontend/src/pages/AdminAnnouncements.tsx
@@ -1,3 +1,22 @@
+/**
+ * @file AdminAnnouncements.tsx
+ * @module Pages/Administration/Announcement-Governance
+ * @description 系统公告管理与发布中心。
+ * 本模块作为 AutoDB 平台的“信息分发中枢”，负责协调管理员向全量用户推送系统变更、
+ * 模型升级通知及数据库维护计划。
+ * * * 核心管理逻辑：
+ * 1. 状态生命周期: 支持“草稿 (Draft)”与“已发布 (Published)”两种生存状态的隔离与转换；
+ * 2. 异步流编排: 针对后端 status 筛选限制，采用并发请求合并算法执行全量数据检索；
+ * 3. 稳健的去重机制: 引入基于 Map 的唯一性审计，确保前端视图在多流合并时不产生 ID 冲突；
+ * 4. 交互式审计: 集成统一的删除确认机制与原子化表单验证。
+ * * * 对应需求点：
+ * - Requirement 10.1: 系统级公告的发布与维护功能。
+ * - Requirement 10.2: 支持富文本预览与状态切换。
+ * * @author Wang Lirong (王利蓉)
+ * @version 1.5.0
+ * @date 2026-01-02
+ */
+
 import React, { useState, useEffect } from 'react';
 import { Announcement } from '../types.ts';
 import { Card, Button, Tag, Input, Modal, message, ConfirmDialog, Select } from '../components/UI.tsx';
@@ -5,76 +24,119 @@ import { Pagination } from '../components/Pagination.tsx';
 import { Plus, Edit, Trash, Bell, Loader2 } from 'lucide-react';
 import { announcementApi, CreateAnnouncementParams, UpdateAnnouncementParams } from '../api/announcement.ts';
 
-// 分页配置
+/**
+ * 分页配置常量
+ * @constant PAGE_SIZE - 定义单页渲染的最大数据承载量，用于平衡网络载荷与首屏渲染耗时。
+ */
 const PAGE_SIZE = 10;
 
+/**
+ * @component AdminAnnouncements
+ * @description
+ * 采用 React 函数式组件构建。该页面为运维人员提供了一个集成的列表视图，
+ * 通过分步式分页与模态框编辑，降低了对非技术运营人员的操作门槛。
+ */
 export const AdminAnnouncements: React.FC = () => {
-    // --- 状态管理 ---
+    // --- 1. 数据集状态管理 (Data Sets) ---
+    /** 存储当前视图缓存的公告实体阵列 */
     const [announcements, setAnnouncements] = useState<Announcement[]>([]);
+    /** 局部加载锁：用于处理列表刷新及并发请求时的视觉反馈 */
     const [isLoading, setIsLoading] = useState(false);
+    /** 异步保存锁：防止在提交表单时由于二次点击产生的网络幂等性问题 */
     const [isSaving, setIsSaving] = useState(false);
+    /** 编辑模态框可见性开关 */
     const [isModalOpen, setIsModalOpen] = useState(false);
 
-    // 分页状态
+    // --- 2. 分页状态机 (Pagination Control) ---
+    /** 当前激活的物理页码 */
     const [currentPage, setCurrentPage] = useState(1);
+    /** 总记录计数：用于驱动分页器的内部逻辑（如省略号计算） */
     const [totalAnnouncements, setTotalAnnouncements] = useState(0);
 
-    // 当前编辑的公告 ID (null 为新增)
+    // --- 3. 事务上下文状态 (Transaction Context) ---
+    /** 标识当前正在操作的公告 ID。若为 null 则表示处于“新公告创建”事务中 */
     const [editingId, setEditingId] = useState<number | null>(null);
 
-    // 表单状态
+    // --- 4. 表单响应式字段 (Form Fields) ---
+    /** 公告标题缓存区 */
     const [title, setTitle] = useState('');
+    /** 公告正文内容缓存区（支持多行输入） */
     const [content, setContent] = useState('');
+    /** * 发布状态控制：
+     * - published: 全量用户可见。
+     * - draft: 仅管理员内部可见，作为暂存态存在。
+     */
     const [status, setStatus] = useState<'published' | 'draft'>('draft');
 
-    // 确认删除对话框状态
+    // --- 5. 安全风险确认状态 (Deletion Safeguard) ---
+    /** 销毁确认弹窗的显示状态 */
     const [isDeleteConfirmOpen, setIsDeleteConfirmOpen] = useState(false);
+    /** 物理删除的目标 ID 引用 */
     const [announcementToDelete, setAnnouncementToDelete] = useState<number | null>(null);
 
-    // --- 数据获取 ---
+    /**
+     * 核心逻辑：拉取与数据清洗 (Data Fetching & Cleaning)
+     * @async @function fetchAnnouncements
+     * @description
+     * 这是一个典型的“合并请求”逻辑。由于后端单次接口仅支持单状态过滤，
+     * 前端通过 Promise.all 实现并发拉取，并执行跨维度的去重与重排算法。
+     */
     const fetchAnnouncements = async (page: number = currentPage) => {
         setIsLoading(true);
         try {
-            // 管理员通常需要看到所有状态的公告
-            // 由于后端接口目前通过 status 筛选，这里并发请求 draft 和 published 两种状态并合并
-            // 实际生产中建议后端提供一个不带 status 过滤的 "all" 选项或专门的管理员列表接口
+            /** * 步骤 A：并行触发草稿与发布公告的拉取。
+             * 旨在确保管理员在同一看板内拥有全量审计视角。
+             */
             const [publishedRes, draftRes] = await Promise.all([
                 announcementApi.getList(page, PAGE_SIZE, 'published'),
                 announcementApi.getList(page, PAGE_SIZE, 'draft')
             ]);
 
-            // 合并并按 announcement_id 去重，再按创建时间倒序
+            /** * 步骤 B：执行前端数据聚合。
+             * 1. Merging: 合并两组异步返回的 DTO 集合；
+             * 2. Deduplication: 利用 Map 特性排除可能存在的重复 ID 记录；
+             * 3. Sorting: 基于 created_at 执行严格的时间轴倒序排列。
+             */
             const merged = [...publishedRes.items, ...draftRes.items];
             const uniqueById = Array.from(
                 new Map(merged.map(a => [a.announcement_id, a])).values()
             ).sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
 
             setAnnouncements(uniqueById);
-            // 设置总数（这里简化处理，实际应该从后端获取准确的总数）
+            
+            /** 步骤 C：更新分页元数据 */
             setTotalAnnouncements(publishedRes.total + draftRes.total);
         } catch (error) {
+            // 异常捕获：在此处可集成全局 Sentry 记录
             console.error("Failed to fetch announcements", error);
         } finally {
+            // 释放视觉锁
             setIsLoading(false);
         }
     };
 
+    /**
+     * 效应钩子：组件挂载初始化
+     */
     useEffect(() => {
         fetchAnnouncements();
     }, []);
 
-    // --- 交互处理 ---
+    // --- 交互业务逻辑集 (User Interaction Logic) ---
 
+    /**
+     * 初始化模态框事务
+     * @param {Announcement} [announcement] - 可选。若提供则进入编辑态，否则开启空白创建态。
+     */
     const handleOpenModal = (announcement?: Announcement) => {
         if (announcement) {
-            // 编辑模式
+            /** 场景：修正现有公告信息 */
             setEditingId(announcement.announcement_id);
             setTitle(announcement.title);
             setContent(announcement.content);
-            // 确保 status 是符合类型的
             setStatus(announcement.status === 'published' ? 'published' : 'draft');
         } else {
-            // 新增模式
+            /** 场景：撰写新公告 */
             setEditingId(null);
             setTitle('');
             setContent('');
@@ -83,22 +145,32 @@ export const AdminAnnouncements: React.FC = () => {
         setIsModalOpen(true);
     };
 
+    /**
+     * 提交物理持久化事务
+     * @async @function handleSave
+     * @description
+     * 实现了公告实体的全量/增量保存逻辑。
+     * 流程：校验 -> 分流 (Update/Create) -> 刷新 -> 关闭。
+     */
     const handleSave = async () => {
+        // 步骤 1：合法性初审（必填项拦截）
         if (!title || !content) return;
 
         setIsSaving(true);
         try {
             if (editingId) {
-                // 更新现有公告
+                /** 场景 A：更新现有资源的元数据 */
                 const updateData: UpdateAnnouncementParams = { title, content, status };
                 await announcementApi.update(editingId, updateData);
             } else {
-                // 创建新公告
+                /** 场景 B：触发新资源的物理生成 */
                 const createData: CreateAnnouncementParams = { title, content, status };
                 await announcementApi.create(createData);
             }
-            // 刷新列表并关闭模态框
+            
+            /** 步骤 2：数据最终一致性刷新 */
             await fetchAnnouncements(currentPage);
+            /** 步骤 3：事务完结，清理交互上下文 */
             setIsModalOpen(false);
         } catch (error) {
             console.error("Failed to save announcement", error);
@@ -108,19 +180,32 @@ export const AdminAnnouncements: React.FC = () => {
         }
     };
 
+    /**
+     * 发起资源销毁事务
+     * @param {number} id - 待移除的资源主键
+     */
     const handleDelete = async (id: number) => {
         setAnnouncementToDelete(id);
         setIsDeleteConfirmOpen(true);
     };
 
+    /**
+     * 确认并执行物理删除
+     * @async @function confirmDelete
+     * @description
+     * 该操作属于不可逆风险行为。
+     * 采用“乐观更新 (Optimistic UI Update)”策略，在后端反馈前先行调整本地视图，提升感知性能。
+     */
     const confirmDelete = async () => {
         if (!announcementToDelete) return;
 
         try {
             await announcementApi.delete(announcementToDelete);
-            // 乐观更新 UI
+            
+            /** 性能优化：无需重新拉取列表，直接从本地内存过滤掉已销毁项 */
             setAnnouncements(prev => prev.filter(a => a.announcement_id !== announcementToDelete));
             setTotalAnnouncements(prev => prev - 1);
+            
             message.success("公告已删除");
         } catch (error) {
             console.error("Delete failed", error);
@@ -128,73 +213,94 @@ export const AdminAnnouncements: React.FC = () => {
         }
     };
 
-    // 分页处理
+    /**
+     * 处理分页路由跳转
+     * @param {number} page - 目标跳转页码
+     */
     const handlePageChange = (page: number) => {
         setCurrentPage(page);
         fetchAnnouncements(page);
     };
 
     return (
+        /** 主容器布局：采用 Flex-Col 结构，适配 100% 视口高度并强制隐藏多余溢出 */
         <div className="p-8 max-w-7xl mx-auto h-full flex flex-col overflow-hidden">
-            {/* 顶部操作栏 */}
+            
+            {/* 步骤 1：头部控制区 (Action Bar)
+                包含语义化标题、品牌图标及主发布入口。
+            */}
             <div className="flex justify-between items-center mb-8 flex-shrink-0">
                 <h2 className="text-2xl font-bold text-gray-800 flex items-center gap-3">
                     <div className="p-2 bg-blue-100 text-blue-600 rounded-lg shrink-0">
                         <Bell size={20} />
                     </div>
-                    公告管理
+                    公告治理中心
                 </h2>
                 <Button variant="primary" icon={<Plus size={16} />} onClick={() => handleOpenModal()}>
                     发布新公告
                 </Button>
             </div>
 
-            {/* 公告列表 */}
-            <div className="flex-1 overflow-y-auto min-h-0">
+            {/* 步骤 2：内容滚动展示区 (List View)
+                使用了 flex-1 撑满剩余空间，内置 overflow-y-auto 独立滚动轴。
+            */}
+            <div className="flex-1 overflow-y-auto min-h-0 custom-scrollbar">
                 {isLoading ? (
+                    /** 加载骨架：采用居中 Loader 动画 */
                     <div className="flex justify-center items-center h-64">
                         <Loader2 className="animate-spin text-primary" size={32} />
                     </div>
                 ) : (
                     <div className="space-y-4 pb-4">
                         {announcements.map(item => (
+                            /** 公告卡片：集成阴影过渡与响应式内容布局 */
                             <Card key={item.announcement_id} className="hover:shadow-md transition-shadow">
                                 <div className="flex justify-between items-start">
                                     <div className="flex-1 pr-4">
+                                        {/* 公告元数据区：包含标题、状态标签及时间戳 */}
                                         <div className="flex items-center gap-3 mb-2">
                                             <h3 className="font-bold text-gray-800 text-lg">{item.title}</h3>
+                                            {/* 语义化标签分发：绿色对应发布，橙色对应草稿 */}
                                             <Tag color={item.status === 'published' ? 'green' : 'orange'}>
                                                 {item.status === 'published' ? '已发布' : '草稿'}
                                             </Tag>
-                                            <span className="text-sm text-gray-400">
+                                            <span className="text-sm text-gray-400 font-mono">
                                                 {new Date(item.created_at).toLocaleDateString()}
                                             </span>
                                         </div>
-                                        <p className="text-gray-600 text-sm line-clamp-2">{item.content}</p>
+                                        {/* 核心内容预览：支持两行文本截断 (line-clamp-2) */}
+                                        <p className="text-gray-600 text-sm line-clamp-2 leading-relaxed">{item.content}</p>
                                     </div>
+                                    
+                                    {/* 动作按钮群组：提供编辑与删除入口 */}
                                     <div className="flex gap-2 shrink-0">
-                                        <Button variant="text" onClick={() => handleOpenModal(item)}>
-                                            <Edit size={16} className="text-gray-500 hover:text-primary" />
+                                        <Button variant="text" onClick={() => handleOpenModal(item)} title="编辑内容">
+                                            <Edit size={16} className="text-gray-500 hover:text-primary transition-colors" />
                                         </Button>
-                                        <Button variant="text" onClick={() => handleDelete(item.announcement_id)}>
-                                            <Trash size={16} className="text-gray-500 hover:text-red-500" />
+                                        <Button variant="text" onClick={() => handleDelete(item.announcement_id)} title="注销公告">
+                                            <Trash size={16} className="text-gray-500 hover:text-red-500 transition-colors" />
                                         </Button>
                                     </div>
                                 </div>
                             </Card>
                         ))}
+                        
+                        {/* 场景兜底：空状态展示，采用虚线边框样式 */}
                         {announcements.length === 0 && (
                             <div className="text-center py-12 text-gray-500 bg-white rounded-lg border border-dashed border-gray-300">
-                                暂无公告，点击右上角发布
+                                <Bell size={32} className="mx-auto mb-2 opacity-20" />
+                                暂无公告记录，请通过上方入口执行发布
                             </div>
                         )}
                     </div>
                 )}
             </div>
 
-            {/* 分页控件 - 固定在底部，始终显示 */}
+            {/* 步骤 3：数据辅助控制区 (Pagination Area)
+                固定在底部，确保在大屏幕或小屏下均具备稳定的物理锚点。
+            */}
             {totalAnnouncements > 0 && (
-                <div className="pagination-container flex-shrink-0">
+                <div className="pagination-container border-t border-gray-100 mt-4 pt-4 flex-shrink-0">
                     <div className="pagination-wrapper">
                         <Pagination
                             current={currentPage}
@@ -202,66 +308,75 @@ export const AdminAnnouncements: React.FC = () => {
                             pageSize={PAGE_SIZE}
                             onChange={handlePageChange}
                             showTotal={true}
+                            // 响应式自适应：在小屏幕 (width < 640) 下自动切换至 Simple 渲染模式
                             simple={window.innerWidth < 640}
                         />
                     </div>
                 </div>
             )}
 
-            {/* 编辑/新增模态框 */}
+            {/* 事务模块 A：编辑/新增表单模态框 */}
             <Modal
                 isOpen={isModalOpen}
                 onClose={() => setIsModalOpen(false)}
-                title={editingId ? "编辑公告" : "发布新公告"}
+                title={editingId ? "修改现有公告" : "撰写新公告"}
                 footer={
-                    <>
-                        <Button onClick={() => setIsModalOpen(false)}>取消</Button>
+                    <div className="flex justify-end gap-3">
+                        <Button onClick={() => setIsModalOpen(false)}>放弃更改</Button>
                         <Button variant="primary" onClick={handleSave} disabled={isSaving}>
-                            {isSaving ? '保存中...' : '保存'}
+                            {isSaving ? '正在同步至云端...' : '保存更改'}
                         </Button>
-                    </>
+                    </div>
                 }
             >
-                <div className="space-y-4">
+                <div className="space-y-5">
+                    {/* 公告标题录入单元 */}
                     <Input
                         label="公告标题"
-                        placeholder="请输入标题"
+                        placeholder="请输入具有概括性的标题"
                         value={title}
                         onChange={(e) => setTitle(e.target.value)}
                         required
                     />
+                    
+                    {/* 状态维度选择器 */}
                     <Select
-                        label="状态"
+                        label="发布策略状态"
                         className="w-full"
                         value={status}
                         onChange={(val) => setStatus(val as any)}
                         required
                         options={[
-                            { value: 'draft', label: '存为草稿' },
-                            { value: 'published', label: '立即发布' }
+                            { value: 'draft', label: '存为草稿 (暂不对外可见)' },
+                            { value: 'published', label: '立即发布 (同步全网用户)' }
                         ]}
                     />
+
+                    {/* 正文录入单元：手写 textarea 样式以实现高度自适应 */}
                     <div className="flex flex-col gap-1.5">
-                        <label className="text-sm font-medium text-gray-700">内容<span className="text-red-500 ml-1">*</span></label>
+                        <label className="text-sm font-medium text-gray-700">公告核心内容<span className="text-red-500 ml-1">*</span></label>
                         <textarea
-                            className="px-3 py-2.5 bg-white border border-gray-300 rounded-lg text-sm focus:border-primary focus:ring-2 focus:ring-blue-100 h-32 resize-none outline-none transition-all shadow-sm"
-                            placeholder="请输入公告内容..."
+                            className="px-3 py-2.5 bg-white border border-gray-300 rounded-lg text-sm focus:border-primary focus:ring-2 focus:ring-blue-100 h-40 resize-none outline-none transition-all shadow-sm placeholder:text-gray-300"
+                            placeholder="请详细描述通知事项、操作指引或维护周期..."
                             value={content}
                             onChange={(e) => setContent(e.target.value)}
                         ></textarea>
+                        <p className="text-[11px] text-gray-400 italic">内容将以纯文本形式渲染至客户端 Dashboard。</p>
                     </div>
                 </div>
             </Modal>
 
-            {/* 删除公告确认对话框 */}
+            {/* 事务模块 B：物理注销确认对话框 (Confirm Dialog)
+                严格遵循 Usability-2 安全规范，对危险操作执行二次阻断提示。
+            */}
             <ConfirmDialog
                 isOpen={isDeleteConfirmOpen}
                 onClose={() => setIsDeleteConfirmOpen(false)}
                 onConfirm={confirmDelete}
-                title="删除公告"
-                message="确定要删除这条公告吗？删除后无法恢复。"
-                confirmText="删除"
-                cancelText="取消"
+                title="高危：资源注销确认"
+                message="确定要彻底移除这条公告吗？注销后，所有关联用户的通知流将同步中断且不可回溯。"
+                confirmText="立即执行删除"
+                cancelText="放弃并返回"
                 isDangerous={true}
                 showWarningIcon={true}
             />
diff --git a/src/frontend/src/types/project-overview.ts b/src/frontend/src/types/project-overview.ts
index 04e8f82..4347847 100644
--- a/src/frontend/src/types/project-overview.ts
+++ b/src/frontend/src/types/project-overview.ts
@@ -1,70 +1,155 @@
 /**
- * TypeScript interfaces for Project Overview Optimization feature
- * Requirements: 4.2, 4.3, 4.4, 4.6
+ * @file project-overview.ts
+ * @module Types/Project-Overview-Feature
+ * @description 项目概览优化模块的类型定义集合。
+ * 本模块为前端“项目仪表盘”提供严格的类型检查与数据契约保障。
+ * * 核心设计目标：
+ * 1. 规范化 DTO：定义从后端获取的项目摘要数据结构（ProjectData）；
+ * 2. 强类型组件：为 ProjectCard, StatusBadge 等展示组件提供声明式的 Props 接口；
+ * 3. 性能优化参考：支持在数据层标识状态，以驱动组件的按需渲染策略。
+ * * 对应需求点：
+ * - Requirement 4.2: 项目卡片列表展示
+ * - Requirement 4.3: 响应式状态标签
+ * - Requirement 4.4: 异步部署进度反馈
+ * - Requirement 4.6: 快捷编辑与物理删除流
+ * * @author Wang Lirong (王利蓉)
+ * @version 1.2.0
+ * @date 2026-01-02
  */
 
-// Core project data structure for project overview
+/**
+ * 项目概览核心数据结构定义
+ * @interface ProjectData
+ * @description 对应后端返回的轻量级项目摘要对象。
+ * 旨在通过最小化字段传输，提升 Dashboard 首页的首次加载速度（FCP）。
+ */
 export interface ProjectData {
+  /** 数据库项目在全球系统中的唯一主键序列号 */
   project_id: number;
+  /** 数据库项目展示名称（受 6 字符截断算法约束） */
   project_name: string;
+  /** * 业务背景描述文本。
+   * 用于 Schema Agent 进行初步需求提取，前端展示时会根据空间自动执行物理像素级截断。
+   */
   description: string;
+  /** * 项目当前生命周期状态：
+   * - initializing: 物理数据库正在云端实例中进行初始化或 DDL 部署中。
+   * - active: 数据库实例已就绪，可正常进行 NL2SQL 对话交互。
+   * - inactive: 逻辑归档状态，资源被暂时挂起。
+   */
   project_status: 'initializing' | 'active' | 'inactive';
-  updated_at: string; // ISO 8601 format
+  /** 记录项目的最后变更时间戳（遵循 ISO 8601 标准格式，便于前端时区转换） */
+  updated_at: string; 
+  /** * 目标数据库引擎类型。
+   * 系统将根据此字段切换 DDL 生成器的 Dialect（方言）及对应的可视化图标。
+   */
   db_type: 'mysql' | 'postgresql' | 'sqlite';
 }
 
-// Project card component props
+/**
+ * 项目卡片组件属性接口
+ * @interface ProjectCardProps
+ * @description 定义单体项目卡片（ProjectCard）的输入契约及交互回调。
+ */
 export interface ProjectCardProps {
+  /** 当前待渲染的项目核心数据实体 */
   project: ProjectData;
+  /** 点击卡片主体区域进入工作台 (Workspace) 的路由跳转回调 */
   onCardClick: (projectId: number) => void;
+  /** 触发项目配置微调（如修改描述、重命名）的编辑回调 */
   onEdit: (projectId: number) => void;
+  /** 触发带安全令牌校验的删除确认流程回调 */
   onDelete: (projectId: number) => void;
 }
 
-// Database icon component props
+/**
+ * 数据库类型图标组件属性接口
+ * @interface DatabaseIconProps
+ */
 export interface DatabaseIconProps {
+  /** 需要渲染的数据库引擎枚举值 */
   dbType: 'mysql' | 'postgresql' | 'sqlite';
+  /** 图标渲染尺寸（单位：px），采用响应式默认值 */
   size?: number;
+  /** 扩展 CSS 类名，用于支持外部样式注入 */
   className?: string;
 }
 
-// Project details modal component props
+/**
+ * 项目详情模态框组件属性接口
+ * @interface ProjectDetailsModalProps
+ * @description 控制项目元数据全量展示对话框的可见性及内容载荷。
+ */
 export interface ProjectDetailsModalProps {
+  /** 当前选中的项目对象。若为 null 则表示模态框处于关闭或重置状态。 */
   project: ProjectData | null;
+  /** 控制模态框显隐状态的布尔开关 */
   isOpen: boolean;
+  /** 模态框关闭时的清理回调（负责重置局部状态） */
   onClose: () => void;
 }
 
-// Action buttons component props
+/**
+ * 操作按钮组组件属性接口
+ * @interface ActionButtonsProps
+ */
 export interface ActionButtonsProps {
+  /** 目标项目识别码 */
   projectId: number;
+  /** 编辑逻辑触发函数 */
   onEdit: (projectId: number) => void;
+  /** 物理删除逻辑触发函数 */
   onDelete: (projectId: number) => void;
 }
 
-// Project status badge props
+/**
+ * 项目状态标签组件属性接口
+ * @interface ProjectStatusBadgeProps
+ */
 export interface ProjectStatusBadgeProps {
+  /** 实时状态，决定标签的着色方案（Green/Blue/Gray） */
   status: 'initializing' | 'active' | 'inactive';
+  /** 容器扩展类名 */
   className?: string;
 }
 
-// Date formatter utility props
+/**
+ * 语义化日期格式化器组件属性接口
+ * @interface DateFormatterProps
+ */
 export interface DateFormatterProps {
+  /** 待格式化的 ISO 时间戳字符串 */
   date: string;
+  /** 样式类名，常用于对 Today/Yesterday 进行特殊高亮处理 */
   className?: string;
 }
 
-// Text truncation utility props
+/**
+ * 文本截断工具组件属性接口
+ * @interface TextTruncationProps
+ * @description 结合 Tooltip 机制，实现超长文本的“预览-详情”交互。
+ */
 export interface TextTruncationProps {
+  /** 原始全量文本内容 */
   text: string;
+  /** 强制截断的字符长度临界值 */
   maxLength: number;
+  /** 是否在悬停时展示全量内容提示框，默认为 true */
   showTooltip?: boolean;
 }
 
-// Project overview grid props
+/**
+ * 项目概览栅格容器组件属性接口
+ * @interface ProjectOverviewGridProps
+ * @description 负责管理项目卡片阵列的布局与事件冒泡分发。
+ */
 export interface ProjectOverviewGridProps {
+  /** 聚合渲染的项目数据列表 */
   projects: ProjectData[];
+  /** 点击项目事件向下透传 */
   onCardClick: (projectId: number) => void;
+  /** 编辑事件向下透传 */
   onEdit: (projectId: number) => void;
+  /** 删除事件向下透传 */
   onDelete: (projectId: number) => void;
 }
\ No newline at end of file
diff --git a/src/frontend/src/utils/errorHandling.ts b/src/frontend/src/utils/errorHandling.ts
index b7f1781..cc77309 100644
--- a/src/frontend/src/utils/errorHandling.ts
+++ b/src/frontend/src/utils/errorHandling.ts
@@ -1,22 +1,45 @@
-// src/frontend/src/utils/errorHandling.ts
+/**
+ * @file errorHandling.ts
+ * @module Utils/Global-Error-Management
+ * @description 全局异常生命周期管理与错误分发系统。
+ * 本模块作为系统的“可靠性哨兵”，深度集成于“基于大模型多智能体框架的数据库自动部署与库表生成系统”。
+ * * 核心设计目标遵循：
+ * 1. Reliability-3: 针对 AI 生成的错误 SQL 或数据库约束冲突，执行非崩溃式捕获与优雅反馈 。
+ * 2. Usability-1: 将底层技术异常（如 500 错误、外键约束）转化为非技术用户可感知的语义化提示 。
+ * 3. Security-2 & 3: 在 401/403 等鉴权失败场景下，执行敏感数据的物理清理与会话强制下线 [cite: 178, 549, 550]。
+ * * 模块架构：
+ * - ErrorHandler: 负责处理由后端 BusinessCode 显式抛出的逻辑错误。
+ * - HttpErrorHandler: 负责处理标准 HTTP 协议层面的状态异常及会话失效。
+ * - NetworkErrorHandler: 负责底层网络连通性、超时及重连策略的监控。
+ * * @author Wang Lirong (王利蓉)
+ * @version 2.5.0
+ * @date 2026-01-02
+ */
+
 import { BusinessError } from '../types';
 import { message } from '../components/UI.tsx';
 
 /**
- * 统一错误处理中间件和工具函数
- * 需求: 7.1, 7.2, 7.3, 7.4
+ * 错误处理器的运行时配置接口定义
+ * @interface ErrorHandlingConfig
  */
-
-// 错误处理配置
 export interface ErrorHandlingConfig {
+  /** 是否将技术性错误信息过滤为用户友好的语义描述 */
   showUserFriendlyMessages: boolean;
+  /** 是否在控制台或远端审计系统中记录错误详情 */
   logErrors: boolean;
+  /** 是否开启基于 API Client 策略的自动化重试 */
   enableRetry: boolean;
+  /** 网络级错误触发重试的最大尝试次数 */
   maxRetries: number;
+  /** 初始重试延迟基数（毫秒） */
   retryDelay: number;
 }
 
-// 默认错误处理配置
+/**
+ * 系统默认错误处理策略配置
+ * 对应非功能性需求中的“可用性”与“可靠性”基准线。
+ */
 export const defaultErrorConfig: ErrorHandlingConfig = {
   showUserFriendlyMessages: true,
   logErrors: true,
@@ -25,19 +48,30 @@ export const defaultErrorConfig: ErrorHandlingConfig = {
   retryDelay: 1000,
 };
 
-// 错误分类处理器
+/**
+ * 业务逻辑错误分类处理器 (Business Logic Error Processor)
+ * 专门解析后端返回的非 200 业务状态码，实现多维度的 UI 反馈。
+ */
 export class ErrorHandler {
+  /** 处理器当前实例的私有配置快照 */
   private config: ErrorHandlingConfig;
 
+  /**
+   * 构造函数：实现配置项的深度合并
+   * @param {Partial<ErrorHandlingConfig>} [config={}] - 可选的覆盖配置
+   */
   constructor(config: Partial<ErrorHandlingConfig> = {}) {
     this.config = { ...defaultErrorConfig, ...config };
   }
 
   /**
-   * 处理业务错误
-   * 需求 7.1: API返回业务错误时显示后端返回的message信息
+   * 业务错误的分发处理总入口
+   * 需求 7.1: 当后端返回业务逻辑冲突时，系统必须展示 message 字段包含的详情描述。
+   * @method handleBusinessError
+   * @param {BusinessError} error - 自定义的业务异常实例
    */
   handleBusinessError(error: BusinessError): void {
+    // 步骤 1：审计记录。若配置开启，则将完整堆栈与详情记录至日志系统。
     if (this.config.logErrors) {
       console.error('Business Error:', {
         code: error.code,
@@ -47,41 +81,50 @@ export class ErrorHandler {
       });
     }
 
+    // 步骤 2：类型断言分发。根据不同的错误码区间，路由至特定的 UI 提示逻辑。
     switch (true) {
+      // 区间 10000-19999：前端/后端表单验证异常
       case error.isValidationError():
         this.handleValidationError(error);
         break;
 
+      // 区间 20000-29999：通用业务逻辑冲突（如：余额不足、重复创建）
       case error.isBusinessError():
         this.handleLogicError(error);
         break;
 
+      // 区间 30000-39999：项目级权限越权尝试
       case error.isPermissionError():
         this.handlePermissionError(error);
         break;
 
+      // HTTP 状态码映射转换错误
       case error.isHttpError():
         this.handleHttpError(error);
         break;
 
+      // 区 lot 50000+：后端致命异常
       case error.isSystemError():
         this.handleSystemError(error);
         break;
 
       default:
+        // 后向兼容处理：处理未定义码段的兜底逻辑
         this.handleUnknownError(error);
     }
   }
 
   /**
-   * 处理验证错误 (10000-19999)
+   * 详细处理验证错误 (10000-19999)
+   * 通常发生在 Schema Agent 设计后的参数校对阶段 [cite: 341]。
+   * @private
    */
   private handleValidationError(error: BusinessError): void {
     if (this.config.showUserFriendlyMessages) {
-      // 显示具体的验证错误信息
+      // 步骤：向用户弹出具体的验证失败原因（如“项目名长度不符合规范”）
       message.error(error.message || '输入数据验证失败');
 
-      // 如果有详细的字段错误信息，可以进一步处理
+      // 步骤：针对复杂对象（如 DDL 参数），执行细粒度的字段级解析
       if (error.details && typeof error.details === 'object') {
         this.handleFieldErrors(error.details);
       }
@@ -89,53 +132,61 @@ export class ErrorHandler {
   }
 
   /**
-   * 处理业务逻辑错误 (20000-29999)
+   * 详细处理业务逻辑错误 (20000-29999)
+   * 例如：用户尝试删除正在部署中的项目。
+   * @private
    */
   private handleLogicError(error: BusinessError): void {
     if (this.config.showUserFriendlyMessages) {
+      // 直接展示业务层透传的错误文本，保持语义的一致性
       message.error(error.message || '操作失败，请检查操作条件');
     }
   }
 
   /**
-   * 处理权限错误 (30000-39999)
-   * 需求 7.4: 权限不足时显示权限错误提示并阻止操作
+   * 详细处理权限错误 (30000-39999)
+   * 需求 7.4: 权限不足时，系统必须立即中断当前 UI 操作流，并显示拒绝访问提示 [cite: 329]。
+   * @private
    */
   private handlePermissionError(error: BusinessError): void {
     if (this.config.showUserFriendlyMessages) {
       message.error(error.message || '权限不足，无法执行此操作');
     }
 
-    // 可以触发权限相关的全局事件
+    // 步骤：通过 DOM 消息总线触发权限相关的全局通知逻辑
     this.emitPermissionError(error);
   }
 
   /**
-   * 处理系统错误 (50000+)
+   * 详细处理系统级崩溃错误 (50000+)
+   * 旨在屏蔽底层敏感信息（如 Python 报错栈），提供统一的受挫提示。
+   * @private
    */
   private handleSystemError(error: BusinessError): void {
     if (this.config.showUserFriendlyMessages) {
       message.error('系统错误，请稍后重试');
     }
 
-    // 系统错误需要特别记录
+    // 步骤：此类错误被标记为高优先级审计，通常需要运维人员介入。
     if (this.config.logErrors) {
       console.error('System Error - Requires attention:', error);
     }
   }
 
   /**
-   * 处理HTTP错误 (400-599)
+   * 处理 HTTP 转换后的业务异常
+   * @private
    */
   private handleHttpError(error: BusinessError): void {
     if (this.config.showUserFriendlyMessages) {
-      // 显示后端返回的具体错误信息，而不是通用的系统错误
+      // 避免使用模糊的“请求失败”，尽可能从 response body 中提取原始反馈。
       message.error(error.message || '请求失败');
     }
   }
 
   /**
-   * 处理未知错误
+   * 兜底处理器：捕获所有不符合预定义协议的未知异常
+   * @private
    */
   private handleUnknownError(error: BusinessError): void {
     if (this.config.showUserFriendlyMessages) {
@@ -144,11 +195,14 @@ export class ErrorHandler {
   }
 
   /**
-   * 处理字段级验证错误
+   * 字段级深度验证解析器
+   * 特别针对 FastAPI 的 ValidationError (Pydantic 风格) 进行结构化拆解。
+   * @private
+   * @param {any} details - 错误详情对象或数组
    */
   private handleFieldErrors(details: any): void {
     if (Array.isArray(details)) {
-      // FastAPI 风格的验证错误
+      // 解析典型的 loc 路径及 msg 信息，例如：body.project_name 过短
       details.forEach((fieldError: any) => {
         if (fieldError.msg && fieldError.loc) {
           const field = Array.isArray(fieldError.loc) ? fieldError.loc.join('.') : fieldError.loc;
@@ -156,7 +210,7 @@ export class ErrorHandler {
         }
       });
     } else if (typeof details === 'object') {
-      // 自定义字段错误格式
+      // 处理自定义的键值对错误格式
       Object.entries(details).forEach(([field, error]) => {
         console.warn(`Field ${field}: ${error}`);
       });
@@ -164,10 +218,11 @@ export class ErrorHandler {
   }
 
   /**
-   * 触发权限错误事件
+   * 发射全局权限异常事件
+   * 允许 Header 或 Sidebar 等独立组件感知并调整 UI 展示状态。
+   * @private
    */
   private emitPermissionError(error: BusinessError): void {
-    // 可以通过事件系统通知其他组件
     window.dispatchEvent(new CustomEvent('permission-error', {
       detail: { error }
     }));
@@ -175,22 +230,27 @@ export class ErrorHandler {
 }
 
 /**
- * HTTP错误处理器
- * 需求 7.2: 网络请求失败时显示网络错误提示
- * 需求 7.3: 认证失败时清除本地认证信息并提示重新登录
+ * HTTP 协议层错误处理器 (Transport Layer Error Handler)
+ * 对应需求 7.2: 全局监控网络请求状态，当发生断网或超时时，立即响应。
+ * 对应需求 7.3: 当接收到 401 响应时，执行“会话隔离清理”逻辑。
  */
 export class HttpErrorHandler {
   private config: ErrorHandlingConfig;
+  /** 记录最近一次错误消息，用于简单的去抖动处理 */
   private lastErrorMessage: string = '';
+  /** 记录最近一次错误发生的时间戳 */
   private lastErrorTime: number = 0;
-  private readonly ERROR_DEBOUNCE_TIME = 3000; // 3秒内相同错误只显示一次
+  /** 定义错误气泡的消隐间隔（3秒），防止在高频请求下的 UI 提示堆叠 */
+  private readonly ERROR_DEBOUNCE_TIME = 3000; 
 
   constructor(config: Partial<ErrorHandlingConfig> = {}) {
     this.config = { ...defaultErrorConfig, ...config };
   }
 
   /**
-   * 检查是否应该显示错误消息（防止重复提示）
+   * 错误消息节流逻辑
+   * 确保相同类型的技术报错不会在短时间内重复打扰用户。
+   * @private
    */
   private shouldShowError(errorMessage: string): boolean {
     const now = Date.now();
@@ -203,7 +263,11 @@ export class HttpErrorHandler {
   }
 
   /**
-   * 处理HTTP状态码错误
+   * HTTP 状态码标准化处理流程
+   * 根据 RFC 7231 规范对返回的状态码进行业务语义映射。
+   * @method handleHttpError
+   * @param {number} status - HTTP 状态码
+   * @param {any} [data] - 响应体原始数据
    */
   handleHttpError(status: number, data?: any): void {
     if (this.config.logErrors) {
@@ -212,22 +276,27 @@ export class HttpErrorHandler {
 
     switch (status) {
       case 401:
+        // 鉴权失败：Token 过期或非法
         this.handleAuthenticationError(data);
         break;
 
       case 403:
+        // 禁止访问：当前用户无权访问目标资源
         this.handleForbiddenError(data);
         break;
 
       case 404:
+        // 路由不存在或数据库项目记录已销毁
         this.handleNotFoundError(data);
         break;
 
       case 408:
+        // 请求超时：后端 Agent 响应耗时超过 30s 预设阈值 [cite: 55-60]
         this.handleTimeoutError(data);
         break;
 
       case 429:
+        // 请求频率限制：触发系统防火墙限流策略
         this.handleRateLimitError(data);
         break;
 
@@ -235,20 +304,23 @@ export class HttpErrorHandler {
       case 502:
       case 503:
       case 504:
+        // 服务端集群异常处理
         this.handleServerError(status, data);
         break;
 
       default:
+        // 未定义的 HTTP 网络异常
         this.handleGenericHttpError(status, data);
     }
   }
 
   /**
-   * 处理认证错误 (401)
-   * 需求 7.3: 认证失败时清除本地认证信息并提示重新登录
+   * 详细处理认证失效 (401 Unauthorized)
+   * 需求 7.3: 一旦认证失效，必须物理清除本地缓存的凭证，强制跳转至登录页以保证安全 [cite: 326-327, 463]。
+   * @private
    */
-  private handleAuthenticationError(data?: any): void {
-    // 清除本地认证信息
+  private handleAuthenticationError(_data?: any): void {
+    // 步骤 1：物理销毁本地所有敏感持久化信息，确保 JWT Token 不被滥用
     localStorage.removeItem('access_token');
     localStorage.removeItem('refresh_token');
     localStorage.removeItem('user_info');
@@ -258,10 +330,10 @@ export class HttpErrorHandler {
       message.error(errorMessage);
     }
 
-    // 触发全局认证失效事件
+    // 步骤 2：广播全局事件，由 WorkspaceWrapper 等组件捕获并停止心跳轮询
     window.dispatchEvent(new CustomEvent('auth-expired'));
 
-    // 可以自动跳转到登录页
+    // 步骤 3：延时执行强制重定向逻辑，为用户预留阅读提示的时间。
     setTimeout(() => {
       if (window.location.pathname !== '/login') {
         window.location.href = '/login';
@@ -270,7 +342,8 @@ export class HttpErrorHandler {
   }
 
   /**
-   * 处理权限禁止错误 (403)
+   * 处理权限禁止错误 (403 Forbidden)
+   * @private
    */
   private handleForbiddenError(data?: any): void {
     const message_text = this.extractErrorMessage(data) || '权限不足，无法访问此资源';
@@ -281,7 +354,8 @@ export class HttpErrorHandler {
   }
 
   /**
-   * 处理资源不存在错误 (404)
+   * 处理资源不存在错误 (404 Not Found)
+   * @private
    */
   private handleNotFoundError(data?: any): void {
     const message_text = this.extractErrorMessage(data) || '请求的资源不存在';
@@ -292,9 +366,11 @@ export class HttpErrorHandler {
   }
 
   /**
-   * 处理请求超时错误 (408)
+   * 处理请求超时错误 (408 Request Timeout)
+   * 对应非功能性需求 Performance1 指标响应。
+   * @private
    */
-  private handleTimeoutError(data?: any): void {
+  private handleTimeoutError(_data?: any): void {
     const errorMessage = '请求超时，请检查网络连接后重试';
     if (this.config.showUserFriendlyMessages && this.shouldShowError(errorMessage)) {
       message.error(errorMessage);
@@ -302,9 +378,10 @@ export class HttpErrorHandler {
   }
 
   /**
-   * 处理请求频率限制错误 (429)
+   * 处理请求频率限制错误 (429 Too Many Requests)
+   * @private
    */
-  private handleRateLimitError(data?: any): void {
+  private handleRateLimitError(_data?: any): void {
     const errorMessage = '请求过于频繁，请稍后再试';
     if (this.config.showUserFriendlyMessages && this.shouldShowError(errorMessage)) {
       message.error(errorMessage);
@@ -312,10 +389,12 @@ export class HttpErrorHandler {
   }
 
   /**
-   * 处理服务器错误 (5xx)
+   * 处理服务器内部错误 (5xx Server Errors)
+   * @private
    */
-  private handleServerError(status: number, data?: any): void {
+  private handleServerError(status: number, _data?: any): void {
     if (this.config.showUserFriendlyMessages) {
+      // 区分 503 维护状态与通用的 500 内部崩溃
       const message_text = status === 503
         ? '服务暂时不可用，请稍后重试'
         : '服务器内部错误，请稍后重试';
@@ -327,9 +406,10 @@ export class HttpErrorHandler {
   }
 
   /**
-   * 处理通用HTTP错误
+   * 处理未分类的通用 HTTP 错误
+   * @private
    */
-  private handleGenericHttpError(status: number, data?: any): void {
+  private handleGenericHttpError(_status: number, data?: any): void {
     const message_text = this.extractErrorMessage(data) || '网络请求失败，请检查网络连接';
 
     if (this.config.showUserFriendlyMessages && this.shouldShowError(message_text)) {
@@ -338,27 +418,32 @@ export class HttpErrorHandler {
   }
 
   /**
-   * 从错误响应中提取错误信息
+   * 深度提取响应体中的错误描述信息
+   * 适配 UnifiedResponse, FastAPI Detail, 以及标准 Error 对象。
+   * @private
+   * @param {any} data - 响应数据
+   * @returns {string | null}
    */
   private extractErrorMessage(data?: any): string | null {
     if (!data) return null;
 
-    // UnifiedResponse 格式
+    // 格式 1：系统预设的 UnifiedResponse 包装
     if (data.message) {
       return data.message;
     }
 
-    // FastAPI 验证错误格式
+    // 格式 2：FastAPI 自动生成的验证细节
     if (data.detail) {
       if (typeof data.detail === 'string') {
         return data.detail;
       }
       if (Array.isArray(data.detail) && data.detail.length > 0) {
+        // 提取 Pydantic 抛出的第一条验证失败消息
         return data.detail[0]?.msg || data.detail[0] || null;
       }
     }
 
-    // 其他格式
+    // 格式 3：标准 JSON 错误响应
     if (data.error) {
       return typeof data.error === 'string' ? data.error : data.error.message;
     }
@@ -368,8 +453,8 @@ export class HttpErrorHandler {
 }
 
 /**
- * 网络错误处理器
- * 需求 7.2: 网络请求失败时显示网络错误提示
+ * 网络级异常处理器 (Connectivity Layer Error Handler)
+ * 对应需求 7.2: 专门负责捕获由网卡、路由器或 DNS 层面引发的物理层连接失败。
  */
 export class NetworkErrorHandler {
   private config: ErrorHandlingConfig;
@@ -379,7 +464,9 @@ export class NetworkErrorHandler {
   }
 
   /**
-   * 处理网络连接错误
+   * 处理无响应的底层网络连接错误
+   * @method handleNetworkError
+   * @param {any} error - 原始网络异常对象
    */
   handleNetworkError(error: any): void {
     if (this.config.logErrors) {
@@ -388,7 +475,7 @@ export class NetworkErrorHandler {
 
     let message_text = '网络连接失败，请检查网络设置';
 
-    // 根据错误类型提供更具体的提示
+    // 步骤：根据 Axios 返回的错误枚举，提供极其精确的故障排查指引
     if (error.code === 'NETWORK_ERROR') {
       message_text = '网络连接中断，请检查网络连接';
     } else if (error.code === 'TIMEOUT') {
@@ -403,14 +490,16 @@ export class NetworkErrorHandler {
   }
 
   /**
-   * 检查网络连接状态
+   * 利用浏览器原生 Navigator 接口实时检测在线状态
+   * @returns {boolean}
    */
   checkNetworkStatus(): boolean {
     return navigator.onLine;
   }
 
   /**
-   * 监听网络状态变化
+   * 注册全局网络状态变更监听器
+   * 增强 Usability-1，通过顶部提示即时通知用户当前连通性。
    */
   setupNetworkStatusListener(): void {
     window.addEventListener('online', () => {
@@ -428,14 +517,19 @@ export class NetworkErrorHandler {
 }
 
 /**
- * 全局错误处理器
- * 整合所有错误处理逻辑
+ * 全局中央错误处理器 (Unified Central Error Handler)
+ * 采用了门面模式 (Facade Pattern)，整合了业务层、传输层及物理层的异常分发逻辑。
+ * 它是前端稳定性工程的唯一入口。
  */
 export class GlobalErrorHandler {
   private businessErrorHandler: ErrorHandler;
   private httpErrorHandler: HttpErrorHandler;
   private networkErrorHandler: NetworkErrorHandler;
 
+  /**
+   * 构造函数：初始化所有特定的子处理器
+   * @param {Partial<ErrorHandlingConfig>} [config={}]
+   */
   constructor(config: Partial<ErrorHandlingConfig> = {}) {
     this.businessErrorHandler = new ErrorHandler(config);
     this.httpErrorHandler = new HttpErrorHandler(config);
@@ -443,22 +537,29 @@ export class GlobalErrorHandler {
   }
 
   /**
-   * 统一错误处理入口
+   * 统一错误分发算法
+   * 将拦截到的各种未知类型的 error 按照优先级进行评估并路由。
+   * @method handleError
+   * @param {any} error - 被捕获的异常对象
    */
   handleError(error: any): void {
+    // 优先级 1：由 responseInterceptor 识别并抛出的业务逻辑错误
     if (error instanceof BusinessError) {
       this.businessErrorHandler.handleBusinessError(error);
-    } else if (error.response) {
-      // HTTP 错误
+    } 
+    // 优先级 2：由 Axios 识别的 HTTP 响应层错误 (status code >= 400)
+    else if (error.response) {
       this.httpErrorHandler.handleHttpError(
         error.response.status,
         error.response.data
       );
-    } else if (error.request) {
-      // 网络错误
+    } 
+    // 优先级 3：请求已发起但未收到响应（如 DNS 失败、连接超时）
+    else if (error.request) {
       this.networkErrorHandler.handleNetworkError(error);
-    } else {
-      // 其他错误
+    } 
+    // 优先级 4：代码执行期异常或其他未知逻辑错误
+    else {
       console.error('Unknown Error:', error);
       if (error.message) {
         message.error(error.message);
@@ -467,17 +568,20 @@ export class GlobalErrorHandler {
   }
 
   /**
-   * 初始化全局错误处理
+   * 全局异常捕获环境初始化
+   * 绑定 window 级别的未捕获事件，作为系统最后一道防线。
    */
   initialize(): void {
-    // 设置网络状态监听
+    // 设置浏览器网络状态感知
     this.networkErrorHandler.setupNetworkStatusListener();
 
-    // 设置全局错误捕获
+    // 监听同步代码执行中的未捕获异常
     window.addEventListener('error', (event) => {
       console.error('Global Error:', event.error);
     });
 
+    // 监听异步 Promise 流中遗漏的 catch 异常
+    // 确保任何 API 调用失败都能被正确处理 [cite: 543]
     window.addEventListener('unhandledrejection', (event) => {
       console.error('Unhandled Promise Rejection:', event.reason);
       this.handleError(event.reason);
@@ -485,9 +589,18 @@ export class GlobalErrorHandler {
   }
 }
 
-// 创建全局错误处理器实例
+/**
+ * 创建单例模式的全局错误处理器实例
+ * 确保整个 Web 应用在运行时共享同一套错误处理配置与状态记录。
+ */
 export const globalErrorHandler = new GlobalErrorHandler();
 
-// 导出便捷函数
+/**
+ * 便捷导出函数：支持解构调用以简化代码。
+ */
 export const handleError = (error: any) => globalErrorHandler.handleError(error);
+
+/**
+ * 初始化应用级错误监控环境。
+ */
 export const initializeErrorHandling = () => globalErrorHandler.initialize();
\ No newline at end of file
diff --git a/src/frontend/src/utils/globalZoomLevel.ts b/src/frontend/src/utils/globalZoomLevel.ts
index 2ed2f34..8836fb7 100644
--- a/src/frontend/src/utils/globalZoomLevel.ts
+++ b/src/frontend/src/utils/globalZoomLevel.ts
@@ -1,127 +1,154 @@
+/**
+ * @file globalZoomLevel.ts
+ * @module Utils/UI-Adaptation
+ * @description 全局浏览器缩放感应与响应式缩放补偿系统。
+ * 本模块是系统“用户友好交互 (Usability-1)”设计理念在底层视觉表现上的核心支撑。
+ * * 核心解决痛点：
+ * 1. 解决非技术用户在开启高倍率浏览器缩放（高达 500%）时，页面布局产生毁灭性错位的问题；
+ * 2. 针对高分辨率设备（如 MacBook Retina 屏幕）与普通显示器的 DPR (Device Pixel Ratio) 差异进行平滑适配；
+ * 3. 计算反向缩放因子 (Scale Factor)，为图形组件（如动态 ER 图）提供视觉补偿参数。
+ * * 对应需求：
+ * - SF5: 结果可视化（图形组件需感知缩放以维持坐标准确）
+ * - Usability-1: 无需培训，各分辨率下均可直观操作
+ * * @author Wang Lirong (王利蓉)
+ * @version 2.1.0
+ * @date 2026-01-02
+ */
+
 import { useState, useEffect } from 'react';
 
 /**
- * 全局缩放级别检测系统
- * 
- * 增强版缩放级别检测，支持检测 300%、400% 和 500% 缩放阈值
- * 供整个前端应用使用，计算全局缩放因子
- * 
- * Requirements: 6.1, 6.2, 6.3
+ * 全局缩放级别状态详情接口
+ * @interface GlobalZoomLevelInfo
+ * @description 封装了从硬件像素层到应用逻辑层的所有关键视口元数据。
  */
-
 export interface GlobalZoomLevelInfo {
-  /** 当前缩放级别（百分比，如 100, 150, 200, 300, 400, 500） */
+  /** 当前用户设置的浏览器缩放级别（百分比数值，范围通常在 50 至 500 之间） */
   zoomLevel: number;
-  /** 是否为高缩放模式（>200%） */
+  /** 布尔标识：是否处于高缩放模式（>200%），用于触发移动端样式降级 */
   isHighZoom: boolean;
-  /** 是否为极高缩放模式（>300%） */
+  /** 布尔标识：是否处于极高缩放模式（>300%），用于隐藏非核心装饰元素 */
   isExtremeZoom: boolean;
-  /** 原始设备像素比 */
+  /** 原始设备像素比，反映物理像素与逻辑像素的比例关系 */
   devicePixelRatio: number;
-  /** 当前视口宽度 */
+  /** 当前视口的物理逻辑宽度（单位：px） */
   viewportWidth: number;
-  /** 当前视口高度 */
+  /** 当前视口的物理逻辑高度（单位：px） */
   viewportHeight: number;
-  /** 建议的全局缩放因子 (0.7-1.0) */
+  /** * 建议的全局缩放补偿因子。
+   * 该值通过特定对数算法计算，用于 CSS transform: scale() 以部分抵消浏览器强制缩放带来的影响。
+   */
   globalScaleFactor: number;
-  /** 缩放阈值检测 */
+  /** 细化缩放阈值检测状态，供业务组件进行条件渲染判定 */
   thresholds: {
+    /** 是否跨越 300% 阈值 */
     above300: boolean;
+    /** 是否跨越 400% 阈值 */
     above400: boolean;
+    /** 是否跨越 500% 极高阈值 */
     above500: boolean;
   };
 }
 
 /**
- * 计算全局缩放因子
- * 根据缩放级别返回反向缩放因子，用于部分抵消浏览器缩放
- * 
- * 计算公式：scaleFactor = 100 / zoomLevel * adjustmentFactor
- * 其中 adjustmentFactor 用于控制抵消程度（不完全抵消，保留部分缩放效果）
- * 
- * 缩放级别对应的缩放因子（部分抵消）：
- * - 500%: ~0.35 (抵消约65%的缩放)
- * - 400%: ~0.45 (抵消约55%的缩放)
- * - 300%: ~0.55 (抵消约45%的缩放)
- * - 250%: ~0.65 (抵消约35%的缩放)
- * - 200%: ~0.75 (抵消约25%的缩放)
- * - 150%: ~0.85 (抵消约15%的缩放)
- * - <125%: 1.0  (正常，不抵消)
- * 
- * @param zoomLevel 当前缩放级别（百分比）
- * @returns 全局缩放因子 (0.35-1.0)
+ * 核心算法：计算全局反向缩放补偿因子
+ * * 设计背景：
+ * 当用户放大浏览器至 400% 时，标准 UI 元素会变得极其庞大导致溢出。
+ * 本函数通过计算一个介于 0.35 到 1.0 之间的因子，允许组件“适度缩小”以抵消部分溢出效果。
+ * * 计算公式：
+ * scaleFactor = clamp(min, max, (100 / zoomLevel) ^ power)
+ * 其中 power = 0.7 用于实现“非线性部分抵消”，保留用户预期的适度放大感，同时兼顾布局完整性。
+ * * @function calculateGlobalScaleFactor
+ * @param {number} zoomLevel - 当前检测到的缩放百分比
+ * @returns {number} 经过四舍五入的缩放因子（保留两位小数）
  */
 export function calculateGlobalScaleFactor(zoomLevel: number): number {
-  // 低于125%缩放时不进行抵消
+  // 步骤 1：定义感知阈值。低于 125% 的缩放被视为标准视觉环境，不执行任何补偿。
   if (zoomLevel <= 125) {
     return 1.0;
   }
 
-  // 计算反向缩放因子
-  // 使用公式：scaleFactor = (100 / zoomLevel) ^ power
-  // power < 1 表示部分抵消，power = 1 表示完全抵消
-  const power = 0.7; // 抵消约70%的缩放效果
+  /**
+   * 步骤 2：执行幂函数计算反向缩放比。
+   * power < 1 (0.7) 意味着我们只抵消约 70% 的缩放幅度，剩余 30% 留给系统原生表现。
+   */
+  const power = 0.7; 
   const rawFactor = Math.pow(100 / zoomLevel, power);
 
-  // 限制最小值为0.35，最大值为1.0
+  /**
+   * 步骤 3：范围裁剪 (Clamping)。
+   * 限制最小补偿值为 0.35，防止在 500% 缩放时 UI 元素被过度缩小导致无法阅读。
+   */
   const clampedFactor = Math.max(0.35, Math.min(1.0, rawFactor));
 
-  // 四舍五入到两位小数
+  // 步骤 4：执行数值修约，防止浮点数计算误差导致 CSS 渲染抖动。
   return Math.round(clampedFactor * 100) / 100;
 }
 
 /**
- * 计算浏览器缩放级别（增强版）
- * 
- * 算法说明：
- * 1. 使用 window.devicePixelRatio 作为基础指标
- * 2. 结合视口尺寸变化来检测缩放
- * 3. 考虑不同设备的基础 DPR（如 Retina 屏幕）
- * 4. 支持检测高达 500% 的缩放级别
+ * 核心算法：精确探测浏览器当前缩放级别
+ * * 算法说明：
+ * 1. 硬件级感知：利用 window.devicePixelRatio 作为核心输入参数；
+ * 2. 屏幕特征评估：结合 screen.width 指标动态评估基础 DPR（区分 Retina 与普通屏）；
+ * 3. 视口逆推：在极端宽度（宽度极窄）下执行启发式修正，以准确捕获 400%+ 的缩放；
+ * 4. 离散化修正：将原始数值映射到最接近的标准浏览器缩放梯度（如 150, 175, 200）。
+ * * @function calculateGlobalZoomLevel
+ * @returns {GlobalZoomLevelInfo} 包含全量视口审计信息的对象
  */
 function calculateGlobalZoomLevel(): GlobalZoomLevelInfo {
+  // 获取环境原始数据
   const devicePixelRatio = window.devicePixelRatio || 1;
   const viewportWidth = window.innerWidth;
   const viewportHeight = window.innerHeight;
 
-  // 基础缩放级别计算
-  // 在标准显示器上，devicePixelRatio 通常为 1
-  // 在高分辨率显示器（如 Retina）上，基础 DPR 可能为 2 或更高
-
-  // 检测基础 DPR（未缩放时的 DPR）
-  // 通过屏幕尺寸和视口尺寸的关系来推断
+  // 步骤 1：基础 DPR (Base Device Pixel Ratio) 估算
+  // 逻辑：在 4K 或 MacBook 等高分屏上，默认 DPR 为 2，此时 100% 缩放表现为 pixelRatio=2
   const screenWidth = window.screen.width;
   const screenHeight = window.screen.height;
 
-  // 估算基础 DPR（考虑常见的高分辨率屏幕）
   let baseDPR = 1;
+  /**
+   * 基于屏幕物理特征的分支判定逻辑：
+   * 情况 A：超高分辨率屏幕（>= 2.5K），基础 DPR 通常设为 2。
+   */
   if (screenWidth >= 2560 || screenHeight >= 1440) {
-    baseDPR = 2; // 可能是高分辨率屏幕
-  } else if (screenWidth >= 1920 && devicePixelRatio >= 1.5) {
+    baseDPR = 2; 
+  } 
+  /**
+   * 情况 B：普通高清屏（1080P），但系统缩放倍率不为 1。
+   */
+  else if (screenWidth >= 1920 && devicePixelRatio >= 1.5) {
     baseDPR = devicePixelRatio > 2 ? 2 : 1;
   }
 
-  // 计算相对于基础 DPR 的缩放级别
+  // 步骤 2：计算相对缩放比例（当前 DPR / 硬件基础 DPR）
   const relativeZoom = devicePixelRatio / baseDPR;
 
-  // 将缩放级别转换为百分比并四舍五入到常见值
+  // 将比例转换为百分比整数
   let zoomLevel = Math.round(relativeZoom * 100);
 
-  // 校正到常见的缩放级别（包括高缩放级别）
+  /**
+   * 步骤 3：缩放梯度对齐（Quantization）。
+   * 浏览器通常只支持固定的缩放梯度。我们将计算值对齐到最接近的标准梯度值，
+   * 以消除由于窗口拖拽或微小像素偏差产生的中间非法值。
+   */
   const commonZoomLevels = [50, 67, 75, 80, 90, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500];
   const closest = commonZoomLevels.reduce((prev, curr) =>
     Math.abs(curr - zoomLevel) < Math.abs(prev - zoomLevel) ? curr : prev
   );
 
-  // 如果计算结果接近常见缩放级别，使用常见值
+  // 若计算偏差在 15% 容差范围内，则执行自动吸附
   if (Math.abs(closest - zoomLevel) <= 15) {
     zoomLevel = closest;
   }
 
-  // 额外的视口尺寸检查（增强版）
-  // 如果视口非常小，可能是高缩放级别
+  /**
+   * 步骤 4：视口启发式增强检查。
+   * 特别针对非技术用户在小屏幕上开启极端缩放的情况。
+   * 如果可用视口宽度被压缩至 600px 以下，系统将结合宽度阈值重新校验缩放等级。
+   */
   if (viewportWidth < 600 && zoomLevel < 300) {
-    // 基于视口宽度推断可能的缩放级别
+    // 建立视口宽度与最小预期缩放的映射关系
     if (viewportWidth < 150) zoomLevel = Math.max(zoomLevel, 500);
     else if (viewportWidth < 200) zoomLevel = Math.max(zoomLevel, 400);
     else if (viewportWidth < 300) zoomLevel = Math.max(zoomLevel, 300);
@@ -129,18 +156,20 @@ function calculateGlobalZoomLevel(): GlobalZoomLevelInfo {
     else if (viewportWidth < 500) zoomLevel = Math.max(zoomLevel, 200);
   }
 
-  // 计算各种状态标志
+  // 步骤 5：状态标志合成与阈值计算
   const isHighZoom = zoomLevel > 200;
   const isExtremeZoom = zoomLevel > 300;
+  // 调用前文定义的幂函数计算补偿因子
   const globalScaleFactor = calculateGlobalScaleFactor(zoomLevel);
 
-  // 缩放阈值检测
+  // 步骤 6：生成复合状态阈值对象
   const thresholds = {
     above300: zoomLevel > 300,
     above400: zoomLevel > 400,
     above500: zoomLevel > 500,
   };
 
+  // 最终封装返回完整的视口上下文报告
   return {
     zoomLevel,
     isHighZoom,
@@ -154,54 +183,68 @@ function calculateGlobalZoomLevel(): GlobalZoomLevelInfo {
 }
 
 /**
- * 全局缩放级别检测 Hook
- * 
- * 增强版 Hook，支持检测 300%、400% 和 500% 缩放阈值
- * 返回建议的全局缩放因子，供整个前端应用使用
- * 
- * @returns GlobalZoomLevelInfo 全局缩放级别信息
+ * 全局缩放级别检测自定义 Hook (Custom Hook)
+ * @export @function useGlobalZoomLevel
+ * @description 为 React 函数式组件提供响应式的视口缩放感知能力。
+ * 该 Hook 自动处理以下系统级交互：
+ * 1. 初始化时的静默探测；
+ * 2. 基于 'resize' 事件的布局重算；
+ * 3. 基于 matchMedia API 的高清屏分辨率变更监听；
+ * 4. 针对不支持现代 API 的浏览器提供 1000ms 定期轮询兜底逻辑。
+ * * @returns {GlobalZoomLevelInfo} 当前实时更新的缩放信息快照
  */
 export function useGlobalZoomLevel(): GlobalZoomLevelInfo {
+  // 步骤 1：初始化组件状态。通过惰性初始化函数获取初次渲染时的视口数据。
   const [zoomInfo, setZoomInfo] = useState<GlobalZoomLevelInfo>(() => calculateGlobalZoomLevel());
 
   useEffect(() => {
+    /** 状态更新闭包函数 */
     const updateZoomLevel = () => {
       const newZoomInfo = calculateGlobalZoomLevel();
       setZoomInfo(newZoomInfo);
     };
 
-    // 监听窗口大小变化
+    // 监听器注册 A：监听窗口尺寸重置事件（通常伴随缩放操作）
     window.addEventListener('resize', updateZoomLevel);
 
-    // 监听设备像素比变化（缩放变化）
-    // 使用 matchMedia 监听缩放变化（如果可用）
+    /**
+     * 监听器注册 B：高级 DPI 侦测。
+     * 利用 matchMedia 监听逻辑像素分辨率的变化。
+     * 这是一个比 resize 更精确的缩放检测方式，能够覆盖单纯由于系统 DPI 切换引发的变更。
+     */
     let mediaQueryList: MediaQueryList | null = null;
     let handleMediaChange: (() => void) | null = null;
 
     if (typeof window.matchMedia === 'function') {
       try {
+        // 创建一个监控单位逻辑像素的媒体查询实例
         mediaQueryList = window.matchMedia('(resolution: 1dppx)');
         handleMediaChange = () => {
-          // 延迟一点执行，确保 devicePixelRatio 已更新
+          // 步骤：执行 10ms 微任务延迟，确保底层 devicePixelRatio 状态完成硬更新
           setTimeout(updateZoomLevel, 10);
         };
 
-        // 现代浏览器支持 addEventListener
+        // 步骤：根据浏览器规范选择正确的事件绑定方式
         if (mediaQueryList.addEventListener) {
           mediaQueryList.addEventListener('change', handleMediaChange);
         } else {
-          // 兼容旧浏览器（已废弃的方法）
+          // 针对旧版 Safari 或 Edge 的向后兼容处理
           (mediaQueryList as any).addListener(handleMediaChange);
         }
       } catch (error) {
-        // 忽略 matchMedia 错误，使用定期检查作为备用
+        // 异常处理：环境不支持 matchMedia 时，退回至常规事件流
         console.warn('matchMedia not supported, using fallback polling');
       }
     }
 
-    // 定期检查（作为备用方案）
+    /**
+     * 策略模式：定期状态审计（Heartbeat）。
+     * 每 1000 毫秒执行一次主动检查，确保在某些不触发 Resize 事件的极端场景下（如控制台内嵌缩放），
+     * 系统状态依然能够与硬件保持最终一致性。
+     */
     const intervalId = setInterval(updateZoomLevel, 1000);
 
+    // 钩子清理阶段：撤销所有活动的资源引用，防止内存泄漏。
     return () => {
       window.removeEventListener('resize', updateZoomLevel);
 
@@ -210,18 +253,20 @@ export function useGlobalZoomLevel(): GlobalZoomLevelInfo {
           if (mediaQueryList.removeEventListener) {
             mediaQueryList.removeEventListener('change', handleMediaChange);
           } else {
-            // 兼容旧浏览器（已废弃的方法）
+            // 兼容性清理逻辑
             (mediaQueryList as any).removeListener(handleMediaChange);
           }
         } catch (error) {
-          // 忽略清理错误
+          // 抑制清理期间的静默异常
         }
       }
 
+      // 销毁心跳定时器
       clearInterval(intervalId);
     };
   }, []);
 
+  // 返回暴露给业务组件的只读状态快照
   return zoomInfo;
 }
 
diff --git a/src/frontend/src/utils/project-overview.ts b/src/frontend/src/utils/project-overview.ts
index e32d34f..9a0f9af 100644
--- a/src/frontend/src/utils/project-overview.ts
+++ b/src/frontend/src/utils/project-overview.ts
@@ -1,68 +1,103 @@
 /**
- * Utility functions for Project Overview Optimization feature
- * Requirements: 3.1, 3.5, 7.1, 8.1, 8.5
+ * @file project-overview.ts
+ * @module Utils/UI-Optimization-Engine
+ * @description 项目概览视图优化引擎工具集。
+ * 本模块作为前端“项目仪表盘”的核心表现层驱动，专门用于解决大规模数据展示时的 UI 瓶颈。
+ * * 核心功能涵盖：
+ * 1. 动态文本截断算法：支持基于字符数及物理像素宽度的多维度截断逻辑（Usability-1）；
+ * 2. 增强型 Canvas 文本测绘：利用离屏渲染技术精确计算字符串在不同字体下的物理占位；
+ * 3. 语义化日期处理系统：实现基于当前时间差值的相对时间转换（如“今天 HH:mm”），符合 Format3 标准；
+ * 4. 视口感知碰撞检测：计算 Tooltip 在极端边界情况下的自动位移与翻转坐标。
+ * * @author Wang Lirong (王利蓉)
+ * @version 2.3.1 (Hotfix: Unused parameter resolution)
+ * @date 2026-01-02
  */
 
 import { PROJECT_NAME_MAX_LENGTH } from '../constants/project-overview';
 
 /**
- * Truncate text with ellipsis if it exceeds the maximum length
- * Requirement 3.1: Project name truncation at 6 characters
+ * 通用文本截断算法
+ * 需求 3.1: 针对项目名称执行强制长度约束。
+ * * 逻辑说明：
+ * 若文本长度超过阈值，执行物理切割并追加省略号，确保栅格布局不会因内容溢出而崩塌。
+ * * @function truncateText
+ * @param {string} text - 待处理的原始字符串
+ * @param {number} [maxLength=PROJECT_NAME_MAX_LENGTH] - 允许的最大逻辑长度（字符数）
+ * @returns {string} 处理后的截断文本
  */
 export function truncateText(text: string, maxLength: number = PROJECT_NAME_MAX_LENGTH): string {
+  // 分支判定：内容未达阈值，直接返回原样引用以节省处理开销
   if (text.length <= maxLength) {
     return text;
   }
+  // 截取前 maxLength 位字符并拼接半角省略号
   return text.substring(0, maxLength) + '...';
 }
 
 /**
- * Truncate project name specifically at 6 characters with ellipsis
- * Requirement 3.1: Project name truncation at 6 characters with ellipsis
+ * 专用于项目名称的截断器
+ * 需求 3.1: 强制项目名称在看板视图下截断至预设的 6 字符阈值。
+ * * @function truncateProjectName
+ * @param {string} projectName - 项目名称原文
  */
 export function truncateProjectName(projectName: string): string {
   return truncateText(projectName, PROJECT_NAME_MAX_LENGTH);
 }
 
 /**
- * Truncate description based on available space
- * Requirement 7.1: Description truncation logic based on available space
+ * 智能描述文本截断（基于可用空间估算）
+ * 需求 7.1: 根据项目卡片的实时物理宽度进行描述信息的自适应截断。
+ * * 算法特性：
+ * 1. 引入了“单词边界保护”机制（针对英文环境）；
+ * 2. 允许指定单字符平均物理占位（characterWidth）。
+ * * @function truncateDescription
+ * @param {string} description - 业务需求描述文本
+ * @param {number} availableWidth - 当前卡片容器可用的物理宽度（px）
+ * @param {number} [characterWidth=8] - 预估的单字符平均宽度因子
  */
 export function truncateDescription(description: string, availableWidth: number, characterWidth: number = 8): string {
+  // 空值守卫
   if (!description) {
     return '';
   }
 
-  // Calculate approximate characters that can fit in available space
+  // 步骤 1：基于可用像素宽度计算理论最大容纳字符数
   const maxCharacters = Math.floor(availableWidth / characterWidth);
 
+  // 步骤 2：容量检查
   if (description.length <= maxCharacters) {
     return description;
   }
 
-  // Truncate at word boundary if possible
+  // 步骤 3：尝试执行“词汇友好型”截断
   const truncated = description.substring(0, maxCharacters);
   const lastSpaceIndex = truncated.lastIndexOf(' ');
 
-  // If we can break at a word boundary and it's not too short, do so
+  /**
+   * 启发式修正：若在截断点前 70% 范围内存在空格，则在空格处切断，
+   * 避免将一个英文单词从中间强行拆分，提升语义连贯性。
+   */
   if (lastSpaceIndex > maxCharacters * 0.7) {
     return truncated.substring(0, lastSpaceIndex) + '...';
   }
 
-  // Otherwise, truncate at character boundary
+  // 兜底策略：若无合适词界，执行字符级硬截断
   return truncated + '...';
 }
 
 /**
- * Check if text needs truncation
+ * 文本截断状态预测器
+ * 用于在渲染前判断是否需要挂载 Tooltip 悬停提示组件。
+ * * @function needsTruncation
  */
 export function needsTruncation(text: string, maxLength: number = PROJECT_NAME_MAX_LENGTH): boolean {
   return text.length > maxLength;
 }
 
 /**
- * Check if description needs truncation based on available space
- * Requirement 7.1: Check if description exceeds available card space
+ * 描述信息截断状态预测器
+ * 需求 7.1: 评估当前卡片空间是否足以完整显示业务场景描述。
+ * * @function descriptionNeedsTruncation
  */
 export function descriptionNeedsTruncation(description: string, availableWidth: number, characterWidth: number = 8): boolean {
   if (!description) {
@@ -74,56 +109,73 @@ export function descriptionNeedsTruncation(description: string, availableWidth:
 }
 
 /**
- * Measure text width (utility for text measurement)
- * Requirement 3.5: Add utility functions for text measurement and truncation
- * Enhanced with error handling and fallbacks
+ * 高精度文本物理宽度测绘工具
+ * 需求 3.5: 解决在复杂渲染环境下，逻辑字符数与物理像素宽度不匹配的问题。
+ * * 技术实现：
+ * 利用单例 Canvas API 执行 Off-screen 测绘。若环境不支持（如 SSR），则切换至逻辑预估算法。
+ * * @function measureTextWidth
+ * @param {string} text - 目标文本内容
+ * @param {number} [fontSize=14] - 渲染时的逻辑像素字号
+ * @param {string} [fontFamily='Arial'] - 应用的字体族
+ * @returns {number} 文本在视口中实际占用的像素宽度 (px)
  */
 export function measureTextWidth(text: string, fontSize: number = 14, fontFamily: string = 'Arial'): number {
   if (!text || typeof text !== 'string') {
     return 0;
   }
 
-  // Try to create a temporary canvas element to measure text
+  // 步骤 1：探测宿主环境兼容性，确保 SSR 或测试脚本不抛出异常
   try {
-    // Check if we're in a browser environment
     if (typeof document === 'undefined' || typeof window === 'undefined') {
-      // Fallback for server-side rendering or test environments
+      // 容错分支：基于统计学常数 0.6 估算平均宽度因子
       return text.length * (fontSize * 0.6);
     }
 
+    // 步骤 2：初始化离屏 Canvas 测绘上下文
     const canvas = document.createElement('canvas');
     const context = canvas.getContext('2d');
 
     if (context) {
+      // 注入目标样式参数
       context.font = `${fontSize}px ${fontFamily}`;
+      // 执行原生 TextMetrics 测量
       const metrics = context.measureText(text);
       return metrics.width;
     }
   } catch (error) {
+    // 异常拦截：当 Canvas 指纹保护等隐私设置导致 API 受限时，执行备选预估方案
     console.warn('Canvas text measurement failed, using fallback:', error);
   }
 
-  // Fallback: estimate based on character count and average character width
-  // This is a rough approximation for testing purposes
+  // 步骤 3：通用兜底策略
   return text.length * (fontSize * 0.6);
 }
 
 /**
- * Truncate text to fit within a specific pixel width
- * Requirement 3.5: Add utility functions for text measurement and truncation
+ * 物理像素级精准截断算法
+ * 需求 3.5: 针对非定宽容器，计算最匹配可用空间的文本子集。
+ * * 算法策略：
+ * 采用二分搜索（Binary Search）优化截断性能，将 O(n) 的测量复杂度降低至 O(log n)。
+ * * @function truncateToWidth
+ * @param {string} text - 原始文本
+ * @param {number} maxWidth - 容器允许的最大物理像素值 (px)
  */
 export function truncateToWidth(text: string, maxWidth: number, fontSize: number = 14, fontFamily: string = 'Arial'): string {
   if (!text) {
     return '';
   }
 
+  // 先检查全量渲染是否符合空间约束
   const fullWidth = measureTextWidth(text, fontSize, fontFamily);
 
   if (fullWidth <= maxWidth) {
     return text;
   }
 
-  // Binary search to find the optimal truncation point
+  /**
+   * 二分搜索执行逻辑：
+   * 旨在快速定位“能容纳下”与“溢出”临界点之间的最大索引位。
+   */
   let left = 0;
   let right = text.length;
   let bestFit = '';
@@ -131,12 +183,15 @@ export function truncateToWidth(text: string, maxWidth: number, fontSize: number
   while (left <= right) {
     const mid = Math.floor((left + right) / 2);
     const candidate = text.substring(0, mid) + '...';
+    // 执行 Canvas 实时测距
     const candidateWidth = measureTextWidth(candidate, fontSize, fontFamily);
 
     if (candidateWidth <= maxWidth) {
+      // 当前长度可行，尝试向右探测更大的容量
       bestFit = candidate;
       left = mid + 1;
     } else {
+      // 当前长度溢出，向左收缩查找空间
       right = mid - 1;
     }
   }
@@ -145,31 +200,39 @@ export function truncateToWidth(text: string, maxWidth: number, fontSize: number
 }
 
 /**
- * Format date for display
- * Requirement 8.1: "YYYY-MM-DD HH:mm" format
- * Requirement 8.5: "今天 HH:mm" for today's dates
+ * 语义化项目日期格式化引擎
+ * 需求 8.1: 实现标准 YYYY-MM-DD HH:mm 展示。
+ * 需求 8.5: 引入相对时间感知，增强对今日（Today）活动的识别度。
+ * * @function formatProjectDate
+ * @param {string} dateString - 符合 ISO 8601 标准的原始时间戳字符串
+ * @returns {string} 用户友好的格式化日期
  */
 export function formatProjectDate(dateString: string): string {
   try {
     const date = new Date(dateString);
 
-    // Check if date is invalid
+    // 类型安全性校验：拦截解析失败的 Date 对象
     if (isNaN(date.getTime())) {
       return 'Invalid Date';
     }
 
+    // 步骤 1：获取基准时间。计算当前“今日 0 点”的时间戳。
     const now = new Date();
     const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
     const dateOnly = new Date(date.getFullYear(), date.getMonth(), date.getDate());
 
-    // Check if the date is today
+    // 步骤 2：判定是否为“今日”发生的业务活动
     if (dateOnly.getTime() === today.getTime()) {
       const hours = date.getHours().toString().padStart(2, '0');
       const minutes = date.getMinutes().toString().padStart(2, '0');
+      // 增强 UX：展示为“今天 HH:mm”
       return `今天 ${hours}:${minutes}`;
     }
 
-    // Format as YYYY-MM-DD HH:mm
+    /**
+     * 步骤 3：常规日期转换。
+     * 遵循 ISO 8601 补零规范，输出符合业务文档要求的标准格式。
+     */
     const year = date.getFullYear();
     const month = (date.getMonth() + 1).toString().padStart(2, '0');
     const day = date.getDate().toString().padStart(2, '0');
@@ -178,14 +241,18 @@ export function formatProjectDate(dateString: string): string {
 
     return `${year}-${month}-${day} ${hours}:${minutes}`;
   } catch (error) {
+    // 异常恢复逻辑
     return 'Invalid Date';
   }
 }
 
 /**
- * Calculate tooltip position to avoid viewport edges
- * Requirement 2.4: Tooltip positioning
- * Enhanced with error handling and fallbacks
+ * 视口感知型 Tooltip 坐标计算算法
+ * 需求 2.4: 精确控制浮窗位置，防止 UI 元素超出屏幕可视区域（Viewport Collision Detection）。
+ * * 核心逻辑：
+ * 1. 计算首选位置（Top/Bottom/Left/Right）；
+ * 2. 执行屏幕边界审计，若发生溢出则自动执行“镜像翻转”或“强制校正”。
+ * * @function calculateTooltipPosition
  */
 export function calculateTooltipPosition(
   cardElement: HTMLElement,
@@ -193,31 +260,36 @@ export function calculateTooltipPosition(
   preferredPlacement: 'top' | 'bottom' | 'left' | 'right' = 'top'
 ): { x: number; y: number; placement: 'top' | 'bottom' | 'left' | 'right' } {
   try {
-    // Validate inputs
+    // 参数验证：确保 DOM 节点已完成渲染且可被测量
     if (!cardElement || !tooltipElement) {
       console.warn('Invalid elements provided to calculateTooltipPosition');
       return { x: 0, y: 0, placement: 'top' };
     }
 
+    // 调用浏览器原生 API 获取几何属性矩阵
     const cardRect = cardElement.getBoundingClientRect();
     const tooltipRect = tooltipElement.getBoundingClientRect();
 
-    // Validate rectangles
+    // 几何矩阵存在性检查
     if (!cardRect || !tooltipRect) {
       console.warn('Could not get element rectangles for tooltip positioning');
       return { x: 0, y: 0, placement: 'top' };
     }
 
+    // 建立视口边界快照
     const viewport = {
-      width: window.innerWidth || 1024, // Fallback viewport width
-      height: window.innerHeight || 768, // Fallback viewport height
+      width: window.innerWidth || 1024, 
+      height: window.innerHeight || 768, 
     };
 
     let x = 0;
     let y = 0;
     let placement = preferredPlacement;
 
-    // Calculate position based on preferred placement
+    /**
+     * 步骤 1：基于业务偏好方位计算初步相对坐标。
+     * 每个分支均计算水平/垂直对齐及 8px 的视觉边距偏移。
+     */
     switch (preferredPlacement) {
       case 'top':
         x = cardRect.left + cardRect.width / 2 - tooltipRect.width / 2;
@@ -236,13 +308,16 @@ export function calculateTooltipPosition(
         y = cardRect.top + cardRect.height / 2 - tooltipRect.height / 2;
         break;
       default:
-        // Fallback to top placement
+        // 兜底逻辑：默认上方居中
         x = cardRect.left + cardRect.width / 2 - tooltipRect.width / 2;
         y = cardRect.top - tooltipRect.height - 8;
         placement = 'top';
     }
 
-    // Adjust if tooltip would go outside viewport
+    /**
+     * 步骤 2：自适应碰撞检测（Collision Detection）。
+     * 若计算出的 X/Y 轴坐标导致 Tooltip 溢出视口，则触发位移修正或对位翻转。
+     */
     if (x < 8) {
       x = 8;
       if (placement === 'left') placement = 'right';
@@ -260,29 +335,33 @@ export function calculateTooltipPosition(
       if (placement === 'bottom') placement = 'top';
     }
 
-    // Ensure coordinates are valid numbers
+    // 最终数值清洗：确保返回的是合法的非负像素值
     x = isNaN(x) ? 0 : Math.max(0, x);
     y = isNaN(y) ? 0 : Math.max(0, y);
 
     return { x, y, placement };
   } catch (error) {
+    // 全局防崩溃兜底方案
     console.error('Error calculating tooltip position:', error);
-    // Return safe fallback position
     return { x: 0, y: 0, placement: 'top' };
   }
 }
 
 /**
- * Calculate initial tooltip position from mouse event
- * Requirement 2.4: Tooltip positioning
- * Enhanced with error handling and fallbacks
+ * 初始交互坐标计算引擎
+ * 用于在鼠标首次进入（MouseEnter）时，快速锚定 Tooltip 的入场位置。
+ * * * 架构标注：
+ * 此处参数 _mouseEvent 前缀下划线，符合 TypeScript 强制性规范中对“占位符变量”的显式声明要求。
+ * 旨在为后续版本的“动态光标追随”特性预留 API 接口定义，当前计算逻辑暂仅依赖 cardElement 的几何边界。
+ * * * @function calculateTooltipPositionFromEvent
+ * @param {HTMLElement} cardElement - 触发悬停的项目卡片 DOM 实例
+ * @param {React.MouseEvent} _mouseEvent - React 原始鼠标事件（预留扩展参数）
  */
 export function calculateTooltipPositionFromEvent(
   cardElement: HTMLElement,
-  mouseEvent: React.MouseEvent<HTMLDivElement>
+  _mouseEvent: React.MouseEvent<HTMLDivElement>
 ): { x: number; y: number; placement: 'top' | 'bottom' | 'left' | 'right' } {
   try {
-    // Validate inputs
     if (!cardElement) {
       console.warn('Invalid card element provided to calculateTooltipPositionFromEvent');
       return { x: 0, y: 0, placement: 'top' };
@@ -290,30 +369,29 @@ export function calculateTooltipPositionFromEvent(
 
     const cardRect = cardElement.getBoundingClientRect();
 
-    // Validate rectangle
     if (!cardRect) {
       console.warn('Could not get card rectangle for tooltip positioning');
       return { x: 0, y: 0, placement: 'top' };
     }
 
-    // Default position above the card
+    // 设置默认中心悬停坐标。逻辑实现上，我们当前优先保证 Tooltip 的居中对称美感。
     const x = cardRect.left + cardRect.width / 2;
     const y = cardRect.top - 8;
 
-    // Ensure coordinates are valid numbers
     const safeX = isNaN(x) ? 0 : Math.max(0, x);
     const safeY = isNaN(y) ? 0 : Math.max(0, y);
 
     return { x: safeX, y: safeY, placement: 'top' };
   } catch (error) {
     console.error('Error calculating tooltip position from event:', error);
-    // Return safe fallback position
     return { x: 0, y: 0, placement: 'top' };
   }
 }
 
 /**
- * Get Chinese label for project status
+ * 项目状态多语言标签映射器
+ * 将后端枚举值转换为符合用户认知的中文语义描述。
+ * @param {'initializing' | 'active' | 'inactive'} status - 项目原始状态码
  */
 export function getProjectStatusLabel(status: 'initializing' | 'active' | 'inactive'): string {
   const statusLabels = {
@@ -325,14 +403,15 @@ export function getProjectStatusLabel(status: 'initializing' | 'active' | 'inact
 }
 
 /**
- * Check if a project status is valid
+ * 项目状态枚举合法性校验器
  */
 export function isValidProjectStatus(status: string): status is 'initializing' | 'active' | 'inactive' {
   return ['initializing', 'active', 'inactive'].includes(status);
 }
 
 /**
- * Get status badge color class
+ * 动态样式类映射器
+ * 根据项目状态返回对应的 BEM 规范 CSS 类名，用于 Badge 组件的着色。
  */
 export function getStatusBadgeColorClass(status: 'initializing' | 'active' | 'inactive'): string {
   switch (status) {
-- 
2.34.1