9.8 KiB
9.8 KiB
混剪场景编排功能重新设计 - 任务清单
任务列表
阶段一：需求分析与设计
任务 1.1：需求确认
- 确认用户对多候选场景模式的具体需求
- 明确每个场景的默认候选数量和最大限制（1-10个）
- 确认两层随机选择算法：
- 第一层：从每个场景的候选中随机选择一个素材
- 第二层：对选中的素材使用随机起点
- 确认随机选择算法要求（确定性随机，基于场景索引）
任务 1.2：数据结构设计
- 设计前端场景数据结构：
{index: [{fileId, duration, candidates, fileUrl, fileDuration}]} - 设计后端 API 数据结构：
List<SceneConfig> - 定义防重复验证规则（同一场景内不重复）
任务 1.3：API 接口设计
- 设计新的创建混剪任务 API（支持scenes格式）
- 定义场景配置数据结构（SceneConfig内部类）
- 确认向后兼容性（保留materials字段）
阶段二：前端实现
任务 2.1：Mix.vue 组件重构
- 修改场景数据结构：
- 将
scenes从Array<{fileId, fileUrl}>改为Array<{index, duration, candidates: Array<Material>}> - 更新场景初始化逻辑
- 修改场景数组监听器（watch）
- 将
- 更新场景格子 UI：
- 添加候选数量徽标（badge）：显示
候选 X/10 - 更新场景格子样式：纵向布局，空态显示
- 添加候选预览：卡片形式展示候选缩略图
- 添加移除功能：支持点击移除候选
- 添加候选数量徽标（badge）：显示
- 实现候选选择弹窗：
- 创建候选选择器：使用现有文件选择弹窗
- 弹窗内容：场景信息 + 素材库网格 + 操作按钮
- 支持多选：批量选择功能
- 显示已选状态：实时更新候选列表
任务 2.2：交互逻辑实现
- 实现场景候选的添加/删除功能：
addCandidateToScene(sceneIndex, material)：添加候选到指定场景removeCandidateFromScene(sceneIndex, candidateIndex)：从场景移除候选clearScene(sceneIndex)：清空指定场景的所有候选selectFileForScene(file, sceneIndex)：选择文件添加到场景
- 实现防重复验证：
isCandidateDuplicate(sceneIndex, fileId)：检查候选是否重复- 前端实时检查：在选择素材时即时验证
- 视觉反馈：已选择的素材显示禁用状态
- 提示信息：重复选择时显示警告提示
- 优化一键填充功能：
- 实现三种填充策略：
EMPTY_ONLY：仅填充空场景（默认）SUPPLEMENT：补充不足场景到目标数量FULL_FILL：全量重新填充所有场景
- 重构
autoFillScenes()方法：- 收集所有可用素材，过滤已使用素材
- 实现Fisher-Yates洗牌算法进行随机选择
- 支持基于场景索引的确定性随机种子
- 动态调整目标候选数量（根据素材库总量）
- 实时更新已使用素材列表，避免跨场景重复
- 实现
randomlySelectMaterials()工具函数：- 支持指定选择数量和随机种子
- 确保选择结果可重现（相同种子相同结果）
- 优化性能：避免重复洗牌相同素材池
- 添加用户体验优化：
- 填充进度提示（进度条或加载动画）
- 填充结果反馈（显示"已为X个场景填充Y个候选"）
- 支持一键撤销最近的填充操作
- 智能建议：根据素材库情况推荐最佳策略
- 实现三种填充策略：
任务 2.3：UI/UX 优化
- 设计候选列表展示方式：
- 纵向布局：每个场景独立显示，标题在上方
- 候选列表：卡片形式展示所有候选缩略图
- 缩略图展示：每个候选显示缩略图 + 文件名
- 添加候选数量提示：
- 场景格子上方显示徽标：
候选 3/10 - 颜色编码：0个（灰色）、1-3个（黄色）、4-10个（绿色）
- 空态显示：大号加号图标 + "点击添加候选"文字
- 场景格子上方显示徽标：
- 实现候选使用状态可视化：
- 候选卡片：带阴影的卡片样式
- 悬停效果：鼠标悬停时卡片放大 + 阴影加深
- 移除功能：支持点击移除候选
- 优化移动端适配：
- 响应式布局：移动端自适应宽度
- 触摸优化：支持触摸操作
- 性能优化：CSS Flexbox高效渲染
任务 2.4：数据处理
- 更新表单数据处理逻辑：
- 修改
formData结构：移除单个素材相关字段 - 更新场景计算：
sceneCount、filledCount - 调整提交检查逻辑：验证每个场景至少有一个候选
- 修改
- 实现候选数据的序列化/反序列化：
- 场景数据持久化：保存到 Vue 响应式数据
- 数据格式转换：新旧格式兼容处理
- 状态恢复：页面刷新后保持场景配置
- 更新提交前的数据验证：
- 验证场景完整性：每个场景至少 1 个候选
- 验证候选数量：每个场景最多 10 个候选
- 验证总时长：计算总时长并检查范围
- 验证素材有效性：检查 fileId 和 fileUrl 是否有效
阶段三：后端实现
任务 3.1：API 对象修改
- 更新
MixTaskSaveReqVO.MaterialItem结构 - 添加场景配置对象：
SceneConfig（内部类） - 更新请求/响应 VO（添加 scenes 字段，保留 materials 字段）
任务 3.2：混剪服务逻辑修改
- 更新
MixTaskServiceImpl.submitToICE()方法 - 修改场景数据解析逻辑（支持新旧格式）
- 实现随机选择算法（
selectRandomMaterialsFromScenes()）
任务 3.3：批量处理优化
- 实现两层随机选择逻辑：
- 第一层：从每个场景的候选中随机选择素材
- 第二层：对选中素材应用随机起点（保留 [x] 修改原有逻辑）
BatchProduceAlignment.produceSingleVideoWithOffset()调用- 调整随机种子算法（基于 videoIndex、sceneIndex）
任务 3.4：数据验证
- 添加场景候选数量验证（
validateScenesFormat()） - 实现候选视频有效性检查（
validateMaterialsFormat()） - 添加总时长验证（保留
validateDuration()方法）
阶段四：测试与验证
任务 4.1：单元测试
- 测试前端场景数据处理
- 测试后端 API 数据解析
- 测试随机选择算法（确定性随机验证）
任务 4.2：集成测试
- 测试完整的混剪流程
- 测试批量混剪功能
- 测试各种边界情况
任务 4.3：性能测试
- 测试大量候选场景的性能
- 测试批量混剪的响应时间
- 测试内存使用情况
任务 4.4：用户验收测试
- 验证功能完整性
- 验证操作便捷性
- 收集用户反馈
阶段五：文档与发布
任务 5.1：文档更新
- 更新 API 文档（MixTaskSaveReqVO.java Swagger注释）
- 更新用户使用指南（实施摘要文档）
- 添加开发者文档（样式更新说明）
任务 5.2：代码审查
- 代码质量检查（前端Vue组件、后端Java代码）
- 安全性审查（数据验证、输入校验）
- 性能优化审查（两层随机算法优化）
任务 5.3：部署准备
- 准备发布说明（IMPLEMENTATION_SUMMARY.md）
- 配置部署脚本（通过OpenSpec管理）
- 准备回滚方案（保持向后兼容）
任务依赖关系
关键路径
- 需求确认 → 数据结构设计 → API 设计
- API 设计 → 前端实现 → 后端实现
- 前后端实现 → 集成测试 → 发布
并行任务
- 任务 2.1（前端组件重构）和 任务 3.1（API 对象修改）可以并行进行
- 任务 4.1（单元测试）和任务 4.2（集成测试）可以并行进行
验收标准
功能验收
- 每个场景可以添加多个候选视频（1-10个）
- 同一场景内候选视频不重复
- 一键填充功能正常（修复数组初始化问题）
- 批量混剪时从候选中随机选择（两层随机算法）
- UI 展示清晰，操作流畅（纵向布局，空态优化）
性能验收
- 场景加载时间 < 2 秒（Vue响应式数据）
- 混剪任务创建响应时间 < 3 秒（优化随机算法）
- 批量混剪性能无明显下降（保持原有第二层随机）
代码验收
- 代码质量良好（前端Vue 3 + 后端Java）
- 无严重代码质量问题（遵循项目规范）
- 关键逻辑有充分注释（算法实现详细说明）
风险缓解
技术风险
- 风险：修改涉及多个文件，可能引入 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 天 | 发布说明、部署完成 |