feat: 前端优化

2025-12-21 22:24:16 +08:00
parent d3a8ea1964
commit b80de78d7c
36 changed files with 3721 additions and 1205 deletions
--- a/openspec/changes/refactor-task-management/specs/digital-human-task/spec.md
+++ b/openspec/changes/refactor-task-management/specs/digital-human-task/spec.md
@@ -0,0 +1,344 @@
+## ADDED Requirements
+
+### Requirement: 数字人任务列表显示
+
+数字人任务管理系统 SHALL 提供任务列表页面，用于查看和管理所有数字人生成任务。
+
+页面规范：
+- 路径：`/system/task-management/digital-human-task`
+- 布局：使用任务中心的左右分栏布局
+- 功能：显示、筛选、搜索、操作数字人任务
+
+#### Scenario: 显示数字人任务列表
+- **WHEN** 用户访问 `/system/task-management/digital-human-task`
+- **THEN** 显示数字人任务列表页面
+- **AND** 左侧导航中「数字人视频任务」项高亮
+- **AND** 右侧显示任务列表表格
+
+### Requirement: 任务列表表格列定义
+
+数字人任务列表 SHALL 显示以下列信息：
+
+列定义：
+- ID：任务唯一标识
+- 任务名称：用户设定的任务名称
+- 视频文件：原始视频文件信息
+- 文案内容：输入的文本内容（支持截断显示）
+- 音色：使用的音色配置
+- 状态：任务当前状态（pending/running/success/failed）
+- 进度：任务完成百分比（0-100）
+- 创建时间：任务创建的时间
+- 操作：可执行的操作按钮
+
+#### Scenario: 显示任务列表数据
+- **WHEN** 任务列表加载完成
+- **THEN** 表格显示所有任务的基本信息
+- **AND** 文案内容列使用 ellipsis 截断过长文本
+- **AND** 状态列使用彩色标签显示
+- **AND** 进度列显示进度条和百分比
+
+### Requirement: 任务状态管理
+
+数字人任务 SHALL 支持以下状态：
+
+状态定义：
+- `pending`：等待处理
+- `running`：处理中
+- `success`：已完成
+- `failed`：失败
+- `canceled`：已取消
+
+#### Scenario: 显示任务状态
+- **WHEN** 渲染任务列表中的状态列
+- **THEN** 根据任务状态显示对应颜色的标签
+- **AND** 状态标签文本为中文描述
+- **AND** 状态颜色映射：
+  - pending：灰色
+  - running：蓝色（带动画效果）
+  - success：绿色
+  - failed：红色
+  - canceled：橙色
+
+### Requirement: 任务操作功能
+
+数字人任务列表 SHALL 支持以下操作：
+
+操作定义：
+- 预览：查看生成结果视频
+- 下载：下载生成的视频文件
+- 删除：删除任务记录
+- 取消：取消正在运行的任务
+- 重试：重新执行失败的任务
+
+#### Scenario: 显示操作按钮
+- **WHEN** 渲染任务列表中的操作列
+- **THEN** 根据状态显示对应的任务操作按钮
+- **AND** 按钮显示规则：
+  - 所有任务：预览、删除
+  - pending/running 任务：取消
+  - success 任务：下载
+  - failed 任务：重试
+
+#### Scenario: 执行预览操作
+- **WHEN** 用户点击「预览」按钮
+- **THEN** 弹出视频预览窗口
+- **AND** 窗口显示生成的结果视频
+- **AND** 提供关闭按钮
+
+#### Scenario: 执行下载操作
+- **WHEN** 用户点击「下载」按钮
+- **THEN** 开始下载生成的视频文件
+- **AND** 文件名为「数字人视频_{任务ID}_{时间戳}.mp4」
+
+#### Scenario: 执行删除操作
+- **WHEN** 用户点击「删除」按钮
+- **THEN** 弹出确认对话框
+- **AND** 用户确认后删除任务
+- **AND** 删除后刷新列表
+
+#### Scenario: 执行取消操作
+- **WHEN** 用户点击「取消」按钮
+- **THEN** 调用取消 API
+- **AND** 任务状态变更为 canceled
+- **AND** 停止状态轮询
+
+#### Scenario: 执行重试操作
+- **WHEN** 用户点击「重试」按钮
+- **THEN** 调用重试 API
+- **AND** 任务状态变更为 pending
+- **AND** 重新开始状态轮询
+
+### Requirement: 筛选和搜索功能
+
+数字人任务列表 SHALL 支持以下筛选条件：
+
+筛选条件：
+- 任务状态：下拉选择（全部/待处理/处理中/已完成/失败）
+- 任务名称：文本搜索（支持模糊匹配）
+- 创建时间：日期范围选择
+
+#### Scenario: 按状态筛选
+- **WHEN** 用户选择任务状态下拉框
+- **THEN** 列表自动刷新，只显示对应状态的任务
+- **AND** 选择「全部状态」时显示所有任务
+
+#### Scenario: 按名称搜索
+- **WHEN** 用户在搜索框输入关键词
+- **AND** 按下回车键或点击搜索按钮
+- **THEN** 列表自动刷新，只显示名称包含关键词的任务
+- **AND** 搜索支持模糊匹配
+
+#### Scenario: 按时间范围筛选
+- **WHEN** 用户选择日期范围
+- **THEN** 列表自动刷新，只显示创建时间在范围内的任务
+- **AND** 日期格式为「YYYY-MM-DD」
+
+### Requirement: 分页功能
+
+数字人任务列表 SHALL 支持分页显示。
+
+分页规范：
+- 每页条数：支持 10/20/50/100 条选项
+- 页码跳转：支持输入页码直接跳转
+- 显示信息：显示「共 X 条记录，第 Y/Z 页」
+
+#### Scenario: 分页导航
+- **WHEN** 任务数量超过每页显示条数
+- **THEN** 表格底部显示分页组件
+- **AND** 用户可以切换页码
+- **AND** 用户可以切换每页条数
+
+### Requirement: 自动状态轮询
+
+数字人任务列表 SHALL 自动轮询正在运行的任务状态。
+
+轮询规范：
+- 轮询间隔：5 秒
+- 轮询范围：只轮询 status 为 pending 或 running 的任务
+- 页面隐藏：暂停轮询
+- 组件销毁：停止轮询
+
+#### Scenario: 自动轮询任务状态
+- **WHEN** 页面显示且有待处理/处理中的任务
+- **THEN** 每 5 秒发起一次 API 请求
+- **AND** 获取任务最新状态
+- **AND** 更新页面显示
+
+#### Scenario: 页面隐藏时暂停轮询
+- **WHEN** 用户切换到其他页面或最小化浏览器
+- **THEN** 暂停状态轮询
+- **AND** 页面重新可见时恢复轮询
+
+#### Scenario: 任务完成时停止轮询
+- **WHEN** 轮询发现任务状态变为 success/failed/canceled
+- **THEN** 从轮询列表中移除该任务
+- **AND** 当所有任务都完成时，停止轮询
+
+### Requirement: API 集成
+
+数字人任务列表 SHALL 集成以下 API：
+
+API 端点：
+- `getDigitalHumanTaskPage`：分页获取任务列表
+- `getDigitalHumanTask`：获取任务详情
+- `cancelTask`：取消任务
+- `retryTask`：重试任务
+- `deleteTask`：删除任务
+
+#### Scenario: 加载任务列表
+- **WHEN** 页面初始加载或筛选条件变化
+- **THEN** 调用 `getDigitalHumanTaskPage(params)`
+- **AND** 解析返回数据并更新表格显示
+
+#### Scenario: 获取任务详情
+- **WHEN** 用户点击预览按钮
+- **THEN** 调用 `getDigitalHumanTask(taskId)`
+- **AND** 根据返回数据显示预览内容
+
+#### Scenario: 取消任务
+- **WHEN** 用户点击取消按钮
+- **THEN** 调用 `cancelTask(taskId)`
+- **AND** 更新任务状态为 canceled
+- **AND** 停止该任务的轮询
+
+#### Scenario: 重试任务
+- **WHEN** 用户点击重试按钮
+- **THEN** 调用 `retryTask(taskId)`
+- **AND** 更新任务状态为 pending
+- **AND** 重新开始轮询
+
+#### Scenario: 删除任务
+- **WHEN** 用户确认删除任务
+- **THEN** 调用 `deleteTask(taskId)`
+- **AND** 从列表中移除该任务
+- **AND** 停止该任务的轮询
+
+### Requirement: 数据模型映射
+
+数字人任务列表 SHALL 使用以下数据模型：
+
+数据模型（基于 `TikDigitalHumanTaskDO`）：
+```typescript
+interface DigitalHumanTask {
+  id: number                    // 任务ID
+  taskName: string             // 任务名称
+  videoFileId: number          // 视频文件ID
+  videoUrl: string             // 视频文件URL
+  inputText: string            // 输入文本
+  voiceId: string              // 音色ID
+  speechRate: number           // 语速
+  emotion?: string             // 情感（可选）
+  instruction?: string         // 指令（可选）
+  status: string               // 任务状态
+  progress: number             // 进度百分比
+  currentStep?: string         // 当前步骤（可选）
+  resultVideoUrl?: string      // 结果视频URL（可选）
+  errorMessage?: string        // 错误信息（可选）
+  createTime: string           // 创建时间
+  finishTime?: string          // 完成时间（可选）
+}
+```
+
+#### Scenario: 映射 API 数据
+- **WHEN** API 返回任务数据
+- **THEN** 将数据映射为本地数据模型
+- **AND** 处理可选字段的空值情况
+- **AND** 格式化时间字段
+
+### Requirement: 错误处理
+
+数字人任务列表 SHALL 提供完善的错误处理机制。
+
+错误处理规范：
+- API 调用失败：显示错误提示和重试按钮
+- 网络异常：显示网络异常提示
+- 操作失败：显示具体错误信息
+- 空数据状态：显示「暂无数据」提示
+
+#### Scenario: API 调用失败
+- **WHEN** 获取任务列表时 API 返回错误
+- **THEN** 显示错误提示信息
+- **AND** 提供「重试」按钮
+- **AND** 用户点击重试后重新发起请求
+
+#### Scenario: 网络异常
+- **WHEN** 网络连接中断
+- **THEN** 显示网络异常提示
+- **AND** 自动检测网络恢复
+- **AND** 网络恢复后提示用户刷新页面
+
+#### Scenario: 操作失败
+- **WHEN** 执行任务操作时失败
+- **THEN** 显示具体错误信息
+- **AND** 提供重试选项
+- **AND** 不关闭对话框（如果适用）
+
+#### Scenario: 空数据状态
+- **WHEN** 任务列表为空
+- **THEN** 显示「暂无数字人任务」提示
+- **AND** 提供「去创建」按钮（如适用）
+
+### Requirement: 加载状态显示
+
+数字人任务列表 SHALL 显示适当的加载状态。
+
+加载状态规范：
+- 初始加载：显示骨架屏或加载动画
+- 数据刷新：显示表格 loading 状态
+- 操作进行：显示按钮 loading 状态
+
+#### Scenario: 初始加载状态
+- **WHEN** 页面首次加载
+- **THEN** 显示骨架屏或加载动画
+- **AND** 加载完成后显示实际内容
+
+#### Scenario: 数据刷新状态
+- **WHEN** 筛选条件变化或分页切换
+- **THEN** 表格显示 loading 状态
+- **AND** 加载完成后更新表格数据
+
+#### Scenario: 操作进行状态
+- **WHEN** 用户执行操作（取消、重试、删除）
+- **THEN** 对应的按钮显示 loading 状态
+- **AND** 操作完成后恢复正常状态
+
+### Requirement: 响应式适配
+
+数字人任务列表 SHALL 支持响应式设计。
+
+适配规范：
+- 桌面端：显示所有列
+- 平板端：隐藏部分次要列
+- 移动端：使用卡片布局或横向滚动
+
+#### Scenario: 平板端适配
+- **WHEN** 在平板设备上访问任务列表
+- **THEN** 隐藏「视频文件」和「音色」列
+- **AND** 保留核心列：ID、任务名称、状态、进度、操作
+
+#### Scenario: 移动端适配
+- **WHEN** 在手机设备上访问任务列表
+- **THEN** 使用卡片布局显示任务信息
+- **AND** 每个卡片包含任务的核心信息和操作按钮
+- **OR** 表格使用横向滚动显示所有列
+
+### Requirement: 性能优化
+
+数字人任务列表 SHALL 实施性能优化措施。
+
+优化措施：
+- 搜索防抖：搜索输入 300ms 后执行
+- 虚拟滚动：数据量 > 1000 条时启用
+- 内存管理：及时清理定时器和事件监听器
+- 图片懒加载：视频缩略图懒加载
+
+#### Scenario: 搜索防抖
+- **WHEN** 用户在搜索框输入内容
+- **THEN** 等待 300ms 无输入后执行搜索
+- **AND** 避免频繁的 API 调用
+
+#### Scenario: 虚拟滚动
+- **WHEN** 任务列表数据量超过 1000 条
+- **THEN** 启用虚拟滚动功能
+- **AND** 只渲染可见区域的行
+- **AND** 提升大数据量时的渲染性能