nex/frontend/openspec/changes/archive/2026-04-17-migrate-to-tdesign/design.md

## Context

**当前状态**：
- 前端使用Ant Design 6.3.5作为UI框架
- 实现了6套自定义主题系统（default、dark、mui、shadcn、bootstrap、glass）
- 使用@ant-design/charts进行数据可视化
- 使用antd-style进行动态样式管理
- 完整的供应商管理和统计功能

**约束条件**：
- 必须保持所有业务功能不变
- 图表功能必须保留
- Settings页面路由必须保留（即使暂时为空）
- 使用bun作为唯一包管理器
- 遵循项目现有代码规范（中文注释、测试覆盖）

**利益相关者**：
- 前端开发团队：维护成本降低
- 产品用户：UI风格变化，功能保持不变

## Goals / Non-Goals

**Goals:**
- 完全迁移到TDesign React组件库，统一设计系统
- 移除复杂的多主题系统，简化代码架构
- 使用Recharts替代@ant-design/charts实现数据可视化
- 保持所有业务功能完整可用
- 确保测试覆盖率不降低
- 优化bundle体积（移除未使用的主题系统）

**Non-Goals:**
- 不实现新的业务功能
- 不保留Ant Design相关代码或依赖
- 不实现侧边栏折叠功能（接受简化）
- 不实现主题切换功能（使用TDesign默认主题）
- 不优化后端API或数据结构

## Decisions

### 1. 图表库选择：Recharts

**决策**：使用Recharts替代@ant-design/charts

**理由**：
- React原生JSX语法，与TDesign风格一致
- TypeScript支持优秀，类型定义完整
- 文档清晰，社区活跃（1.8M周下载量）
- Bundle体积适中（~370KB vs ECharts ~1MB）
- shadcn/ui生态默认选择，现代化设计
- 声明式组件，易于维护和测试

**替代方案**：
- **ECharts**：功能强大但体积大（1MB），需要wrapper，非React原生
- **Chart.js**：最流行但非React原生，需要react-chartjs-2 wrapper
- **Visx**：最灵活但学习曲线陡峭，适合高度定制场景

**实现**：
```tsx
// UsageChart.tsx
import { LineChart, Line, XAxis, YAxis, CartesianGrid, ResponsiveContainer, Tooltip } from 'recharts';

<ResponsiveContainer width="100%" height={300}>
  <LineChart data={chartData}>
    <CartesianGrid strokeDasharray="3 3" />
    <XAxis dataKey="date" />
    <YAxis />
    <Tooltip />
    <Line type="monotone" dataKey="requestCount" stroke="#0052D9" strokeWidth={2} />
  </LineChart>
</ResponsiveContainer>
```

### 2. 主题系统：完全移除

**决策**：删除所有主题相关代码，使用TDesign默认主题

**理由**：
- 多主题系统增加维护成本和代码复杂度
- TDesign默认主题已满足企业级应用需求
- 简化迁移过程，降低风险
- 减少bundle体积（移除antd-style和主题配置）

**实现**：
- 删除`src/contexts/ThemeContext.tsx`
- 删除`src/themes/`整个目录
- App.tsx移除ThemeProvider，直接使用TDesign ConfigProvider
- Settings页面简化为空页面

### 3. 布局组件：简化侧边栏

**决策**：移除侧边栏折叠功能，使用固定宽度侧边栏

**理由**：
- TDesign Menu组件没有内置折叠功能
- 自定义实现增加复杂度和维护成本
- 固定宽度侧边栏满足当前业务需求
- 简化迁移过程，降低风险

**实现**：
```tsx
// AppLayout.tsx
<Layout.Aside width="232px">
  <div style={{ height: 64 }}>AI Gateway</div>
  <Menu value={location.pathname} items={menuItems} onChange={({ value }) => navigate(value)} />
</Layout.Aside>
```

### 4. 图标系统：TDesign Icons

**决策**：使用tdesign-icons-react图标库

**理由**：
- 与TDesign组件库配套，风格一致
- 支持按需导入，优化bundle体积
- 提供完整的图标集合

**映射方案**：
```tsx
// Ant Design → TDesign
CloudServerOutlined → CloudServerIcon (或ServerIcon)
BarChartOutlined    → ChartLineIcon (或ChartIcon)
SettingOutlined     → SettingIcon
```

**注意**：具体图标名称需要在安装tdesign-icons-react后确认，根据实际可用图标选择最接近的。

### 5. 栅格系统：保持不变

**决策**：继续使用Row/Col栅格系统

**理由**：
- TDesign提供完整的Row/Col组件
- API与Ant Design完全兼容
- 无需修改现有栅格代码
- 保持响应式布局能力

**实现**：直接替换import路径即可
```tsx
// import { Row, Col } from 'antd';
import { Row, Col } from 'tdesign-react';
```

### 6. 表单组件：Dialog替代Modal

**决策**：使用TDesign Dialog组件替代Ant Design Modal

**理由**：
- Dialog是TDesign的标准弹窗组件
- API相似，迁移成本低
- 支持所有必要功能（确认、取消、加载状态）

**API映射**：
```tsx
// Ant Design Modal → TDesign Dialog
title       → header
open        → visible
onOk        → onConfirm
onCancel    → onClose (注意：语义略有不同)
okText      → confirmBtn
cancelText  → cancelBtn
destroyOnHidden → destroyOnClose
Form.Item   → Form.FormItem
```

### 7. 迁移策略：渐进式文件替换

**决策**：按模块逐个替换，保持项目可运行

**理由**：
- 降低风险，便于调试
- 可以逐步验证每个模块的功能
- 出现问题容易定位和回滚

**顺序**：
1. 依赖安装与配置（基础）
2. App.tsx主题移除（入口）
3. AppLayout布局迁移（导航）
4. 表单组件迁移（ProviderForm、ModelForm）
5. 表格组件迁移（ProviderTable、ModelTable、StatsTable）
6. 统计组件迁移（StatCards、UsageChart）
7. Settings页面简化
8. 测试文件更新

## Risks / Trade-offs

### 风险1：图标名称不匹配
**风险**：TDesign可能没有与Ant Design完全对应的图标名称

**缓解**：
- 安装tdesign-icons-react后立即确认可用图标
- 选择语义最接近的图标
- 必要时使用通用图标（如CloudIcon、ChartIcon、SettingIcon）
- 在design.md中记录最终选择的图标映射

### 风险2：组件API差异导致功能缺失
**风险**：TDesign组件API与Ant Design不完全一致，可能影响功能

**缓解**：
- 逐个组件对比API文档
- 编写详细的迁移映射表
- 每个模块迁移后立即测试验证
- 保留原有业务逻辑，只替换UI组件

### 风险3：样式差异影响用户体验
**风险**：TDesign默认样式与Ant Design不同，用户可能不适应

**缓解**：
- 迁移后进行完整UI验收测试
- 必要时通过ConfigProvider调整主题配置
- 记录样式差异点，统一调整

### 风险4：测试覆盖率下降
**风险**：迁移过程中测试可能失败或被跳过

**缓解**：
- 迁移前确保所有测试通过
- 每个模块迁移后立即更新对应测试
- 删除主题相关测试，其他测试必须保留
- 迁移后运行完整测试套件，确保覆盖率不降低

### 风险5：DatePicker日期格式处理
**风险**：TDesign DatePicker的日期格式处理可能与Ant Design不同

**缓解**：
- 对比两个组件的日期格式API
- 测试日期范围选择功能
- 确保与后端API的日期格式兼容

## Migration Plan

### 阶段1：依赖准备（0.5小时）
1. 安装新依赖：
   ```bash
   cd frontend
   bun add tdesign-react tdesign-icons-react recharts
   ```
2. 移除旧依赖：
   ```bash
   bun remove antd @ant-design/icons @ant-design/charts antd-style
   ```
3. 引入TDesign全局样式：
   ```tsx
   // src/main.tsx
   import 'tdesign-react/es/style/index.css';
   ```

### 阶段2：主题系统移除（0.5小时）
1. 删除`src/contexts/ThemeContext.tsx`
2. 删除`src/themes/`整个目录
3. 修改`src/App.tsx`：
   - 移除ThemeProvider导入和使用
   - 替换为TDesign ConfigProvider
4. 删除主题相关测试文件

### 阶段3：布局与导航迁移（1小时）
1. 修改`src/components/AppLayout/index.tsx`：
   - 替换Layout组件（Sider→Aside）
   - 替换Menu组件
   - 替换图标（@ant-design/icons→tdesign-icons-react）
   - 移除折叠功能相关代码
   - 移除主题相关逻辑
2. 更新AppLayout测试

### 阶段4：表单组件迁移（1.5小时）
1. 修改`src/pages/Providers/ProviderForm.tsx`：
   - Modal→Dialog
   - Form.Item→Form.FormItem
   - Input、Switch组件替换
2. 修改`src/pages/Providers/ModelForm.tsx`：
   - 同上处理
3. 更新表单测试

### 阶段5：表格组件迁移（1小时）
1. 修改`src/pages/Providers/ProviderTable.tsx`：
   - Table、Card、Button、Tag、Popconfirm、Space替换
2. 修改`src/pages/Providers/ModelTable.tsx`：
   - 同上处理
3. 修改`src/pages/Stats/StatsTable.tsx`：
   - Table、Card、Select、Input、DatePicker替换
4. 更新表格测试

### 阶段6：统计组件迁移（1小时）
1. 修改`src/pages/Stats/StatCards.tsx`：
   - Row、Col、Card、Statistic替换
2. 修改`src/pages/Stats/UsageChart.tsx`：
   - Card保持
   - @ant-design/charts→recharts重写
3. 更新统计测试

### 阶段7：Settings页面简化（0.5小时）
1. 修改`src/pages/Settings/index.tsx`：
   - 移除主题设置相关代码
   - 简化为空页面提示
2. 更新Settings测试

### 阶段8：测试与修复（2小时）
1. 运行完整测试套件：`bun test`
2. 修复失败的测试
3. 运行E2E测试：`bun test:e2e`
4. 手动验收测试：
   - 供应商管理完整流程
   - 统计数据展示
   - 图表交互
   - 响应式布局

### 阶段9：样式微调（1小时）
1. 检查UI一致性
2. 调整间距、颜色等细节
3. 确认图标显示正确
4. 最终验收

### 回滚策略
如果迁移过程中出现严重问题：
1. 恢复package.json到迁移前状态
2. 恢复所有源代码文件
3. 重新安装依赖：`bun install`
4. 运行测试确认回滚成功

**注意**：建议在迁移前创建Git分支，便于回滚。

## Open Questions

1. **TDesign图标名称确认**
   - 需要安装tdesign-icons-react后确认具体图标名称
   - 如果没有CloudServer/ChartLine/Setting图标，选择哪个替代？
   - 是否需要自定义SVG图标？

2. **DatePicker日期格式兼容性**
   - TDesign DatePicker的日期格式是否与后端API兼容？
   - RangePicker的API是否完全兼容？
   - 是否需要额外的日期处理逻辑？

3. **ConfigProvider全局配置**
   - 是否需要配置TDesign的全局属性？
   - 是否需要自定义主题token？
   - 国际化配置是否需要调整？

4. **性能影响评估**
   - 新bundle体积是否可接受？
   - Recharts渲染性能是否满足需求？
   - 是否需要代码分割优化？

5. **用户验收标准**
   - UI风格变化的接受度如何？
   - 是否需要用户参与验收测试？
   - 是否需要提供UI变更说明文档？