hnu202326010328
/
202326010
1
0
Fork 1
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Labels Milestones
New Pull Request

feat: 深度完善系统管理后台治理体系，标准化原子 UI 组件库与响应式交互文档 #38

Merged
hnu202326010328 merged 1 commits from wanglirong_branch into develop 1 month ago
Conversation 0 Commits 1 Files Changed 15
15 changed files with 2214 additions and 911 deletions
Show Stats Download Patch File Download Diff File

88
src/frontend/src/components/ConfirmDialog.tsx
Unescape View File

@ -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'}

255
src/frontend/src/components/InteractiveERRenderer.tsx
Unescape View File

@ -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); }

129
src/frontend/src/components/Pagination.tsx
Unescape View File

@ -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;

81
src/frontend/src/components/PanelToggleButton.tsx
Unescape View File

@ -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>
);

276
src/frontend/src/components/ProjectWizard.tsx
Unescape View File

@ -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>
);
};
};

159
src/frontend/src/components/Sidebar.tsx
Unescape View File

@ -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} /> 退出登录

365
src/frontend/src/components/UI.tsx
Unescape View File

@ -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';

192
src/frontend/src/hooks/useViewportWidth.ts
Unescape View File

@ -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];
}

305
src/frontend/src/pages/Admin.tsx
Unescape View File

@ -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>

292
src/frontend/src/pages/AdminAIModels.tsx
Unescape View File

@ -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>
);
};
};

221
src/frontend/src/pages/AdminAnnouncements.tsx
Unescape View File

@ -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}
/>

109
src/frontend/src/types/project-overview.ts
Unescape View File

@ -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;
}

257
src/frontend/src/utils/errorHandling.ts
Unescape View File

@ -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();

205
src/frontend/src/utils/globalZoomLevel.ts
Unescape View File

@ -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;
}

191
src/frontend/src/utils/project-overview.ts
Unescape View File

@ -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) {

Write Preview
Loading…
Cancel
Save