feat(drivers/alias): support move direct within same backend

[qiuxiuya]

Summary / 摘要

为 alias 驱动的 move 操作新增 MoveDirect 选项。当源后端数量少于目标后端数量时，不再直接报错 ErrNotEnoughSrcObjs，而是在同一后端上执行 move，跳过无法匹配的目标目录。

用户可感知的行为变化

• 在源对象所在后端数量少于目标路径所在后端数量时，move 操作不再必然失败，只要源和目标存在于同一后端即可成功。
• 新增MoveDirect配置项，用户可通过配置将其关闭以回退到原有严格行为。

实现变化

• 在 drivers/alias/meta.go 中新增 MoveDirect 字段。

• 在 drivers/alias/util.go 中新增 getMoveObjsDirect 方法，按挂载点将目标目录分组，遍历源对象时仅匹配同挂载点的目标目录。

• 修改 getMoveObjs 方法：当 MoveDirect 开启且 len(tmpSrcObjs) < len(dstObjs) 时，调用 getMoveObjsDirect 替代直接返回错误。

• This PR has breaking changes.
  / 此 PR 包含破坏性变更。

• This PR changes public API, config, storage format, or migration behavior.
  / 此 PR 修改了公开 API、配置、存储格式或迁移行为。

• This PR requires corresponding changes in related repositories.
  / 此 PR 需要关联仓库同步修改。

Related Issues / 关联 Issue

Testing / 测试

• go test ./...
• Manual test / 手动测试:
  • 创建 alias 驱动，挂载多个后端存储。
  • 在源文件后端少于目标后端的情况下执行 move 操作，验证 move 仅在同后端发生。
  • 关闭 MoveDirect（设为 false）后重试，验证回退到原有 ErrNotEnoughSrcObjs 行为。

Checklist / 检查清单

• I have read CONTRIBUTING.
  / 我已阅读 CONTRIBUTING。
• I confirm this contribution follows the repository license, contribution policy, and code of conduct.
  / 我确认此贡献符合仓库许可证、贡献规范和行为准则。
• I have formatted the changed code with gofmt, go fmt, or prettier where applicable.
  / 我已按适用情况使用 gofmt、go fmt 或 prettier 格式化变更代码。
• I have requested review from relevant maintainers or code owners where applicable.
  / 我已在适用情况下请求相关维护者或代码所有者审查。

AI Disclosure / AI 使用声明

• This PR includes AI-assisted content.
  / 此 PR 包含 AI 辅助内容。

Tools used / 使用工具:

• ChatGPT
• Codex
• GitHub Copilot
• Claude
• Gemini
• Other (please specify) / 其他（请注明）:

Usage scope / 使用范围:

• Code generation / 代码生成

• Refactoring / 重构

• Documentation / 文档

• Tests / 测试

• Translation / 翻译

• Review assistance / 审查辅助

• I have reviewed and validated all AI-assisted content included in this PR.
  / 我已审核并验证此 PR 中的所有 AI 辅助内容。

• I have ensured that all AI-assisted commits include Co-Authored-By attribution.
  / 我已确保所有 AI 辅助提交都包含 Co-Authored-By 归属信息。

• I can reproduce all AI-assisted content included in this PR without any AI tools.
  / 我可以在没有任何 AI 工具的情况下重现此 PR 中包含的所有 AI 辅助内容。

[jyxjjj]

Also see: #2644

[pikachuren]

🙏 感谢贡献

感谢 @qiuxiuya 提交此PR！我已完成代码评审，以下是评审结果。

---

🤖 AI 自动审核声明

本评审报告由 AI 自动生成，当前使用 Claude Opus 5 模型进行分析，部分复杂场景可能辅助使用 ChatGPT、DeepSeek 等模型进行交叉验证。

⚠️ AI 分析结果仅供参考，可能存在误判或遗漏。如您发现任何问题或有不同意见，欢迎随时提出讨论和纠正。

⚠️ 重要提醒：即使 AI 评审认为代码质量良好且建议合并，最终是否合并仍需由项目维护者进行人工判定。项目维护者会综合考虑代码质量、项目规划、技术方向、团队资源等多方面因素做出决策。

---

📖 PR背景与需求

PR标题：feat(drivers/alias): support move direct within same backend

关联Issue：无明确关联

需求说明：为 alias 驱动的 move 操作新增 MoveDirect 配置选项。当前 alias 驱动在处理跨挂载点的 move 操作时，会将源对象和目标对象分配到各自的后端存储进行处理。本次改动新增了 MoveDirect 选项，允许用户选择只在同一后端存储内进行直接 move 操作，提升同一存储后端内的 move 性能。

预期目标：

• 新增 move_direct 配置项（默认 false，保持向下兼容）
• 当 move_direct=true 时，move 操作仅在源和目标属于同一后端存储时执行
• 避免跨后端存储的复杂 move 操作，提升同一后端内的操作性能
• 保持与现有功能的兼容性

---

📋 问题摘要

• ✅ 功能性：新增功能设计合理，满足特定场景需求
• ✅ 代码质量：实现清晰，逻辑正确
• ⚠️ 改进建议：建议补充文档说明和边界情况处理

---

📂 逐文件分析

drivers/alias/meta.go

改动意图：在 alias 驱动的元数据配置中新增 MoveDirect 布尔选项

代码修改逻辑：

MoveDirect bool `json:"move_direct" type:"bool" default:"false"`

在 Additional 配置组中新增了 MoveDirect 字段：

• 字段类型：bool
• 默认值：false（保持向下兼容，默认行为不变）
• JSON 键名：move_direct

合理性评估：

• ✅ 优点：

  • 默认值为 false，保证了向下兼容性，不会影响现有用户的行为
  • 配置项命名清晰（move_direct），易于理解
  • 放置在 Additional 配置组中，与其他高级选项分类一致

• ✅ 无明显问题：配置项定义规范，符合项目惯例

详细建议：

1. 文档完善：建议在用户文档中详细说明此选项的用途和适用场景，例如：
   • 何时应该启用 move_direct（同一后端存储内的高频 move 场景）
   • 何时不应该启用（需要跨后端存储 move 的场景）
   • 启用后的行为变化（只在同一后端内 move，跨后端的 move 请求会如何处理？）

---

drivers/alias/util.go

改动意图：实现 MoveDirect 功能的核心逻辑，新增 getMoveObjsDirect 方法

代码修改逻辑：

1. 新增 getMoveObjsDirect 方法：

   func (d *Alias) getMoveObjsDirect(ctx context.Context, tmpSrcObjs, dstObjs BalancedObjs) (BalancedObjs, BalancedObjs, error)

   核心逻辑：

   • 按挂载点路径对目标对象进行分组（dstObjsMap）
   • 遍历源对象时，只匹配与源对象同一挂载点的目标对象
   • 如果源对象和目标对象不在同一挂载点，则跳过该源对象
   • 返回过滤后的源对象列表和目标对象列表

2. 修改 Move 方法：
   在原有的 getMoveObjs 调用处新增条件判断：

   if d.MoveDirect {
       tmpSrcObjs, tmpDstObjs, err = d.getMoveObjsDirect(ctx, tmpSrcObjs, tmpDstObjs)
   } else {
       tmpSrcObjs, tmpDstObjs, err = d.getMoveObjs(ctx, tmpSrcObjs, tmpDstObjs)
   }

合理性评估：

• ✅ 优点：

  • 代码结构清晰，新增方法职责单一
  • 使用条件判断切换逻辑，避免破坏原有功能
  • 按挂载点分组的实现思路合理，符合 alias 驱动的设计理念

• ⚠️ 疑问：

  • 跨后端的 move 请求会如何处理？ 如果用户在 move_direct=true 时尝试跨后端 move，代码会静默跳过这些对象吗？
  • 用户体验：如果源对象列表中有些对象被跳过，是否应该返回错误或警告信息，告知用户哪些对象无法移动？
  • 日志记录：建议在跳过跨后端对象时记录日志，方便用户排查问题

详细建议：

1. 增强用户反馈（重要）：
   当 move_direct=true 且存在跨后端的 move 请求时，建议返回明确的错误信息或警告：

   if d.MoveDirect {
       tmpSrcObjs, tmpDstObjs, err = d.getMoveObjsDirect(ctx, tmpSrcObjs, tmpDstObjs)
       if err != nil {
           return err
       }
       // 新增：检查是否有对象被跳过
       if len(tmpSrcObjs) == 0 {
           return fmt.Errorf("no objects can be moved: move_direct is enabled but source and destination are in different backends")
       }
       if len(tmpSrcObjs) < len(srcObjsRaw) {
           // 记录警告日志，告知用户部分对象被跳过
           log.Warnf("move_direct enabled: skipped %d objects due to cross-backend constraints", len(srcObjsRaw)-len(tmpSrcObjs))
       }
   }

2. 代码优化：
   在 getMoveObjsDirect 方法中，建议优化目标对象查找逻辑：

   // 当前实现使用 map 查找，已经比较高效
   // 但可以考虑增加注释说明查找逻辑
   for _, srcObj := range tmpSrcObjs {
       srcPath := srcObj.GetPath()
       // 查找与源对象同一挂载点的目标对象
       dstObjsForPath, ok := dstObjsMap[srcPath]
       if !ok {
           // 源对象和目标对象不在同一挂载点，跳过
           continue
       }
       // ...
   }

3. 边界情况处理：

   • 如果 tmpSrcObjs 或 tmpDstObjs 为空，是否需要提前返回？
   • 如果所有对象都被跳过，newSrcObjs 和 newDstObjs 都为空，后续代码是否能正确处理？

4. 测试建议：
   建议新增测试用例覆盖以下场景：

   • move_direct=true 且源和目标在同一后端（应成功）
   • move_direct=true 且源和目标在不同后端（应跳过或报错）
   • move_direct=false 的行为（应保持原有逻辑）
   • 混合场景：部分对象同一后端，部分对象跨后端

---

🎯 总体评价

功能性：⭐⭐⭐⭐ - 功能设计合理，满足特定场景需求，但缺少对跨后端 move 的明确处理

安全性：⭐⭐⭐⭐⭐ - 无安全风险，纯粹的功能增强

代码质量：⭐⭐⭐⭐ - 代码实现清晰，但缺少用户反馈和边界情况处理

实现方案：⭐⭐⭐⭐ - 技术方案合理，但可以进一步优化用户体验

建议操作：

• ✅ Approve（建议合并）
• 🔄 Request Changes（需要修改）
• ❌ Close（建议关闭）

理由：
这是一个功能设计合理的性能优化，核心逻辑正确，代码结构清晰。但存在以下需要改进的地方：

1. 用户体验不足：当 move_direct=true 时，如果用户尝试跨后端 move，代码会静默跳过这些对象，用户可能不知道为什么某些文件没有被移动。建议返回明确的错误信息或警告日志。

2. 文档缺失：需要在用户文档中详细说明 move_direct 选项的用途、适用场景和行为变化。

3. 测试覆盖：建议补充测试用例，确保各种场景下的行为符合预期。

建议修改：

1. 在 getMoveObjsDirect 方法中新增用户反馈机制（错误信息或警告日志）
2. 补充用户文档，说明 move_direct 选项的行为
3. 新增测试用例覆盖同一后端、跨后端、混合场景

完成上述改进后，这将是一个优秀的功能增强！💪