sionrui/openspec/changes/refactor-task-management/specs/digital-human-task/spec.md

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）：

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 提升大数据量时的渲染性能