TrueGrowth/specs/001-batch-task-queue/spec.md

# 功能规格说明：内容生成批量任务队列

**功能分支**: `001-batch-task-queue`  
**创建日期**: 2025-11-22  
**状态**: 草稿  
**输入**: 用户描述: "增加批量任务支持.图片或视频,点击生成之后,创建一个前端任务,后台进行生成.表单恢复初始状态,可以继续创建新的生成任务"

## 澄清记录

### 会话 2025-11-22

- Q: 当后台 AI 生成服务（图片/视频生成 API）完全不可用或响应超时时，系统应如何处理已排队的任务？ → A: 使用指数退避策略自动重试（例如：1分钟、5分钟、15分钟），超过最大重试次数（如3次）后标记为失败
- Q: 每个用户的任务队列应该有容量限制吗？ → A: 无限制，允许用户提交任意数量的任务
- Q: 对于图片和视频生成任务，系统应该设置多长的超时时间，超过这个时间后将任务标记为失败？ → A: 长超时（图片 10 分钟，视频 30 分钟）
- Q: 任务数据（队列、状态、参数、结果）应该存储在哪里以确保跨会话持久化？ → A: 仅浏览器本地存储（LocalStorage 或 IndexedDB）
- Q: 任务队列应该如何呈现给用户，以便用户可以方便地监控和管理任务？ → A: 页面底部固定工具栏，显示任务摘要，点击展开完整队列

## 用户场景与测试 *(必填)*

### 用户故事 1 - 提交内容生成任务 (优先级: P1)

用户需要提交图片或视频生成请求，而无需等待生成完成，从而可以继续处理其他任务或连续提交多个请求。

**优先级理由**: 这是实现异步内容生成的核心功能。没有这个功能，用户在内容生成期间会被阻塞，完全无法进行批量操作。

**独立测试**: 可以通过提交单个生成请求、验证任务出现在队列中、确认表单重置来完整测试。通过解放用户无需等待即可立即交付价值。

**验收场景**:

1. **假设** 用户已填写图片生成表单，**当** 用户点击"生成"，**那么** 创建一个任务并出现在任务队列中，表单重置为初始状态
2. **假设** 用户已填写视频生成表单，**当** 用户点击"生成"，**那么** 创建一个任务并出现在任务队列中，表单重置为初始状态
3. **假设** 生成任务已提交，**当** 用户查看任务队列，**那么** 任务显示为"待处理"或"处理中"状态
4. **假设** 表单已提交，**当** 表单重置，**那么** 所有字段恢复为默认值，用户可以立即创建新任务
5. **假设** 用户提交任务，**当** 队列中已有大量任务，**那么** 新任务仍然可以成功添加到队列，无容量限制阻止
6. **假设** 任务已创建，**当** 任务添加到队列，**那么** 页面底部工具栏显示任务摘要（例如："3 个任务处理中"）

---

### 用户故事 2 - 监控任务进度 (优先级: P2)

用户需要跟踪已提交生成任务的状态，以便知道内容何时准备就绪或任务是否失败。

**优先级理由**: 对用户感知和任务管理至关重要，但用户仍然可以在没有全面监控的情况下提交任务。

**独立测试**: 可以通过提交任务并验证状态更新在任务列表中正确显示来测试。通过提供生成进度的可见性来交付价值。

**验收场景**:

1. **假设** 用户已提交多个任务，**当** 用户查看任务队列，**那么** 所有任务都显示其当前状态（待处理、处理中、已完成、失败）
2. **假设** 任务正在处理中，**当** 生成成功完成，**那么** 任务状态更新为"已完成"，生成的内容变为可访问
3. **假设** 任务正在处理中，**当** 生成失败，**那么** 任务状态更新为"失败"，并显示解释问题的错误消息
4. **假设** 任务处于各种状态，**当** 用户刷新页面，**那么** 所有任务状态从浏览器本地存储恢复并保持准确
5. **假设** 后台生成服务不可用，**当** 任务自动重试，**那么** 用户在任务详情中看到重试计数和下次重试时间
6. **假设** 图片生成任务处理超过 10 分钟，**当** 达到超时限制，**那么** 任务被标记为失败并显示超时错误消息
7. **假设** 视频生成任务处理超过 30 分钟，**当** 达到超时限制，**那么** 任务被标记为失败并显示超时错误消息
8. **假设** 用户查看底部工具栏，**当** 点击任务摘要区域，**那么** 完整的任务队列展开显示，包含所有任务的详细信息
9. **假设** 任务队列已展开，**当** 用户再次点击或点击关闭按钮，**那么** 队列收起，仅显示摘要信息

---

### 用户故事 3 - 访问生成的内容 (优先级: P2)

用户需要检索和使用已完成生成任务的内容。

**优先级理由**: 对任务价值交付至关重要，但优先级略低于监控，因为用户需要先知道任务完成才能访问结果。

**独立测试**: 可以通过完成生成任务并验证用户可以下载或插入生成的内容来测试。通过提供最终输出来交付价值。

**验收场景**:

1. **假设** 任务已成功完成，**当** 用户查看已完成的任务，**那么** 用户可以预览生成的图片或视频
2. **假设** 已完成的任务包含生成的内容，**当** 用户点击下载/插入操作，**那么** 内容可在白板中使用或保存到设备
3. **假设** 存在多个已完成的任务，**当** 用户浏览已完成的任务，**那么** 用户可以轻松识别和访问每个生成的内容
4. **假设** 任务完成，**当** 底部工具栏显示通知（例如："1 个新任务完成"），**那么** 用户点击可快速访问已完成的内容

---

### 用户故事 4 - 批量提交多个任务 (优先级: P3)

高级用户需要快速连续提交多个生成请求，以批量创建内容。

**优先级理由**: 增强高级工作流的生产力，但建立在 P1 基础之上。一旦实现 P1，用户已经可以顺序提交多个任务。

**独立测试**: 可以通过快速连续提交 5-10 个任务并验证所有任务都正确排队来测试。通过最大化批量操作的吞吐量来交付价值。

**验收场景**:

1. **假设** 用户已提交一个任务，**当** 表单重置，**那么** 用户可以立即修改参数并提交另一个任务，无需延迟
2. **假设** 用户想生成 10 个变体，**当** 用户连续提交任务，**那么** 所有任务按顺序排队和处理
3. **假设** 快速提交多个任务，**当** 查看任务队列，**那么** 所有任务都显示唯一标识符和正确参数

---

### 用户故事 5 - 管理任务队列 (优先级: P3)

用户需要管理任务队列，包括取消待处理任务或清除已完成/失败的任务。

**优先级理由**: 改善用户控制和队列管理，但如果任务能够合理快速完成，用户可以在没有取消功能的情况下运行。

**独立测试**: 可以通过提交任务然后从队列中取消/删除它们来测试。通过让用户控制资源使用来交付价值。

**验收场景**:

1. **假设** 任务待处理或处理中，**当** 用户点击任务的"取消"，**那么** 任务从队列中删除或标记为已取消
2. **假设** 存在多个已完成的任务，**当** 用户点击"清除已完成"，**那么** 所有已完成的任务从可见队列中删除
3. **假设** 队列中存在失败的任务，**当** 用户点击失败任务的"重试"，**那么** 使用相同参数将任务重新提交到队列

---

### 边界情况

- 当用户提交的任务参数无效时会发生什么（例如，缺少必填字段）？系统应在创建任务之前进行验证。
- 当用户在任务处理时关闭浏览器会发生什么？任务数据保存在浏览器本地存储中，当用户返回时从本地存储恢复。
- 当任务处理时间异常长时会发生什么？图片生成任务在 10 分钟后超时，视频生成任务在 30 分钟后超时，超时任务被标记为失败。
- 当多个用户共享同一账户并提交任务时会发生什么？每个用户应看到账户的所有任务，或根据身份验证使任务特定于用户。
- 当生成的内容保存失败时会发生什么？系统应重试保存操作，如果保存继续失败则将任务标记为失败。
- 当用户在队列中有任务时导航离开页面会发生什么？任务通过浏览器本地存储在页面导航之间持久保存。
- 当后台生成服务完全不可用时会发生什么？系统使用指数退避策略自动重试（1分钟、5分钟、15分钟），超过3次重试后标记任务为失败。
- 当用户清除浏览器数据或使用隐私模式时会发生什么？用户将丢失所有任务历史记录和队列数据。

## 需求 *(必填)*

### 功能需求

- **FR-001**: 系统必须在用户为图片或视频内容点击"生成"时创建后台任务
- **FR-002**: 系统必须在任务创建后立即将生成表单重置为初始状态
- **FR-003**: 系统必须允许用户在先前任务处理时提交新的生成任务
- **FR-004**: 系统必须在页面底部显示固定工具栏，显示任务摘要（例如：生成中任务数量、最新状态）
- **FR-005**: 系统必须允许用户点击底部工具栏展开完整的任务队列面板
- **FR-006**: 系统必须在展开的任务队列面板中显示所有用户提交的任务，不设置队列容量上限
- **FR-007**: 系统必须跟踪任务状态，至少包括：待处理、处理中、重试中、已完成和失败状态
- **FR-008**: 系统必须在生成进度推进时实时或近实时更新任务状态
- **FR-009**: 系统必须使用浏览器本地存储（LocalStorage 或 IndexedDB）在页面刷新和浏览器会话之间持久保存任务数据
- **FR-010**: 系统必须为已完成的任务提供对生成内容的访问
- **FR-011**: 系统必须为失败的任务显示错误信息，帮助用户了解出了什么问题
- **FR-012**: 系统必须支持图片和视频生成任务类型
- **FR-013**: 系统必须在后台异步处理任务，不阻塞用户界面
- **FR-014**: 系统必须保留任务参数（提示词、设置等）以供参考和可能的重试
- **FR-015**: 系统必须允许用户取消待处理或处理中的任务
- **FR-016**: 系统必须在短时间窗口内（可配置，例如 5 秒）防止相同参数的重复任务提交
- **FR-017**: 系统必须优雅地处理任务失败，并允许用户使用相同参数重试失败的任务
- **FR-018**: 系统必须在后台生成服务不可用或超时时实施指数退避重试策略，重试间隔为 1 分钟、5 分钟、15 分钟，最多重试 3 次
- **FR-019**: 系统必须在任务详情中显示重试计数和下次重试时间（如适用）
- **FR-020**: 系统必须在达到最大重试次数后将任务标记为失败，并提供清晰的错误消息
- **FR-021**: 系统必须为图片生成任务设置 10 分钟的超时限制，超过此时间将任务标记为失败
- **FR-022**: 系统必须为视频生成任务设置 30 分钟的超时限制，超过此时间将任务标记为失败
- **FR-023**: 系统必须在任务超时时显示明确的超时错误消息，区分于其他类型的失败
- **FR-024**: 系统必须在应用加载时从浏览器本地存储读取任务队列并恢复所有任务状态
- **FR-025**: 系统必须在每次任务状态变化时更新浏览器本地存储以确保数据一致性
- **FR-026**: 系统必须在底部工具栏任务摘要中显示关键信息，包括：生成中任务数量、已完成任务数量、失败任务数量
- **FR-027**: 系统必须允许用户收起展开的任务队列面板，返回到仅显示摘要的状态

### 关键实体

- **生成任务**: 表示单个内容生成请求，包含任务 ID、任务类型（图片/视频）、提交时间戳、状态、生成参数（提示词、设置）、结果引用（URL 或标识符）、错误消息（如果失败）、重试计数、下次重试时间、超时限制（图片 10 分钟，视频 30 分钟）和用户标识符等属性，存储在浏览器本地存储中
- **任务队列**: 用户所有生成任务的集合，按提交时间或优先级排序，具有按状态筛选的能力，无容量限制，持久化在浏览器本地存储中
- **生成内容**: 已完成任务产生的输出工件（图片或视频文件），包含创建时间戳、文件大小、格式以及指向源任务链接等元数据
- **任务工具栏**: 页面底部固定的UI组件，显示任务摘要和快速访问入口，可展开显示完整队列面板

## 成功标准 *(必填)*

### 可衡量的成果

- **SC-001**: 用户可以在点击上一个任务的"生成"后 2 秒内提交新的生成任务
- **SC-002**: 表单在任务提交后 500 毫秒内重置为初始状态
- **SC-003**: 任务队列显示所有任务的当前状态，更新在状态变化后 5 秒内出现
- **SC-004**: 用户可以快速连续成功提交和排队至少 10 个生成任务，无错误
- **SC-005**: 95% 的用户可以在任务完成后 10 秒内找到并访问其生成的内容
- **SC-006**: 任务队列在浏览器会话之间从本地存储持久保存，任务状态和参数 100% 准确
- **SC-007**: 用户可以在 2 秒内完成任务管理操作（取消、重试、清除）
- **SC-008**: 系统处理并发任务，支持至少 5 个同时用户生成内容，性能无下降
- **SC-009**: 当后台服务临时不可用时，90% 的任务在自动重试后成功完成，无需用户干预
- **SC-010**: 系统能够处理每个用户超过 100 个任务的队列，界面响应时间保持在 2 秒内
- **SC-011**: 图片生成任务在 10 分钟内完成或被标记为超时失败，准确率 100%
- **SC-012**: 视频生成任务在 30 分钟内完成或被标记为超时失败，准确率 100%
- **SC-013**: 应用加载时从本地存储恢复任务队列的时间不超过 1 秒
- **SC-014**: 底部工具栏任务摘要在 200 毫秒内响应用户点击并展开队列面板
- **SC-015**: 队列面板展开/收起动画流畅，帧率保持在 60 FPS