# 混剪场景编排功能重新设计 - 任务清单

## 任务列表

### 阶段一：需求分析与设计

#### 任务 1.1：需求确认
- [x] 确认用户对多候选场景模式的具体需求
- [x] 明确每个场景的默认候选数量和最大限制（1-10个）
- [x] 确认两层随机选择算法：
  - 第一层：从每个场景的候选中随机选择一个素材
  - 第二层：对选中的素材使用随机起点
- [x] 确认随机选择算法要求（确定性随机，基于场景索引）

#### 任务 1.2：数据结构设计
- [x] 设计前端场景数据结构：`{index: [{fileId, duration, candidates, fileUrl, fileDuration}]}`
- [x] 设计后端 API 数据结构：`List<SceneConfig>`
- [x] 定义防重复验证规则（同一场景内不重复）

#### 任务 1.3：API 接口设计
- [x] 设计新的创建混剪任务 API（支持scenes格式）
- [x] 定义场景配置数据结构（SceneConfig内部类）
- [x] 确认向后兼容性（保留materials字段）

### 阶段二：前端实现

#### 任务 2.1：Mix.vue 组件重构
- [x] **修改场景数据结构**：
  - 将 `scenes` 从 `Array<{fileId, fileUrl}>` 改为 `Array<{index, duration, candidates: Array<Material>}>`
  - 更新场景初始化逻辑
  - 修改场景数组监听器（watch）
- [x] **更新场景格子 UI**：
  - 添加候选数量徽标（badge）：显示 `候选 X/10`
  - 更新场景格子样式：纵向布局，空态显示
  - 添加候选预览：卡片形式展示候选缩略图
  - 添加移除功能：支持点击移除候选
- [x] **实现候选选择弹窗**：
  - 创建候选选择器：使用现有文件选择弹窗
  - 弹窗内容：场景信息 + 素材库网格 + 操作按钮
  - 支持多选：批量选择功能
  - 显示已选状态：实时更新候选列表

#### 任务 2.2：交互逻辑实现
- [x] **实现场景候选的添加/删除功能**：
  - `addCandidateToScene(sceneIndex, material)`：添加候选到指定场景
  - `removeCandidateFromScene(sceneIndex, candidateIndex)`：从场景移除候选
  - `clearScene(sceneIndex)`：清空指定场景的所有候选
  - `selectFileForScene(file, sceneIndex)`：选择文件添加到场景
- [x] **实现防重复验证**：
  - `isCandidateDuplicate(sceneIndex, fileId)`：检查候选是否重复
  - 前端实时检查：在选择素材时即时验证
  - 视觉反馈：已选择的素材显示禁用状态
  - 提示信息：重复选择时显示警告提示
- [x] **优化一键填充功能**：
  - **实现三种填充策略**：
    - `EMPTY_ONLY`：仅填充空场景（默认）
    - `SUPPLEMENT`：补充不足场景到目标数量
    - `FULL_FILL`：全量重新填充所有场景
  - **重构 `autoFillScenes()` 方法**：
    - 收集所有可用素材，过滤已使用素材
    - 实现Fisher-Yates洗牌算法进行随机选择
    - 支持基于场景索引的确定性随机种子
    - 动态调整目标候选数量（根据素材库总量）
    - 实时更新已使用素材列表，避免跨场景重复
  - **实现 `randomlySelectMaterials()` 工具函数**：
    - 支持指定选择数量和随机种子
    - 确保选择结果可重现（相同种子相同结果）
    - 优化性能：避免重复洗牌相同素材池
  - **添加用户体验优化**：
    - 填充进度提示（进度条或加载动画）
    - 填充结果反馈（显示"已为X个场景填充Y个候选"）
    - 支持一键撤销最近的填充操作
    - 智能建议：根据素材库情况推荐最佳策略

#### 任务 2.3：UI/UX 优化
- [x] **设计候选列表展示方式**：
  - 纵向布局：每个场景独立显示，标题在上方
  - 候选列表：卡片形式展示所有候选缩略图
  - 缩略图展示：每个候选显示缩略图 + 文件名
- [x] **添加候选数量提示**：
  - 场景格子上方显示徽标：`候选 3/10`
  - 颜色编码：0个（灰色）、1-3个（黄色）、4-10个（绿色）
  - 空态显示：大号加号图标 + "点击添加候选"文字
- [x] **实现候选使用状态可视化**：
  - 候选卡片：带阴影的卡片样式
  - 悬停效果：鼠标悬停时卡片放大 + 阴影加深
  - 移除功能：支持点击移除候选
- [x] **优化移动端适配**：
  - 响应式布局：移动端自适应宽度
  - 触摸优化：支持触摸操作
  - 性能优化：CSS Flexbox高效渲染

#### 任务 2.4：数据处理
- [x] **更新表单数据处理逻辑**：
  - 修改 `formData` 结构：移除单个素材相关字段
  - 更新场景计算：`sceneCount`、`filledCount`
  - 调整提交检查逻辑：验证每个场景至少有一个候选
- [x] **实现候选数据的序列化/反序列化**：
  - 场景数据持久化：保存到 Vue 响应式数据
  - 数据格式转换：新旧格式兼容处理
  - 状态恢复：页面刷新后保持场景配置
- [x] **更新提交前的数据验证**：
  - 验证场景完整性：每个场景至少 1 个候选
  - 验证候选数量：每个场景最多 10 个候选
  - 验证总时长：计算总时长并检查范围
  - 验证素材有效性：检查 fileId 和 fileUrl 是否有效

### 阶段三：后端实现

#### 任务 3.1：API 对象修改
- [x] 更新 `MixTaskSaveReqVO.MaterialItem` 结构
- [x] 添加场景配置对象：`SceneConfig`（内部类）
- [x] 更新请求/响应 VO（添加 scenes 字段，保留 materials 字段）

#### 任务 3.2：混剪服务逻辑修改
- [x] 更新 `MixTaskServiceImpl.submitToICE()` 方法
- [x] 修改场景数据解析逻辑（支持新旧格式）
- [x] 实现随机选择算法（`selectRandomMaterialsFromScenes()`）

#### 任务 3.3：批量处理优化
- [x] 实现两层随机选择逻辑：
  - 第一层：从每个场景的候选中随机选择素材
  - 第二层：对选中素材应用随机起点（保留 [x] 修改原有逻辑）
- `BatchProduceAlignment.produceSingleVideoWithOffset()` 调用
- [x] 调整随机种子算法（基于 videoIndex、sceneIndex）

#### 任务 3.4：数据验证
- [x] 添加场景候选数量验证（`validateScenesFormat()`）
- [x] 实现候选视频有效性检查（`validateMaterialsFormat()`）
- [x] 添加总时长验证（保留 `validateDuration()` 方法）

### 阶段四：测试与验证

#### 任务 4.1：单元测试
- [x] 测试前端场景数据处理
- [x] 测试后端 API 数据解析
- [x] 测试随机选择算法（确定性随机验证）

#### 任务 4.2：集成测试
- [x] 测试完整的混剪流程
- [x] 测试批量混剪功能
- [x] 测试各种边界情况

#### 任务 4.3：性能测试
- [x] 测试大量候选场景的性能
- [x] 测试批量混剪的响应时间
- [x] 测试内存使用情况

#### 任务 4.4：用户验收测试
- [x] 验证功能完整性
- [x] 验证操作便捷性
- [x] 收集用户反馈

### 阶段五：文档与发布

#### 任务 5.1：文档更新
- [x] 更新 API 文档（MixTaskSaveReqVO.java Swagger注释）
- [x] 更新用户使用指南（实施摘要文档）
- [x] 添加开发者文档（样式更新说明）

#### 任务 5.2：代码审查
- [x] 代码质量检查（前端Vue组件、后端Java代码）
- [x] 安全性审查（数据验证、输入校验）
- [x] 性能优化审查（两层随机算法优化）

#### 任务 5.3：部署准备
- [x] 准备发布说明（IMPLEMENTATION_SUMMARY.md）
- [x] 配置部署脚本（通过OpenSpec管理）
- [x] 准备回滚方案（保持向后兼容）

## 任务依赖关系

### 关键路径
1. **需求确认** → **数据结构设计** → **API 设计**
2. **API 设计** → **前端实现** → **后端实现**
3. **前后端实现** → **集成测试** → **发布**

### 并行任务
- 任务 2.1（前端组件重构）和 任务 3.1（API 对象修改）可以并行进行
- 任务 4.1（单元测试）和任务 4.2（集成测试）可以并行进行

## 验收标准

### 功能验收
- [x] 每个场景可以添加多个候选视频（1-10个）
- [x] 同一场景内候选视频不重复
- [x] 一键填充功能正常（修复数组初始化问题）
- [x] 批量混剪时从候选中随机选择（两层随机算法）
- [x] UI 展示清晰，操作流畅（纵向布局，空态优化）

### 性能验收
- [x] 场景加载时间 < 2 秒（Vue响应式数据）
- [x] 混剪任务创建响应时间 < 3 秒（优化随机算法）
- [x] 批量混剪性能无明显下降（保持原有第二层随机）

### 代码验收
- [x] 代码质量良好（前端Vue 3 + 后端Java）
- [x] 无严重代码质量问题（遵循项目规范）
- [x] 关键逻辑有充分注释（算法实现详细说明）

## 风险缓解

### 技术风险
- **风险**：修改涉及多个文件，可能引入 Bug
- **缓解**：充分的单元测试和集成测试

### 兼容性风险
- **风险**：修改 API 结构可能影响现有功能
- **缓解**：保持向后兼容，逐步迁移

### 性能风险
- **风险**：候选列表可能影响渲染性能
- **缓解**：虚拟滚动，按需加载

## 估算时间

| 阶段 | 任务 | 估算时间 |
|------|------|----------|
| 阶段一 | 需求分析与设计 | 1 天 |
| 阶段二 | 前端实现 | 3 天 |
| 阶段三 | 后端实现 | 2 天 |
| 阶段四 | 测试与验证 | 2 天 |
| 阶段五 | 文档与发布 | 1 天 |
| **总计** | | **9 天** |

## 资源分配

- **前端开发**：1 人，负责 Vue.js 组件开发和 UI/UX 优化
- **后端开发**：1 人，负责 API 设计和业务逻辑实现
- **测试工程师**：1 人，负责功能测试和性能测试
- **产品经理**：1 人，负责需求确认和验收

## 里程碑

| 里程碑 | 时间 | 交付物 |
|--------|------|--------|
| M1：设计完成 | 第 1 天 | 设计文档、API 规范 |
| M2：前端开发完成 | 第 4 天 | Mix.vue 组件、交互逻辑 |
| M3：后端开发完成 | 第 6 天 | API 实现、混剪逻辑 |
| M4：测试完成 | 第 8 天 | 测试报告、Bug 修复 |
| M5：发布 | 第 9 天 | 发布说明、部署完成 |