lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
6eeb38c15eac43ace83d9fbbbc488ff12a05fe1e
nex/openspec/specs/frontend-config-ui/spec.md
lanyuanxiaoyao 6eeb38c15e refactor: 迁移前端 antd 组件至 v6 规范 API，消除废弃用法 
- 迁移静态 message 到 App.useApp() 模式，使 message 感知 ConfigProvider 上下文
- Button type/danger 迁移为 variant/color 新 API
- Space direction 迁移为 vertical 布尔属性
- Select.Option 子组件迁移为 options 属性
- AppLayout 硬编码颜色替换为 antd design token
- 优化 useThemeConfig：default/dark 改为静态导出，减少不必要的 hook 调用
- 同步更新 openspec 主规范文档
2026-04-17 00:59:36 +08:00

365 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 前端配置界面
## Purpose
TBD - 提供供应商、模型配置和用量统计的前端管理界面
## Requirements
### Requirement: 提供供应商管理页面
前端 SHALL 使用 Ant Design 组件提供供应商管理页面，所有组件 SHALL 遵循 antd v6 API 规范。
#### Scenario: 显示供应商列表
- **WHEN** 加载供应商管理页面
- **THEN** 前端 SHALL 使用 Ant Design Table 显示所有已配置供应商
- **THEN** 每个供应商 SHALL 显示 name、base_url 和 enabled 状态（使用 Tag 组件）
- **THEN** API Key SHALL 被脱敏显示（掩码处理）
- **THEN** 表格 SHALL 支持展开行以显示关联模型
- **THEN** 表格 SHALL 设置 `scroll={{ x: 'max-content' }}` 防止窄屏溢出
#### Scenario: 表格列宽约束
- **WHEN** 渲染供应商表格
- **THEN** 名称列 SHALL 固定宽度 180px 并启用 ellipsis（超长文本显示省略号，hover 显示 Tooltip）
- **THEN** Base URL 列 SHALL 不设固定宽度（浮动填充剩余空间）并启用 ellipsis + Tooltip
- **THEN** API Key 列 SHALL 固定宽度 120px 并启用 ellipsis
- **THEN** 状态列 SHALL 固定宽度 80px
- **THEN** 操作列 SHALL 固定宽度 160px
#### Scenario: 表格空状态
- **WHEN** 供应商列表为空
- **THEN** 表格 SHALL 显示自定义空状态文案 "暂无供应商，点击上方按钮添加"
#### Scenario: 添加新供应商
- **WHEN** 用户点击"添加供应商"按钮
- **THEN** 前端 SHALL 使用 Ant Design Modal + Form 显示输入表单
- **THEN** 表单 SHALL 包含 id、name、api_key、base_url 字段，带校验规则
- **WHEN** 用户提交包含有效数据的表单
- **THEN** 前端 SHALL 通过 useMutation 调用创建 API
- **THEN** 成功后 SHALL 关闭 Modal 并刷新供应商列表
- **THEN** 失败 SHALL 使用 `App.useApp()` 提供的 `message` 实例显示错误提示
#### Scenario: 编辑现有供应商
- **WHEN** 用户点击供应商的"编辑"按钮
- **THEN** 前端 SHALL 使用 Ant Design Modal + Form 显示预填充数据的表单
- **WHEN** 用户提交包含更新数据的表单
- **THEN** 前端 SHALL 通过 useMutation 调用更新 API
- **THEN** 成功后 SHALL 关闭 Modal 并刷新供应商列表
#### Scenario: 删除供应商
- **WHEN** 用户点击供应商的"删除"按钮
- **THEN** 前端 SHALL 使用 Ant Design Popconfirm 弹出确认
- **WHEN** 用户确认删除
- **THEN** 前端 SHALL 通过 useMutation 调用删除 API
- **THEN** 成功后 SHALL 刷新供应商列表
### Requirement: 提供模型管理界面
前端 SHALL 在供应商页面展开行中提供模型管理，所有组件 SHALL 遵循 antd v6 API 规范。
#### Scenario: 显示供应商的模型
- **WHEN** 展开供应商行
- **THEN** 前端 SHALL 显示该供应商的模型列表
- **THEN** 每个模型 SHALL 显示 model_name 和 enabled 状态
- **THEN** 模型名称列 SHALL 启用 ellipsis（超长文本显示省略号，hover 显示 Tooltip）
#### Scenario: 模型表格空状态
- **WHEN** 模型列表为空
- **THEN** 表格 SHALL 显示自定义空状态文案 "暂无模型，点击上方按钮添加"
#### Scenario: 为供应商添加模型
- **WHEN** 用户在展开行中点击"添加模型"
- **THEN** 前端 SHALL 显示 Ant Design Modal + Form
- **THEN** provider_id SHALL 自动关联当前供应商
- **THEN** 供应商选择 SHALL 使用 `options` 属性而非 `Select.Option` 子组件
- **WHEN** 用户提交表单
- **THEN** 前端 SHALL 通过 useMutation 调用创建 API
- **THEN** 成功后 SHALL 刷新模型列表
#### Scenario: 编辑模型
- **WHEN** 用户点击模型的"编辑"
- **THEN** 前端 SHALL 显示编辑表单
- **WHEN** 用户提交表单
- **THEN** 前端 SHALL 通过 useMutation 调用更新 API
- **THEN** 成功后 SHALL 刷新模型列表
#### Scenario: 删除模型
- **WHEN** 用户点击模型的"删除"
- **THEN** 前端 SHALL 使用 Popconfirm 弹出确认
- **WHEN** 用户确认删除
- **THEN** 前端 SHALL 通过 useMutation 调用删除 API
- **THEN** 成功后 SHALL 刷新模型列表
### Requirement: 提供统计查看页面
前端 SHALL 使用 Ant Design 组件提供统计仪表盘页面。
#### Scenario: 显示统计概览
- **WHEN** 加载统计页面
- **THEN** 前端 SHALL 在顶部显示统计摘要卡片（总请求量、活跃模型数、活跃供应商数、今日请求量）
- **THEN** 统计摘要数据 SHALL 从 stats API 返回数据中前端聚合
- **THEN** 前端 SHALL 显示请求趋势折线图
- **THEN** 前端 SHALL 使用 Ant Design Table 显示统计数据
- **THEN** 统计数据 SHALL 按供应商和模型显示请求计数
- **THEN** 统计表格 SHALL 设置 `scroll={{ x: 'max-content' }}` 防止窄屏溢出
#### Scenario: 统计表格列宽约束
- **WHEN** 渲染统计表格
- **THEN** 供应商列 SHALL 固定宽度 180px 并启用 ellipsis + Tooltip
- **THEN** 模型列 SHALL 固定宽度 250px 并启用 ellipsis + Tooltip
- **THEN** 日期列 SHALL 固定宽度 120px
- **THEN** 请求数列 SHALL 固定宽度 100px 并右对齐
#### Scenario: 统计表格空状态
- **WHEN** 统计数据为空
- **THEN** 表格 SHALL 显示自定义空状态文案 "暂无统计数据"
#### Scenario: 按供应商过滤统计
- **WHEN** 用户从 Ant Design Select 选择供应商
- **THEN** 前端 SHALL 自动查询并过滤统计
- **THEN** 统计摘要卡片和趋势图表 SHALL 同步更新
#### Scenario: 按日期范围过滤统计
- **WHEN** 用户使用 Ant Design DatePicker.RangePicker 选择日期范围
- **THEN** 前端 SHALL 自动查询并过滤统计
- **THEN** 统计摘要卡片和趋势图表 SHALL 同步更新
### Requirement: 优雅处理 API 错误
前端 SHALL 处理 API 错误并显示用户友好的消息，message 组件 SHALL 通过 `App.useApp()` 获取。
#### Scenario: API 请求失败
- **WHEN** API 请求失败（网络错误、4xx、5xx）
- **THEN** 前端 SHALL 使用 `App.useApp()` 提供的 `message` 实例显示全局错误提示
- **THEN** 错误消息 SHALL 具有描述性
#### Scenario: 验证错误
- **WHEN** 用户提交包含无效数据的表单
- **THEN** 前端 SHALL 在相关字段旁显示验证错误
- **THEN** 前端 SHALL 阻止表单提交
### Requirement: 提供响应式布局
前端 SHALL 使用 Ant Design Layout 提供侧边栏导航布局。
#### Scenario: 桌面布局
- **WHEN** 在桌面屏幕上查看前端（宽度 >= 992px）
- **THEN** 布局 SHALL 使用 Ant Design `Layout.Sider` + `Menu`（inline 模式）
- **THEN** 侧边栏 SHALL 显示导航菜单，包含图标和文字标签
- **THEN** 侧边栏 SHALL 可通过折叠按钮折叠为仅图标模式
#### Scenario: 响应式折叠
- **WHEN** 屏幕宽度小于 992px
- **THEN** 侧边栏 SHALL 自动折叠为图标模式
- **THEN** 折叠后侧边栏宽度 SHALL 为 80px
- **THEN** 菜单项 SHALL 仅显示图标
#### Scenario: 页面内容区域
- **WHEN** 显示页面内容
- **THEN** 内容区域 SHALL 在 `Layout.Content` 中渲染
- **THEN** 页面之间 SHALL 通过 React Router Outlet 渲染
#### Scenario: Header 区域
- **WHEN** 渲染页面 Header
- **THEN** Header SHALL 仅显示当前页面标题
- **THEN** Header SHALL 不包含导航菜单
### Requirement: 使用无组件库的最小 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'` 获取
### Requirement: 样式体系
前端样式 SHALL 优先使用 Ant Design 样式体系，SCSS 作为补充工具。
#### Scenario: Ant Design 样式优先
- **WHEN** 实现组件样式
- **THEN** 前端 SHALL 优先使用 Ant Design 组件的 style prop
- **THEN** 前端 SHALL 优先使用 Ant Design v6 的语义化样式（classNames 和 styles props）
- **THEN** 前端 SHALL 使用 Ant Design Layout 组件处理布局
#### Scenario: SCSS 补充使用
- **WHEN** Ant Design 样式体系无法满足需求
- **THEN** 前端 MAY 使用 SCSS 作为补充
- **THEN** SCSS 文件 SHALL 使用 *.module.scss（SCSS Modules）
- **THEN** 前端 SHALL NOT 使用纯 CSS 文件（*.css）
#### Scenario: 移除冗余 SCSS
- **WHEN** SCSS 文件仅实现 Ant Design 已有的功能
- **THEN** 前端 SHALL 移除该 SCSS 文件
- **THEN** 前端 SHALL 使用 Ant Design 内置功能替代
### Requirement: 提供侧边栏导航
前端 SHALL 使用 Ant Design `Layout.Sider` 提供侧边栏导航。
#### Scenario: 侧边栏内容
- **WHEN** 渲染侧边栏
- **THEN** 侧边栏顶部 SHALL 显示应用名称/Logo
- **THEN** 侧边栏 SHALL 包含 inline 模式的导航菜单
- **THEN** 导航菜单项 SHALL 包含：供应商管理（CloudServerOutlined 图标）、用量统计（BarChartOutlined 图标）
- **THEN** 侧边栏底部 SHALL 放置主题切换按钮
#### Scenario: 侧边栏折叠
- **WHEN** 用户点击侧边栏折叠按钮
- **THEN** 侧边栏 SHALL 切换折叠/展开状态
- **THEN** 折叠状态下菜单项 SHALL 仅显示图标
- **THEN** 折叠状态下应用名称/Logo SHALL 隐藏或缩小
- **THEN** 折叠状态下主题切换按钮 SHALL 保持可见可点击
#### Scenario: 导航菜单交互
- **WHEN** 用户点击导航中的"供应商管理"
- **THEN** 前端 SHALL 导航到 `/providers` 并高亮当前菜单项
- **WHEN** 用户点击导航中的"用量统计"
- **THEN** 前端 SHALL 导航到 `/stats` 并高亮当前菜单项
### Requirement: 提供导航
前端 SHALL 使用 React Router v7 提供导航。
#### Scenario: 路由配置
- **WHEN** 应用启动
- **THEN** 前端 SHALL 使用 React Router v7 Library 模式（BrowserRouter）
- **THEN** `/providers` 路径 SHALL 显示供应商管理页面
- **THEN** `/stats` 路径 SHALL 显示用量统计页面
- **THEN** `/` 路径 SHALL 重定向到 `/providers`
- **THEN** 不存在的路径 SHALL 显示 404 页面
#### Scenario: 导航菜单
- **WHEN** 用户点击导航中的"供应商管理"
- **THEN** 前端 SHALL 导航到 `/providers` 并高亮当前菜单项
- **WHEN** 用户点击导航中的"用量统计"
- **THEN** 前端 SHALL 导航到 `/stats` 并高亮当前菜单项
#### Scenario: URL 同步
- **WHEN** 用户在供应商页面刷新浏览器
- **THEN** 前端 SHALL 保持在供应商页面（URL 持久化）
- **WHEN** 用户使用浏览器后退按钮
- **THEN** 前端 SHALL 正确导航到上一个页面
### Requirement: 使用 React 和 TypeScript
前端 SHALL 使用 React 和 TypeScript 实现，遵循 strict 模式。
#### Scenario: TypeScript strict 模式
- **WHEN** 编写前端代码
- **THEN** TypeScript 配置 SHALL 开启 strict: true
- **THEN** TypeScript 配置 SHALL 开启 noUncheckedIndexedAccess
- **THEN** 所有代码 SHALL NOT 使用 any 类型
- **THEN** tsconfig SHALL 合并为单文件（不使用 project references）
#### Scenario: React 函数组件
- **WHEN** 实现 UI
- **THEN** 它 SHALL 使用 React 函数组件
- **THEN** 它 SHALL 使用自定义 Hooks 封装业务逻辑
### Requirement: 使用 Vite 构建
前端 SHALL 使用 Vite 作为构建工具。
#### Scenario: 开发服务器
- **WHEN** 在开发模式下启动前端
- **THEN** Vite SHALL 使用热模块替换服务应用
#### Scenario: 生产构建
- **WHEN** 为生产构建前端
- **THEN** Vite SHALL 生成优化的静态文件
### Requirement: 与后端 API 通信
前端 SHALL 使用 TanStack Query v5 和统一 API 客户端与后端通信。
#### Scenario: API 基础 URL 配置
- **WHEN** 前端发起 API 请求
- **THEN** 开发环境 SHALL 通过 Vite proxy 转发 /api 请求到后端
- **THEN** 生产环境 SHALL 使用环境变量 VITE_API_BASE 配置基础 URL
- **THEN** 前端 SHALL NOT 硬编码 API 基础 URL
#### Scenario: 统一 API 客户端
- **WHEN** 进行 API 调用
- **THEN** 所有调用 SHALL 通过 api/client.ts 的 request<T>() 方法
- **THEN** 错误处理 SHALL 统一抛出 ApiError（包含 status 和 message）
- **THEN** 开发环境 SHALL 使用 Vite proxy 转发 API 请求
#### Scenario: 字段名转换
- **WHEN** 接收后端 API 响应
- **THEN** API 层 SHALL 将 snake_case 字段转换为 camelCase
- **WHEN** 发送请求到后端 API
- **THEN** API 层 SHALL 将 camelCase 字段转换为 snake_case
- **THEN** hooks 和组件 SHALL 仅使用 camelCase 字段
#### Scenario: TanStack Query 数据管理
- **WHEN** 页面加载数据
- **THEN** 前端 SHALL 使用 TanStack Query 的 useQuery hook
- **THEN** 前端 SHALL 自动缓存请求结果
- **THEN** 前端 SHALL 自动处理加载和错误状态
#### Scenario: TanStack Query 写操作
- **WHEN** 用户执行创建、更新或删除操作
- **THEN** 前端 SHALL 使用 TanStack Query 的 useMutation hook
- **THEN** 操作成功后 SHALL 自动失效相关查询缓存
- **THEN** 操作失败 SHALL 使用 `App.useApp()` 提供的 `message` 实例显示错误提示
#### Scenario: 错误提示
- **WHEN** API 请求失败（网络错误、4xx、5xx）
- **THEN** 前端 SHALL 使用 `App.useApp()` 提供的 `message` 实例显示全局错误提示
- **THEN** 错误消息 SHALL 具有描述性
View Git Blame Copy Permalink