Jammy/TrueGrowth

Fork 0

Files

Jammy 3b6781d695 Initial TrueGrowth source import

2026-07-07 09:36:36 +08:00

36 KiB

Raw Blame History

任务清单：内容生成批量任务队列

功能分支: 001-batch-task-queue
创建日期: 2025-11-22
规格文档: spec.md
实施计划: plan.md

任务摘要

阶段	任务数	预估工时	优先级	状态
阶段 0: 基础设施	8	16-20h	P1	待开始
阶段 1: 任务创建与持久化	10	18-22h	P1	待开始
阶段 2: 任务执行与监控	12	24-28h	P2	待开始
阶段 3: 内容访问与管理	9	16-20h	P2-P3	待开始
阶段 4: 优化与边界情况	8	14-18h	P3	待开始
总计	47	88-108h	-	-

阶段 0: 基础设施 (P1 依赖)

目标

建立核心数据结构、存储服务和任务队列基础逻辑，为后续开发提供稳定的基础设施。

任务列表

Task 0.1: 创建类型定义文件

文件: packages/drawnix/src/types/task.types.ts
预估工时: 2-3h
优先级: P1
依赖: 无

描述: 定义任务队列系统的所有 TypeScript 类型和接口。

验收标准:

定义 TaskStatus 枚举（6 种状态）
定义 TaskType 枚举（image, video）
定义 Task 接口（包含所有必需字段）
定义 TaskResult 接口
定义 TaskError 接口
定义 TaskQueueState 接口
定义 GenerationParams 接口
所有类型添加 JSDoc 注释
TypeScript 编译无错误

关键代码位置:

// task.types.ts
export enum TaskStatus { ... }
export enum TaskType { ... }
export interface Task { ... }
export interface TaskResult { ... }
export interface TaskError { ... }

Task 0.2: 创建生成相关类型定义

文件: packages/drawnix/src/types/generation.types.ts
预估工时: 1-2h
优先级: P1
依赖: 无

描述: 定义 AI 生成服务相关的类型接口。

验收标准:

定义 GenerationRequest 接口
定义 GenerationResponse 接口
定义 GenerationError 接口
添加 JSDoc 注释
TypeScript 编译无错误

Task 0.3: 实现常量定义

文件: packages/drawnix/src/constants/TASK_CONSTANTS.ts
预估工时: 1h
优先级: P1
依赖: Task 0.1

描述: 定义任务队列系统使用的所有常量值。

验收标准:

定义超时时长常量（图片 10min, 视频 30min）
定义重试间隔常量（1min, 5min, 15min）
定义最大重试次数（3 次）
定义防重复提交窗口（5 秒）
定义存储键名常量
定义 IndexedDB 配置常量
使用 UPPER_SNAKE_CASE 命名
添加注释说明每个常量的用途

示例代码:

export const TASK_TIMEOUT = {
  IMAGE: 10 * 60 * 1000, // 10 minutes
  VIDEO: 30 * 60 * 1000, // 30 minutes
} as const;

export const RETRY_DELAYS = [
  1 * 60 * 1000,  // 1 minute
  5 * 60 * 1000,  // 5 minutes
  15 * 60 * 1000, // 15 minutes
] as const;

Task 0.4: 实现 StorageService

文件: packages/drawnix/src/services/storage-service.ts
预估工时: 3-4h
优先级: P1
依赖: Task 0.1, Task 0.3

描述: 封装 localforage，提供任务队列的持久化存储功能。

验收标准:

初始化 IndexedDB 数据库（数据库名: aitu-task-queue）
实现 saveTasks(tasks: Task[]): Promise<void> 方法
实现 loadTasks(): Promise<Task[]> 方法
实现 clearCompletedTasks(): Promise<void> 方法
实现 getStorageSize(): Promise<number> 方法
错误处理和日志记录
支持数据迁移（版本管理）
单文件 < 500 行
单元测试覆盖率 > 80%

关键 API:

class StorageService {
  async saveTasks(tasks: Task[]): Promise<void>
  async loadTasks(): Promise<Task[]>
  async clearCompletedTasks(): Promise<void>
  async getStorageSize(): Promise<number>
}

Task 0.5: 实现重试策略工具函数

文件: packages/drawnix/src/utils/retry-utils.ts
预估工时: 2-3h
优先级: P1
依赖: Task 0.3

描述: 实现指数退避重试策略的计算逻辑。

验收标准:

实现 calculateRetryDelay(retryCount: number): number 函数
实现 shouldRetry(task: Task): boolean 函数
实现 getNextRetryTime(task: Task): number 函数
正确计算重试延迟（1min, 5min, 15min）
最大重试次数限制为 3 次
边界情况处理（retryCount < 0, > 3）
添加 JSDoc 注释
单元测试覆盖率 > 90%

示例代码:

export function calculateRetryDelay(retryCount: number): number {
  if (retryCount < 0 || retryCount >= RETRY_DELAYS.length) {
    return 0;
  }
  return RETRY_DELAYS[retryCount];
}

Task 0.6: 实现任务工具函数

文件: packages/drawnix/src/utils/task-utils.ts
预估工时: 2-3h
优先级: P1
依赖: Task 0.1, Task 0.3

描述: 实现任务相关的工具函数（ID 生成、状态判断、超时检测等）。

验收标准:

实现 generateTaskId(): string (UUID v4)
实现 isTaskActive(task: Task): boolean
实现 isTaskTimeout(task: Task): boolean
实现 getTaskTimeout(taskType: TaskType): number
实现 canRetry(task: Task): boolean
实现 formatTaskDuration(ms: number): string
添加 JSDoc 注释
单元测试覆盖率 > 85%

Task 0.7: 实现参数验证工具

文件: packages/drawnix/src/utils/validation-utils.ts
预估工时: 2h
优先级: P1
依赖: Task 0.1, Task 0.2

描述: 实现生成参数的验证逻辑。

验收标准:

实现 validateGenerationParams(params: GenerationParams): boolean
验证必填字段（prompt）
验证参数范围（width, height, duration）
返回清晰的错误消息
添加 JSDoc 注释
单元测试覆盖率 > 85%

Task 0.8: 实现 TaskQueueService 核心服务

文件: packages/drawnix/src/services/task-queue-service.ts
预估工时: 4-5h
优先级: P1
依赖: Task 0.1-0.7

描述: 实现任务队列的核心业务逻辑，使用单例模式和 RxJS 管理状态。

验收标准:

单例模式实现
使用 RxJS Subject 管理事件流
实现 createTask(params: GenerationParams, type: TaskType): Task
实现 updateTaskStatus(taskId: string, status: TaskStatus): void
实现 getTask(taskId: string): Task | undefined
实现 getAllTasks(): Task[]
实现 cancelTask(taskId: string): void
实现 retryTask(taskId: string): void
实现 clearCompletedTasks(): void
防重复提交检测（5 秒窗口）
发出事件：taskCreated, taskUpdated, taskDeleted
错误处理和日志记录
单文件 < 500 行
单元测试覆盖率 > 80%

关键 API:

class TaskQueueService {
  private static instance: TaskQueueService;
  private tasks: Map<string, Task>;
  private taskUpdates$: Subject<TaskEvent>;
  
  static getInstance(): TaskQueueService;
  createTask(params, type): Task;
  updateTaskStatus(taskId, status): void;
  getTask(taskId): Task | undefined;
  getAllTasks(): Task[];
  observeTaskUpdates(): Observable<TaskEvent>;
}

阶段 1: 任务创建与持久化 (P1)

目标

实现用户创建任务、表单重置、任务持久化和底部工具栏的基本显示功能。

任务列表

Task 1.1: 实现 useTaskStorage Hook

文件: packages/drawnix/src/hooks/useTaskStorage.ts
预估工时: 2-3h
优先级: P1
依赖: Task 0.4, Task 0.8

描述: 封装任务队列与本地存储的同步逻辑。

验收标准:

监听 TaskQueueService 的状态变化
自动将变化写入 IndexedDB
应用启动时从存储恢复任务
防抖处理（避免频繁写入）
错误处理和重试
单文件 < 300 行
单元测试覆盖率 > 75%

关键 API:

export function useTaskStorage() {
  // 自动同步任务到本地存储
  // 应用启动时恢复任务
}

Task 1.2: 实现 useTaskQueue Hook

文件: packages/drawnix/src/hooks/useTaskQueue.ts
预估工时: 3-4h
优先级: P1
依赖: Task 0.8, Task 1.1

描述: 提供 React 组件友好的任务队列状态管理接口。

验收标准:

订阅 TaskQueueService 的事件流
提供 React 状态：tasks, activeTasks, completedTasks, failedTasks
提供操作方法：createTask, cancelTask, retryTask, clearCompleted
自动清理订阅（useEffect cleanup）
性能优化（useMemo, useCallback）
单文件 < 400 行
单元测试覆盖率 > 75%

关键 API:

export function useTaskQueue() {
  return {
    tasks: Task[],
    activeTasks: Task[],
    completedTasks: Task[],
    failedTasks: Task[],
    createTask: (params, type) => void,
    cancelTask: (taskId) => void,
    retryTask: (taskId) => void,
    clearCompleted: () => void,
  };
}

Task 1.3: 实现 TaskSummary 组件

文件: packages/drawnix/src/components/task-queue/TaskSummary.tsx
预估工时: 2h
优先级: P1
依赖: Task 1.2

描述: 显示任务摘要信息（生成中/完成/失败计数）。

验收标准:

显示生成中任务数量
显示已完成任务数量
显示失败任务数量
实时更新（订阅任务状态变化）
使用 TDesign 组件（Badge, Text）
响应式设计（移动端适配）
单文件 < 200 行
组件测试覆盖关键场景

UI 设计:

[生成中: 3] [已完成: 12] [失败: 1]

Task 1.4: 实现 TaskToolbar 组件

文件: packages/drawnix/src/components/task-queue/TaskToolbar.tsx
预估工时: 3-4h
优先级: P1
依赖: Task 1.3

描述: 实现页面底部固定的任务工具栏，显示摘要并支持展开/收起队列面板。

验收标准:

固定在页面底部（CSS: position: fixed; bottom: 0;）
集成 TaskSummary 组件
点击展开/收起任务队列面板
显示新任务完成通知
平滑动画（展开/收起）
使用 TDesign light 主题
响应式设计
单文件 < 300 行
组件测试覆盖点击交互

样式要求:

高度: 56px
背景: 白色，阴影
圆角: 顶部 8px
z-index: 999

Task 1.5: 创建任务队列样式文件

文件: packages/drawnix/src/components/task-queue/task-queue.scss
预估工时: 2-3h
优先级: P1
依赖: 无

描述: 定义任务队列相关组件的 SCSS 样式。

验收标准:

使用 BEM 命名约定
使用 TDesign 设计系统变量
定义 TaskToolbar 样式
定义 TaskSummary 样式
定义展开/收起动画
响应式断点（移动端 < 768px）
支持深色模式（预留变量）
单文件 < 400 行

关键样式:

.task-toolbar {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  height: 56px;
  background: var(--td-bg-color-container);
  box-shadow: var(--td-shadow-3);
  z-index: 999;
  
  &__summary {
    // ...
  }
  
  &--expanded {
    // ...
  }
}

Task 1.6: 修改 CreationToolbar 集成任务创建

文件: packages/drawnix/src/components/toolbar/creation-toolbar.tsx
预估工时: 3-4h
优先级: P1
依赖: Task 1.2

描述: 在现有的创建工具栏中集成任务队列功能，支持异步提交任务。

验收标准:

引入 useTaskQueue Hook
"生成"按钮点击时创建任务（不等待完成）
表单在 500ms 内重置为初始状态
参数验证（使用 validation-utils）
防重复提交（5 秒窗口）
显示提交成功提示
错误处理和提示
保持原有功能不受影响
单文件 < 500 行（如超限则拆分）
组件测试覆盖表单重置

关键变更:

const handleGenerate = useCallback(async () => {
  // 验证参数
  if (!validateGenerationParams(params)) {
    showError('参数无效');
    return;
  }
  
  // 创建任务
  const task = createTask(params, type);
  
  // 重置表单
  resetForm();
  
  // 显示提示
  showSuccess('任务已添加到队列');
}, [params, type, createTask, resetForm]);

Task 1.7: 集成任务队列到主应用

文件: packages/drawnix/src/drawnix.tsx
预估工时: 2-3h
优先级: P1
依赖: Task 1.1, Task 1.4

描述: 在主应用组件中集成任务队列上下文和 UI。

验收标准:

添加 TaskToolbar 组件到应用底部
初始化 useTaskStorage（恢复任务）
处理应用卸载时的清理
不影响现有功能
单文件 < 500 行（如超限则拆分）

关键变更:

function Drawnix() {
  useTaskStorage(); // 初始化存储同步
  
  return (
    <div className="drawnix">
      {/* 现有内容 */}
      <TaskToolbar />
    </div>
  );
}

Task 1.8: 编写阶段 1 单元测试

文件:

tests/unit/useTaskQueue.spec.ts
tests/unit/useTaskStorage.spec.ts
tests/unit/TaskToolbar.spec.tsx
tests/unit/TaskSummary.spec.tsx

预估工时: 3-4h
优先级: P1
依赖: Task 1.1-1.7

描述: 编写阶段 1 的单元测试。

验收标准:

useTaskQueue: 测试所有方法和状态
useTaskStorage: 测试存储同步逻辑
TaskToolbar: 测试展开/收起交互
TaskSummary: 测试摘要计算和显示
测试覆盖率 > 75%
所有测试通过

Task 1.9: 编写阶段 1 集成测试

文件: tests/integration/task-creation-flow.spec.ts
预估工时: 2-3h
优先级: P1
依赖: Task 1.8

描述: 测试任务创建的完整流程。

验收标准:

测试从表单提交到任务创建的完整流程
测试表单重置逻辑
测试任务持久化和恢复
测试防重复提交
所有测试通过

Task 1.10: 阶段 1 验收与优化

预估工时: 2h
优先级: P1
依赖: Task 1.1-1.9

描述: 验收阶段 1 的成果，进行必要的优化和修复。

验收标准:

用户可以提交生成任务
表单在 500ms 内重置
TaskToolbar 正确显示任务摘要
刷新页面后任务恢复
所有测试通过
性能目标达成（任务创建 < 200ms）
代码审查通过
文档更新

阶段 2: 任务执行与监控 (P2)

目标

实现任务的自动执行、状态监控、重试机制和队列面板的展开显示功能。

任务列表

Task 2.1: 实现 GenerationAPIService

文件: packages/drawnix/src/services/generation-api-service.ts
预估工时: 3-4h
优先级: P2
依赖: Task 0.2

描述: 封装 AI 生成服务的 API 调用逻辑（初期使用模拟数据）。

验收标准:

实现 generate(params: GenerationParams, type: TaskType): Promise<TaskResult>
支持取消请求（AbortController）
处理超时（fetch timeout）
处理网络错误
返回标准化响应格式
模拟延迟（图片 2-5s, 视频 5-10s）
模拟失败场景（10% 概率）
错误日志记录
单文件 < 400 行
单元测试覆盖率 > 75%

关键 API:

class GenerationAPIService {
  async generate(
    params: GenerationParams,
    type: TaskType,
    signal?: AbortSignal
  ): Promise<TaskResult>
  
  cancelRequest(taskId: string): void
}

Task 2.2: 实现 useRetryStrategy Hook

文件: packages/drawnix/src/hooks/useRetryStrategy.ts
预估工时: 2-3h
优先级: P2
依赖: Task 0.5

描述: 封装重试策略逻辑，管理重试定时器。

验收标准:

计算下次重试时间
管理重试定时器
支持取消重试
指数退避策略（1min, 5min, 15min）
最大重试 3 次
自动清理定时器
单文件 < 300 行
单元测试覆盖率 > 80%

关键 API:

export function useRetryStrategy(task: Task, onRetry: () => void) {
  return {
    scheduleRetry: () => void,
    cancelRetry: () => void,
    nextRetryAt: number | null,
  };
}

Task 2.3: 实现 useTaskExecutor Hook

文件: packages/drawnix/src/hooks/useTaskExecutor.ts
预估工时: 4-5h
优先级: P2
依赖: Task 2.1, Task 2.2

描述: 管理单个任务的执行生命周期，包括执行、超时检测、重试等。

验收标准:

监听 pending 状态任务，自动开始执行
调用 GenerationAPIService 执行生成
超时检测（图片 10min, 视频 30min）
失败后触发重试策略
更新任务状态（processing, completed, failed, retrying）
保存执行结果或错误信息
支持取消执行
清理定时器和请求
单文件 < 400 行
单元测试覆盖率 > 75%

关键 API:

export function useTaskExecutor() {
  // 自动监听并执行 pending 任务
  // 处理超时、重试、状态更新
}

Task 2.4: 实现 TaskItem 组件

文件: packages/drawnix/src/components/task-queue/TaskItem.tsx
预估工时: 3-4h
优先级: P2
依赖: Task 1.2

描述: 显示单个任务的详细信息和操作按钮。

验收标准:

显示任务类型图标（图片/视频）
显示任务参数摘要（prompt 前 50 字符）
显示任务状态标签（不同颜色）
显示创建时间和执行时长
显示重试计数和下次重试时间（retrying 状态）
显示错误消息（failed 状态）
操作按钮：取消（processing）、重试（failed）、删除（completed/failed）、下载（completed）
实时状态更新
使用 TDesign 组件（Card, Tag, Button, Tooltip）
单文件 < 400 行
组件测试覆盖所有状态和操作

UI 设计:

┌─────────────────────────────────────────────────┐
│ [图片] 生成一只可爱的猫咪...           [处理中] │
│ 创建时间: 2分钟前 | 执行时长: 1分23秒           │
│ [取消]                                          │
└─────────────────────────────────────────────────┘

Task 2.5: 实现 TaskQueuePanel 组件

文件: packages/drawnix/src/components/task-queue/TaskQueuePanel.tsx
预估工时: 4-5h
优先级: P2
依赖: Task 2.4

描述: 实现可展开/收起的任务队列面板，显示所有任务列表。

验收标准:

展开/收起动画（60 FPS）
显示所有任务（使用 TaskItem 组件）
支持按状态筛选（全部/待处理/处理中/已完成/失败）
虚拟滚动支持（100+ 任务）
空状态提示（无任务时）
批量操作按钮（清除已完成、清除失败）
使用 TDesign 组件（Tabs, Button, VirtualList）
响应式设计
单文件 < 450 行
组件测试覆盖展开/收起和筛选

UI 设计:

┌─────────────────────────────────────────────────┐
│ [全部 | 待处理 | 处理中 | 已完成 | 失败]  [清除] │
├─────────────────────────────────────────────────┤
│ <TaskItem />                                    │
│ <TaskItem />                                    │
│ <TaskItem />                                    │
│ ...                                             │
└─────────────────────────────────────────────────┘

Task 2.6: 集成 TaskExecutor 到主应用

文件: packages/drawnix/src/drawnix.tsx
预估工时: 2h
优先级: P2
依赖: Task 2.3

描述: 在主应用中初始化任务执行器。

验收标准:

添加 useTaskExecutor Hook
应用启动时自动执行待处理任务
不影响现有功能
单文件 < 500 行

Task 2.7: 更新 TaskToolbar 集成队列面板

文件: packages/drawnix/src/components/task-queue/TaskToolbar.tsx
预估工时: 2-3h
优先级: P2
依赖: Task 2.5

描述: 在 TaskToolbar 中集成 TaskQueuePanel，实现展开/收起功能。

验收标准:

点击工具栏展开/收起面板
展开状态管理
平滑动画过渡
点击外部区域收起面板
单文件 < 400 行
组件测试覆盖展开/收起交互

Task 2.8: 实现超时检测逻辑

文件: packages/drawnix/src/hooks/useTaskExecutor.ts（修改）
预估工时: 2h
优先级: P2
依赖: Task 2.3

描述: 在任务执行器中添加超时检测和处理。

验收标准:

图片任务超时时间: 10 分钟
视频任务超时时间: 30 分钟
超时后标记任务为 failed
错误消息明确标注"超时"
清理定时器
单元测试覆盖超时场景

Task 2.9: 更新样式文件（阶段 2）

文件: packages/drawnix/src/components/task-queue/task-queue.scss（修改）
预估工时: 2-3h
优先级: P2
依赖: Task 2.4, Task 2.5

描述: 添加 TaskItem 和 TaskQueuePanel 的样式。

验收标准:

TaskItem 样式（不同状态的颜色）
TaskQueuePanel 样式（展开/收起动画）
筛选标签样式
虚拟滚动样式优化
响应式设计
单文件 < 500 行

Task 2.10: 编写阶段 2 单元测试

文件:

tests/unit/GenerationAPIService.spec.ts
tests/unit/useRetryStrategy.spec.ts
tests/unit/useTaskExecutor.spec.ts
tests/unit/TaskItem.spec.tsx
tests/unit/TaskQueuePanel.spec.tsx

预估工时: 4-5h
优先级: P2
依赖: Task 2.1-2.9

描述: 编写阶段 2 的单元测试。

验收标准:

测试覆盖率 > 75%
测试所有重试场景
测试超时场景
测试状态更新
所有测试通过

Task 2.11: 编写阶段 2 集成测试

文件: tests/integration/task-execution-flow.spec.ts
预估工时: 3-4h
优先级: P2
依赖: Task 2.10

描述: 测试任务执行的完整流程。

验收标准:

测试任务自动执行
测试状态实时更新
测试失败重试流程
测试超时处理
测试取消任务
所有测试通过

Task 2.12: 阶段 2 验收与优化

预估工时: 2-3h
优先级: P2
依赖: Task 2.1-2.11

描述: 验收阶段 2 的成果，进行必要的优化。

验收标准:

任务自动执行
状态实时更新（< 5s）
失败任务自动重试（指数退避）
超时任务正确处理
展开/收起动画流畅（60 FPS）
所有测试通过
性能目标达成
代码审查通过

阶段 3: 内容访问与管理 (P2-P3)

目标

实现生成内容的预览、下载、插入功能，以及任务的手动管理操作。

任务列表

Task 3.1: 实现内容预览功能

文件: packages/drawnix/src/components/task-queue/TaskItem.tsx（修改）
预估工时: 2-3h
优先级: P2
依赖: Task 2.4

描述: 在 TaskItem 中添加预览功能，支持图片和视频的快速预览。

验收标准:

已完成任务显示预览缩略图
点击缩略图打开全屏预览
图片预览使用 TDesign ImageViewer
视频预览使用 HTML5 video 元素
关闭预览快捷键（ESC）
单文件 < 450 行
组件测试覆盖预览交互

Task 3.2: 实现下载功能

文件: packages/drawnix/src/utils/download-utils.ts（新增）
预估工时: 2h
优先级: P2
依赖: 无

描述: 实现生成内容的下载功能。

验收标准:

实现 downloadFile(url: string, filename: string): void
支持图片格式（PNG, JPG, WebP）
支持视频格式（MP4, WebM）
使用 blob 下载
自动生成文件名（包含时间戳）
错误处理
单元测试覆盖率 > 80%

Task 3.3: 实现插入白板功能

文件: packages/drawnix/src/utils/board-utils.ts（新增）
预估工时: 3-4h
优先级: P2
依赖: 无

描述: 实现将生成内容插入到白板的功能。

验收标准:

实现 insertImageToBoard(imageUrl: string): void
实现 insertVideoToBoard(videoUrl: string): void（如支持）
与 Plait 框架集成
插入到当前视口中心
自动选中插入的元素
错误处理
单元测试覆盖率 > 75%

Task 3.4: 在 TaskItem 中集成下载和插入

文件: packages/drawnix/src/components/task-queue/TaskItem.tsx（修改）
预估工时: 2h
优先级: P2
依赖: Task 3.2, Task 3.3

描述: 在 TaskItem 中添加下载和插入按钮。

验收标准:

已完成任务显示"下载"和"插入"按钮
点击"下载"触发文件下载
点击"插入"将内容插入白板
操作成功后显示提示
错误处理和提示
单文件 < 500 行
组件测试覆盖下载和插入操作

Task 3.5: 实现任务取消功能

文件: packages/drawnix/src/services/task-queue-service.ts（修改）
预估工时: 2h
优先级: P2
依赖: Task 0.8, Task 2.1

描述: 实现取消待处理或处理中任务的功能。

验收标准:

更新 cancelTask(taskId) 方法
取消 API 请求（GenerationAPIService）
更新任务状态为 cancelled
清理定时器
发出 taskUpdated 事件
单元测试覆盖取消场景

Task 3.6: 实现任务重试功能

文件: packages/drawnix/src/hooks/useTaskQueue.ts（修改）
预估工时: 2h
优先级: P2
依赖: Task 1.2

描述: 实现手动重试失败任务的功能。

验收标准:

实现 retryTask(taskId) 方法
重置重试计数
更新状态为 pending
触发自动执行
单元测试覆盖重试场景

Task 3.7: 实现清除任务功能

文件: packages/drawnix/src/hooks/useTaskQueue.ts（修改）
预估工时: 2h
优先级: P3
依赖: Task 1.2

描述: 实现批量清除已完成或失败任务的功能。

验收标准:

实现 clearCompleted() 方法
实现 clearFailed() 方法
从队列和存储中删除任务
显示确认对话框
操作成功后显示提示
单元测试覆盖清除场景

Task 3.8: 实现任务完成通知

文件: packages/drawnix/src/components/task-queue/TaskToolbar.tsx（修改）
预估工时: 2-3h
优先级: P3
依赖: Task 1.4

描述: 在底部工具栏显示新任务完成的通知。

验收标准:

监听任务状态变化
任务完成时显示通知徽章
显示"1 个新任务完成"文本
点击通知展开队列并滚动到该任务
使用 TDesign Notification 组件
自动消失（5 秒后）
组件测试覆盖通知显示

Task 3.9: 阶段 3 验收与优化

预估工时: 2h
优先级: P2-P3
依赖: Task 3.1-3.8

描述: 验收阶段 3 的成果，进行必要的优化。

验收标准:

用户可以预览生成内容
用户可以下载生成内容
用户可以插入内容到白板
用户可以取消任务
用户可以手动重试任务
用户可以清除已完成/失败任务
任务完成通知正常显示
所有测试通过
代码审查通过

阶段 4: 优化与边界情况 (P3)

目标

性能优化、边界情况处理、完善文档和最终验收。

任务列表

Task 4.1: 实现虚拟滚动优化

文件: packages/drawnix/src/components/task-queue/TaskQueuePanel.tsx（修改）
预估工时: 3-4h
优先级: P3
依赖: Task 2.5

描述: 使用虚拟滚动技术优化大量任务（100+）的渲染性能。

验收标准:

使用 TDesign VirtualList 或 react-window
仅渲染可见区域的任务项
100+ 任务时 UI 响应 < 2s
滚动流畅（60 FPS）
支持动态高度（任务项高度不固定）
性能测试验证

Task 4.2: 实现防重复提交检测

文件: packages/drawnix/src/services/task-queue-service.ts（修改）
预估工时: 2h
优先级: P3
依赖: Task 0.8

描述: 增强防重复提交逻辑，防止用户在 5 秒窗口内提交相同参数的任务。

验收标准:

计算参数哈希值
检查 5 秒窗口内是否有相同哈希的任务
重复提交时显示提示
单元测试覆盖防重复场景

Task 4.3: 实现任务按状态筛选

文件: packages/drawnix/src/components/task-queue/TaskQueuePanel.tsx（修改）
预估工时: 2h
优先级: P3
依赖: Task 2.5

描述: 在任务队列面板中添加按状态筛选功能。

验收标准:

筛选选项：全部、待处理、处理中、已完成、失败
使用 TDesign Tabs 组件
实时更新任务计数
筛选逻辑性能优化（useMemo）
组件测试覆盖筛选功能

Task 4.4: 优化 IndexedDB 性能

文件: packages/drawnix/src/services/storage-service.ts（修改）
预估工时: 2-3h
优先级: P3
依赖: Task 0.4

描述: 优化本地存储的性能，减少读写延迟。

验收标准:

批量写入优化（防抖 500ms）
增量更新（仅更新变化的任务）
索引优化（status, createdAt）
读取性能测试（100 任务 < 1s）
写入性能测试（< 100ms）

Task 4.5: 实现容量管理

文件: packages/drawnix/src/services/storage-service.ts（修改）
预估工时: 2h
优先级: P3
依赖: Task 0.4

描述: 监控本地存储容量，防止超限，自动清理旧任务。

验收标准:

监控存储容量使用
接近 50MB 时显示警告
自动清理最旧的已完成/失败任务
保留最近 100 个任务
用户可手动触发清理

Task 4.6: 添加错误边界处理

文件: packages/drawnix/src/components/task-queue/ErrorBoundary.tsx（新增）
预估工时: 2h
优先级: P3
依赖: 无

描述: 添加 React 错误边界，防止任务队列组件崩溃影响主应用。

验收标准:

实现 ErrorBoundary 组件
捕获任务队列组件的错误
显示友好的错误提示
提供重置按钮
错误日志记录
组件测试覆盖错误场景

Task 4.7: 性能测试与优化

文件: tests/performance/task-queue-performance.spec.ts（新增）
预估工时: 3-4h
优先级: P3
依赖: Task 4.1-4.6

描述: 进行全面的性能测试，确保达成所有性能目标。

验收标准:

任务创建响应 < 200ms
表单重置 < 500ms
状态更新延迟 < 5s
工具栏展开/收起 < 200ms, 60 FPS
本地存储读取 < 1s (100 任务)
本地存储写入 < 100ms
100+ 任务 UI 响应 < 2s
所有性能目标达成

Task 4.8: 最终验收与文档完善

预估工时: 3-4h
优先级: P3
依赖: Task 4.1-4.7

描述: 最终验收，完善文档，准备发布。

验收标准:

所有功能需求实现
所有验收场景通过
所有测试通过（单元、集成、E2E）
所有性能目标达成
代码审查通过
更新用户文档
更新开发者文档
更新 CHANGELOG
准备发布说明

任务依赖关系图

阶段 0
  └─ 0.1, 0.2, 0.3 (并行)
  └─ 0.4 ← 0.1, 0.3
  └─ 0.5 ← 0.3
  └─ 0.6 ← 0.1, 0.3
  └─ 0.7 ← 0.1, 0.2
  └─ 0.8 ← 0.1-0.7

阶段 1
  └─ 1.1 ← 0.4, 0.8
  └─ 1.2 ← 0.8, 1.1
  └─ 1.3 ← 1.2
  └─ 1.4 ← 1.3
  └─ 1.5 (并行)
  └─ 1.6 ← 1.2
  └─ 1.7 ← 1.1, 1.4
  └─ 1.8 ← 1.1-1.7
  └─ 1.9 ← 1.8
  └─ 1.10 ← 1.1-1.9

阶段 2
  └─ 2.1 ← 0.2
  └─ 2.2 ← 0.5
  └─ 2.3 ← 2.1, 2.2
  └─ 2.4 ← 1.2
  └─ 2.5 ← 2.4
  └─ 2.6 ← 2.3
  └─ 2.7 ← 2.5
  └─ 2.8 ← 2.3
  └─ 2.9 ← 2.4, 2.5
  └─ 2.10 ← 2.1-2.9
  └─ 2.11 ← 2.10
  └─ 2.12 ← 2.1-2.11

阶段 3
  └─ 3.1 ← 2.4
  └─ 3.2 (并行)
  └─ 3.3 (并行)
  └─ 3.4 ← 3.2, 3.3
  └─ 3.5 ← 0.8, 2.1
  └─ 3.6 ← 1.2
  └─ 3.7 ← 1.2
  └─ 3.8 ← 1.4
  └─ 3.9 ← 3.1-3.8

阶段 4
  └─ 4.1 ← 2.5
  └─ 4.2 ← 0.8
  └─ 4.3 ← 2.5
  └─ 4.4 ← 0.4
  └─ 4.5 ← 0.4
  └─ 4.6 (并行)
  └─ 4.7 ← 4.1-4.6
  └─ 4.8 ← 4.1-4.7

风险管理

高风险任务

任务	风险	缓解措施
Task 0.8	TaskQueueService 复杂度高，可能超过 500 行	早期设计审查，及时拆分子模块
Task 2.3	useTaskExecutor 逻辑复杂，测试困难	使用状态机模式，模拟 API 响应
Task 4.1	虚拟滚动实现复杂	使用成熟库（react-window），留足测试时间
Task 4.4	IndexedDB 性能优化效果不确定	早期性能基准测试，预留优化缓冲

阻塞风险

如果以下任务延期，将阻塞后续阶段：

Task 0.8: 阻塞整个阶段 1 和 2
Task 1.2: 阻塞大部分 UI 组件开发
Task 2.3: 阻塞任务执行功能

应对措施: 优先投入资源到关键路径任务，增加代码审查频率。

测试策略总结

测试覆盖率目标

测试类型	目标覆盖率	关键测试内容
单元测试	> 80%	Services, Hooks, Utils
组件测试	> 75%	所有 UI 组件
集成测试	100% 关键流程	任务创建、执行、管理
E2E 测试	100% 用户场景	5 个核心用户故事

关键测试场景

任务创建流程: 表单提交 → 任务创建 → 表单重置 → 持久化
任务执行流程: 自动执行 → 状态更新 → 完成/失败处理
任务重试流程: 失败 → 延迟重试 → 最终失败
任务管理流程: 取消 → 重试 → 清除
存储恢复流程: 刷新页面 → 从 IndexedDB 恢复 → 状态同步

发布计划

里程碑

里程碑	完成条件	预计时间
M1: 基础设施完成	阶段 0 所有任务完成	Week 1
M2: 任务创建完成	阶段 1 所有任务完成	Week 2-3
M3: 任务执行完成	阶段 2 所有任务完成	Week 4-5
M4: 功能完整	阶段 3 所有任务完成	Week 6
M5: 生产就绪	阶段 4 所有任务完成	Week 7

发布策略

内部测试 (Week 7): 开发团队内部测试
Beta 测试 (Week 8): 邀请 10-20 名用户测试
灰度发布 (Week 9):
- 10% 用户（1-2 天）
- 50% 用户（3-4 天）
- 100% 用户（第 5 天）
正式发布 (Week 10): 全量发布，发布公告

后续优化任务

以下功能不在当前 MVP 范围内，留待后续迭代：

短期优化 (1-3 个月)

任务优先级支持
任务执行进度条
任务分组和标签
批量下载功能
导出任务历史

中期优化 (3-6 个月)

任务模板功能
任务统计和分析
多语言支持
键盘快捷键
无障碍访问优化

长期优化 (6-12 个月)

服务器端持久化（可选）
多设备同步
协作队列（多用户共享）
任务调度优化（优先级队列）
Webhook 集成

文档版本: 1.0
最后更新: 2025-11-22
维护者: 开发团队

36 KiB Raw Blame History Unescape Escape

任务清单：内容生成批量任务队列

任务摘要

阶段 0: 基础设施 (P1 依赖)

目标

任务列表

Task 0.1: 创建类型定义文件

Task 0.2: 创建生成相关类型定义

Task 0.3: 实现常量定义

Task 0.4: 实现 StorageService

Task 0.5: 实现重试策略工具函数

Task 0.6: 实现任务工具函数

Task 0.7: 实现参数验证工具

Task 0.8: 实现 TaskQueueService 核心服务

阶段 1: 任务创建与持久化 (P1)

目标

任务列表

Task 1.1: 实现 useTaskStorage Hook

Task 1.2: 实现 useTaskQueue Hook

Task 1.3: 实现 TaskSummary 组件

Task 1.4: 实现 TaskToolbar 组件

Task 1.5: 创建任务队列样式文件

Task 1.6: 修改 CreationToolbar 集成任务创建

Task 1.7: 集成任务队列到主应用

Task 1.8: 编写阶段 1 单元测试

Task 1.9: 编写阶段 1 集成测试

Task 1.10: 阶段 1 验收与优化

阶段 2: 任务执行与监控 (P2)

目标

任务列表

Task 2.1: 实现 GenerationAPIService

Task 2.2: 实现 useRetryStrategy Hook

Task 2.3: 实现 useTaskExecutor Hook

Task 2.4: 实现 TaskItem 组件

Task 2.5: 实现 TaskQueuePanel 组件

Task 2.6: 集成 TaskExecutor 到主应用

Task 2.7: 更新 TaskToolbar 集成队列面板

Task 2.8: 实现超时检测逻辑

Task 2.9: 更新样式文件（阶段 2）

Task 2.10: 编写阶段 2 单元测试

Task 2.11: 编写阶段 2 集成测试

Task 2.12: 阶段 2 验收与优化

阶段 3: 内容访问与管理 (P2-P3)

目标

任务列表

Task 3.1: 实现内容预览功能

Task 3.2: 实现下载功能

Task 3.3: 实现插入白板功能

Task 3.4: 在 TaskItem 中集成下载和插入

Task 3.5: 实现任务取消功能

Task 3.6: 实现任务重试功能

Task 3.7: 实现清除任务功能

Task 3.8: 实现任务完成通知

Task 3.9: 阶段 3 验收与优化

阶段 4: 优化与边界情况 (P3)

目标

任务列表

Task 4.1: 实现虚拟滚动优化

Task 4.2: 实现防重复提交检测

Task 4.3: 实现任务按状态筛选

Task 4.4: 优化 IndexedDB 性能

Task 4.5: 实现容量管理

Task 4.6: 添加错误边界处理

Task 4.7: 性能测试与优化

Task 4.8: 最终验收与文档完善

任务依赖关系图

风险管理

高风险任务

阻塞风险

测试策略总结

测试覆盖率目标

关键测试场景

发布计划

里程碑

发布策略

后续优化任务

短期优化 (1-3 个月)

中期优化 (3-6 个月)

长期优化 (6-12 个月)

36 KiB

Raw Blame History