feat: 优化功能

2025-12-22 00:15:02 +08:00
parent b80de78d7c
commit 8d7bc0d47f
12 changed files with 2513 additions and 595 deletions
--- a/openspec/changes/refactor-mix-scene编排/tasks.md
+++ b/openspec/changes/refactor-mix-scene编排/tasks.md
@@ -0,0 +1,241 @@
+# 混剪场景编排功能重新设计 - 任务清单
+
+## 任务列表
+
+### 阶段一：需求分析与设计
+
+#### 任务 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 天 | 发布说明、部署完成 |