1
0

refactor: 迁移 UI 组件库从 Ant Design 至 TDesign

- 替换 antd 为 tdesign-react 作为主要 UI 组件库
- 引入 Recharts 替代 @ant-design/charts 实现图表功能
- 移除主题系统相关代码(ThemeContext、themes 目录)
- 更新所有组件以适配 TDesign 组件 API
- 更新测试用例以匹配新的组件实现
- 新增 TDesign 和 Recharts 集成规范文档
This commit is contained in:
2026-04-17 18:22:13 +08:00
parent 6eeb38c15e
commit 2b1c5e96c3
55 changed files with 1622 additions and 2541 deletions

View File

@@ -8,16 +8,15 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
### Requirement: 提供供应商管理页面
前端 SHALL 使用 Ant Design 组件提供供应商管理页面,所有组件 SHALL 遵循 antd v6 API 规范
前端 SHALL 使用 TDesign 组件提供供应商管理页面。
#### Scenario: 显示供应商列表
- **WHEN** 加载供应商管理页面
- **THEN** 前端 SHALL 使用 Ant Design Table 显示所有已配置供应商
- **THEN** 前端 SHALL 使用 TDesign Table 显示所有已配置供应商
- **THEN** 每个供应商 SHALL 显示 name、base_url 和 enabled 状态(使用 Tag 组件)
- **THEN** API Key SHALL 被脱敏显示(掩码处理)
- **THEN** 表格 SHALL 支持展开行以显示关联模型
- **THEN** 表格 SHALL 设置 `scroll={{ x: 'max-content' }}` 防止窄屏溢出
#### Scenario: 表格列宽约束
@@ -36,32 +35,32 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
#### Scenario: 添加新供应商
- **WHEN** 用户点击"添加供应商"按钮
- **THEN** 前端 SHALL 使用 Ant Design Modal + Form 显示输入表单
- **THEN** 前端 SHALL 使用 TDesign Dialog + Form 显示输入表单
- **THEN** 表单 SHALL 包含 id、name、api_key、base_url 字段,带校验规则
- **WHEN** 用户提交包含有效数据的表单
- **THEN** 前端 SHALL 通过 useMutation 调用创建 API
- **THEN** 成功后 SHALL 关闭 Modal 并刷新供应商列表
- **THEN** 失败 SHALL 使用 `App.useApp()` 提供的 `message` 实例显示错误提示
- **THEN** 成功后 SHALL 关闭 Dialog 并刷新供应商列表
- **THEN** 失败 SHALL 显示错误提示
#### Scenario: 编辑现有供应商
- **WHEN** 用户点击供应商的"编辑"按钮
- **THEN** 前端 SHALL 使用 Ant Design Modal + Form 显示预填充数据的表单
- **THEN** 前端 SHALL 使用 TDesign Dialog + Form 显示预填充数据的表单
- **WHEN** 用户提交包含更新数据的表单
- **THEN** 前端 SHALL 通过 useMutation 调用更新 API
- **THEN** 成功后 SHALL 关闭 Modal 并刷新供应商列表
- **THEN** 成功后 SHALL 关闭 Dialog 并刷新供应商列表
#### Scenario: 删除供应商
- **WHEN** 用户点击供应商的"删除"按钮
- **THEN** 前端 SHALL 使用 Ant Design Popconfirm 弹出确认
- **THEN** 前端 SHALL 使用 TDesign Popconfirm 弹出确认
- **WHEN** 用户确认删除
- **THEN** 前端 SHALL 通过 useMutation 调用删除 API
- **THEN** 成功后 SHALL 刷新供应商列表
### Requirement: 提供模型管理界面
前端 SHALL 在供应商页面展开行中提供模型管理,所有组件 SHALL 遵循 antd v6 API 规范
前端 SHALL 在供应商页面展开行中提供模型管理。
#### Scenario: 显示供应商的模型
@@ -78,9 +77,9 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
#### Scenario: 为供应商添加模型
- **WHEN** 用户在展开行中点击"添加模型"
- **THEN** 前端 SHALL 显示 Ant Design Modal + Form
- **THEN** 前端 SHALL 显示 TDesign Dialog + Form
- **THEN** provider_id SHALL 自动关联当前供应商
- **THEN** 供应商选择 SHALL 使用 `options` 属性而非 `Select.Option` 子组件
- **THEN** 供应商选择 SHALL 使用 `options` 属性
- **WHEN** 用户提交表单
- **THEN** 前端 SHALL 通过 useMutation 调用创建 API
- **THEN** 成功后 SHALL 刷新模型列表
@@ -103,7 +102,7 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
### Requirement: 提供统计查看页面
前端 SHALL 使用 Ant Design 组件提供统计仪表盘页面。
前端 SHALL 使用 TDesign 组件提供统计仪表盘页面。
#### Scenario: 显示统计概览
@@ -111,9 +110,8 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
- **THEN** 前端 SHALL 在顶部显示统计摘要卡片(总请求量、活跃模型数、活跃供应商数、今日请求量)
- **THEN** 统计摘要数据 SHALL 从 stats API 返回数据中前端聚合
- **THEN** 前端 SHALL 显示请求趋势折线图
- **THEN** 前端 SHALL 使用 Ant Design Table 显示统计数据
- **THEN** 前端 SHALL 使用 TDesign Table 显示统计数据
- **THEN** 统计数据 SHALL 按供应商和模型显示请求计数
- **THEN** 统计表格 SHALL 设置 `scroll={{ x: 'max-content' }}` 防止窄屏溢出
#### Scenario: 统计表格列宽约束
@@ -130,24 +128,24 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
#### Scenario: 按供应商过滤统计
- **WHEN** 用户从 Ant Design Select 选择供应商
- **WHEN** 用户从 TDesign Select 选择供应商
- **THEN** 前端 SHALL 自动查询并过滤统计
- **THEN** 统计摘要卡片和趋势图表 SHALL 同步更新
#### Scenario: 按日期范围过滤统计
- **WHEN** 用户使用 Ant Design DatePicker.RangePicker 选择日期范围
- **WHEN** 用户使用 TDesign DateRangePicker 选择日期范围
- **THEN** 前端 SHALL 自动查询并过滤统计
- **THEN** 统计摘要卡片和趋势图表 SHALL 同步更新
### Requirement: 优雅处理 API 错误
前端 SHALL 处理 API 错误并显示用户友好的消息message 组件 SHALL 通过 `App.useApp()` 获取
前端 SHALL 处理 API 错误并显示用户友好的消息。
#### Scenario: API 请求失败
- **WHEN** API 请求失败网络错误、4xx、5xx
- **THEN** 前端 SHALL 使用 `App.useApp()` 提供的 `message` 实例显示全局错误提示
- **THEN** 前端 SHALL 显示全局错误提示
- **THEN** 错误消息 SHALL 具有描述性
#### Scenario: 验证错误
@@ -158,21 +156,14 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
### Requirement: 提供响应式布局
前端 SHALL 使用 Ant Design Layout 提供侧边栏导航布局。
前端 SHALL 使用 TDesign Layout 提供侧边栏导航布局。
#### Scenario: 桌面布局
- **WHEN** 在桌面屏幕上查看前端(宽度 >= 992px
- **THEN** 布局 SHALL 使用 Ant Design `Layout.Sider` + `Menu`inline 模式)
- **WHEN** 在桌面屏幕上查看前端
- **THEN** 布局 SHALL 使用 TDesign `Layout.Aside` + `Menu`
- **THEN** 侧边栏 SHALL 显示导航菜单,包含图标和文字标签
- **THEN** 侧边栏 SHALL 可通过折叠按钮折叠为仅图标模式
#### Scenario: 响应式折叠
- **WHEN** 屏幕宽度小于 992px
- **THEN** 侧边栏 SHALL 自动折叠为图标模式
- **THEN** 折叠后侧边栏宽度 SHALL 为 80px
- **THEN** 菜单项 SHALL 仅显示图标
- **THEN** 侧边栏 SHALL 使用固定宽度 232px
#### Scenario: 页面内容区域
@@ -186,70 +177,52 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
- **THEN** Header SHALL 仅显示当前页面标题
- **THEN** Header SHALL 不包含导航菜单
### Requirement: 使用无组件库的最小 UI
### Requirement: 使用 TDesign UI 组件库
前端 SHALL 使用 Ant Design 6 作为 UI 组件库,所有组件 SHALL 使用 antd v6 推荐的 API
#### Scenario: Ant Design 组件使用
- **WHEN** 实现前端
- **THEN** Button 组件 SHALL 使用 `variant``color` 属性替代已废弃的 `type`link/text/dashed`danger` 属性
- **THEN** Button `type="link"` SHALL 替换为 `variant="link"`
- **THEN** Button `danger` 属性 SHALL 替换为 `color="danger"`
- **THEN** Space 组件 SHALL 使用 `vertical` 布尔属性替代已废弃的 `direction` 属性
- **THEN** Select 组件 SHALL 使用 `options` 属性替代 `Select.Option` 子组件
- **THEN** 图标 SHALL 优先使用图标库中已有的图标
#### Scenario: App 组件包裹
- **WHEN** 应用初始化
- **THEN** `App.tsx` SHALL 在 `ConfigProvider` 内部使用 Ant Design `<App>` 组件包裹应用
- **THEN** hooks 中 SHALL 使用 `App.useApp()` 获取 `message` 实例
- **THEN** `message` 实例 SHALL NOT 通过静态 `import { message } from 'antd'` 获取
前端 SHALL 使用 TDesign 作为 UI 组件库。
### Requirement: 样式体系
前端样式 SHALL 优先使用 Ant Design 样式体系SCSS 作为补充工具。
前端样式 SHALL 优先使用 TDesign 样式体系SCSS 作为补充工具。
#### Scenario: Ant Design 样式优先
#### Scenario: TDesign 样式优先
- **WHEN** 实现组件样式
- **THEN** 前端 SHALL 优先使用 Ant Design 组件的 style prop
- **THEN** 前端 SHALL 优先使用 Ant Design v6 的语义化样式classNames 和 styles props
- **THEN** 前端 SHALL 使用 Ant Design Layout 组件处理布局
- **THEN** 前端 SHALL 优先使用 TDesign 组件的 style prop
- **THEN** 前端 SHALL 使用 TDesign Layout 组件处理布局
#### Scenario: SCSS 补充使用
- **WHEN** Ant Design 样式体系无法满足需求
- **WHEN** TDesign 样式体系无法满足需求
- **THEN** 前端 MAY 使用 SCSS 作为补充
- **THEN** SCSS 文件 SHALL 使用 *.module.scssSCSS Modules
- **THEN** 前端 SHALL NOT 使用纯 CSS 文件(*.css
#### Scenario: 移除冗余 SCSS
- **WHEN** SCSS 文件仅实现 Ant Design 已有的功能
- **WHEN** SCSS 文件仅实现 TDesign 已有的功能
- **THEN** 前端 SHALL 移除该 SCSS 文件
- **THEN** 前端 SHALL 使用 Ant Design 内置功能替代
- **THEN** 前端 SHALL 使用 TDesign 内置功能替代
### Requirement: 提供侧边栏导航
前端 SHALL 使用 Ant Design `Layout.Sider` 提供侧边栏导航。
前端 SHALL 使用 TDesign `Layout.Aside` 提供侧边栏导航。
#### Scenario: 侧边栏内容
- **WHEN** 渲染侧边栏
- **THEN** 侧边栏顶部 SHALL 显示应用名称/Logo
- **THEN** 侧边栏 SHALL 包含 inline 模式的导航菜单
- **THEN** 导航菜单项 SHALL 包含:供应商管理(CloudServerOutlined 图标)、用量统计(BarChartOutlined 图标)
- **THEN** 侧边栏底部 SHALL 放置主题切换按钮
- **THEN** 侧边栏 SHALL 包含导航菜单
- **THEN** 导航菜单项 SHALL 包含供应商管理ServerIcon 图标、用量统计ChartLineIcon 图标、设置SettingIcon 图标)
#### Scenario: 侧边栏折叠
#### Scenario: 导航菜单交互
- **WHEN** 用户点击侧边栏折叠按钮
- **THEN** 侧边栏 SHALL 切换折叠/展开状态
- **THEN** 折叠状态下菜单项 SHALL 仅显示图标
- **THEN** 折叠状态下应用名称/Logo SHALL 隐藏或缩小
- **THEN** 折叠状态下主题切换按钮 SHALL 保持可见可点击
- **WHEN** 用户点击导航中的"供应商管理"
- **THEN** 前端 SHALL 导航到 `/providers` 并高亮当前菜单项
- **WHEN** 用户点击导航中的"用量统计"
- **THEN** 前端 SHALL 导航到 `/stats` 并高亮当前菜单项
- **WHEN** 用户点击导航中的"设置"
- **THEN** 前端 SHALL 导航到 `/settings` 并高亮当前菜单项
#### Scenario: 导航菜单交互
@@ -355,10 +328,10 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
- **WHEN** 用户执行创建、更新或删除操作
- **THEN** 前端 SHALL 使用 TanStack Query 的 useMutation hook
- **THEN** 操作成功后 SHALL 自动失效相关查询缓存
- **THEN** 操作失败 SHALL 使用 `App.useApp()` 提供的 `message` 实例显示错误提示
- **THEN** 操作失败 SHALL 显示错误提示
#### Scenario: 错误提示
- **WHEN** API 请求失败网络错误、4xx、5xx
- **THEN** 前端 SHALL 使用 `App.useApp()` 提供的 `message` 实例显示全局错误提示
- **THEN** 前端 SHALL 显示全局错误提示
- **THEN** 错误消息 SHALL 具有描述性