refactor: 迁移 UI 组件库从 Ant Design 至 TDesign
- 替换 antd 为 tdesign-react 作为主要 UI 组件库 - 引入 Recharts 替代 @ant-design/charts 实现图表功能 - 移除主题系统相关代码(ThemeContext、themes 目录) - 更新所有组件以适配 TDesign 组件 API - 更新测试用例以匹配新的组件实现 - 新增 TDesign 和 Recharts 集成规范文档
This commit is contained in:
@@ -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.scss(SCSS 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 具有描述性
|
||||
|
||||
Reference in New Issue
Block a user