<fix>[migration]: fix batch migration error

[ZStack-Robot]

queuing operations to sync the same primary storage capacity.

Resolves/Related: ZSTAC-81028

Change-Id: I73726668696e6a68756b726c6f6c637273706774

sync from gitlab !8986

[coderabbitai]

大致流程

对主存储同步物理容量的流程进行了改造，引入 SingleFlightTask 机制实现并发去重。将直接同步完成的流程替换为单飞任务包装的流程，确保并发请求共享单一执行。

变更清单

队列 / 文件	变更摘要
主存储容量同步流程改造 storage/src/main/java/org/zstack/storage/primary/PrimaryStorageBase.java	新增导入：Consumer、SingleFlightTask、SingleFlightDone、SingleFlightTaskResult；替换同步容量更新机制为单飞任务，使用存储 UUID 作为唯一同步签名；任务成功时通过 PrimaryStorageCapacityUpdater 更新容量后触发完成回调；失败时返回错误信息；外层流程等待任务结果判断后续执行

序列图

sequenceDiagram
    participant Trigger
    participant SingleFlight as SingleFlightTask<br/>(按UUID去重)
    participant SyncLogic as syncPhysicalCapacity<br/>业务逻辑
    participant Updater as PrimaryStorageCapacityUpdater
    
    rect rgba(100, 200, 150, 0.2)
    Note over Trigger,Updater: 新流程：单飞去重容量同步
    end
    
    Trigger->>SingleFlight: singleFlightSubmit(签名)
    
    alt 首次执行
        SingleFlight->>SyncLogic: 执行同步物理容量
        SyncLogic->>SyncLogic: 采集容量数据
        SyncLogic->>Updater: 容量数据
        Updater->>Updater: 更新存储容量
        Updater-->>SingleFlight: 更新完成
        SingleFlight->>SingleFlight: 标记成功结果
    else 执行失败
        SyncLogic-->>SingleFlight: 异常
        SingleFlight->>SingleFlight: 记录失败结果
    end
    
    SingleFlight-->>Trigger: 返回任务结果
    
    alt 结果成功
        Trigger->>Trigger: 继续执行 trigger.next()
    else 结果失败
        Trigger->>Trigger: 触发失败处理
    end
    
    rect rgba(150, 150, 200, 0.2)
    Note over SingleFlight: 并发请求 ◇ 共享结果
    end

Loading

代码审查工作量估计

🎯 3 (中等) | ⏱️ ~20 分钟

诗

🐰 群兔齐声欢呼起，
单飞妙法除重复，
容量更新不混杂，
高效流转显魔力！

Pre-merge checks and finishing touches

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 1 warning)

Check name	Status	Explanation	Resolution
Title check	❌ Error	PR标题声称修复批量迁移错误，但实际变更涉及主存储容量同步的单飞去重机制优化，两者不相关。	将标题改为准确反映变更内容，例如'[storage]: Deduplicate concurrent capacity sync operations'或'[primary-storage]: Use single-flight for capacity sync'。
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description check	✅ Passed	描述与变更相关，提及了同步主存储容量和ZSTAC-81028，虽然信息不够详细但确实涉及变更的核心内容。

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Path: http://open.zstack.ai:20001/code-reviews/zstack-cloud.yaml (via .coderabbit.yaml)

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7e3ce34 and fd80c45.

📒 Files selected for processing (1)

• storage/src/main/java/org/zstack/storage/primary/PrimaryStorageBase.java

🧰 Additional context used

📓 Path-based instructions (2)

**/*.*

⚙️ CodeRabbit configuration file

**/*.*: - 代码里不应当有有中文，包括报错、注释等都应当使用正确的、无拼写错误的英文来写

Files:

• storage/src/main/java/org/zstack/storage/primary/PrimaryStorageBase.java

**/*.java

⚙️ CodeRabbit configuration file

**/*.java: ## 1. API 设计要求

• API 命名：
  • API 名称必须唯一，不能重复。
  • API 消息类需要继承 APIMessage；其返回类必须继承 APIReply 或 APIEvent，并在注释中用 @RestResponse 进行标注。
  • API 消息上必须添加注解 @RestRequest，并满足如下规范：
    • path:
      • 针对资源使用复数形式。
      • 当 path 中引用消息类变量时，使用 {variableName} 格式。
    • HTTP 方法对应：
      • 查询操作 → HttpMethod.GET
      • 更新操作 → HttpMethod.PUT
      • 创建操作 → HttpMethod.POST
      • 删除操作 → HttpMethod.DELETE
  • API 类需要实现 __example__ 方法以便生成 API 文档，并确保生成对应的 Groovy API Template 与 API Markdown 文件。

---

2. 命名与格式规范

• 类名：

  • 使用 UpperCamelCase 风格。
  • 特殊情况：
    • VO/AO/EO 类型类除外。
    • 抽象类采用 Abstract 或 Base 前缀/后缀。
    • 异常类应以 Exception 结尾。
    • 测试类需要以 Test 或 Case 结尾。

• 方法名、参数名、成员变量和局部变量：

  • 使用 lowerCamelCase 风格。

• 常量命名：

  • 全部大写，使用下划线分隔单词。
  • 要求表达清楚，避免使用含糊或不准确的名称。

• 包名：

  • 统一使用小写，使用点分隔符，每个部分应是一个具有自然语义的英文单词（参考 Spring 框架的结构）。

• 命名细节：

  • 避免在父子类或同一代码块中出现相同名字的成员或局部变量，防止混淆。
  • 命名缩写：
    • 不允许使用不必要的缩写，如：AbsSchedulerJob、condi、Fu 等。应使用完整单词提升可读性。

---

3. 编写自解释代码

• 意图表达：

  • 避免使用布尔型参数造成含义不明确。例如：
    • 对于 stopAgent(boolean ignoreError)，建议拆分为不同函数（如 stopAgentIgnoreError()），或使用枚举表达操作类型。
  • 命名应尽量用完整的单词组合表达意图，并在名称中体现数据类型或用途（例如在常量与变量名称中，将类型词放在末尾）。
  • 避免使用魔法值（Magic Value）：

    • 直接使用未经定义的数值或字符串（如 if (status == 5)）应替换为枚举或常量。

    • 示例：

    • // 错误示例：魔法值

    • if (user.getStatus() == 5) { ... }

    • // 正确示例：常量或枚举

    • public static final int STATUS_ACTIVE = 5;

    • if (user.getStatus() == STATUS_ACTIVE) { ... }

    • // 或使用枚举

    • enum UserStatus { ACTIVE, INACTIVE }

• 注释：

  • 代码应尽量做到自解释，对少于两行的说明可以直接写在代码中。
  • 对于较长的注释，需要仔细校对并随代码更新，确保内容正确。
  • 接口方法不应有多余的修饰符（例如 public），且必须配有有效的 Javadoc 注释。

---

4. 流程控制和结构优化

• if...else 的使用：

  • 应尽量减少 if...else 结构的使用，建议：
    • 限制嵌套层级最多为两层，且内层不应再出现 else 分支。
    • 尽早返回（Early Return），将条件判断中的处理逻辑提前结束或抽成独立方法。
    • 使用 Java Stream 或 Lambda 表达式代替冗长的循环与条件判断。

• 条件判断：

  • if 条件表达不宜过长或过于复杂，必要时可以将条件抽成 boolean 变量描述。

• 代码块长度：
  ...

Files:

• storage/src/main/java/org/zstack/storage/primary/PrimaryStorageBase.java

🧠 Learnings (1)

📓 Common learnings

Learnt from: zstack-robot-1
Repo: MatheMatrix/zstack PR: 2360
File: network/src/main/java/org/zstack/network/l3/L3BasicNetwork.java:449-490
Timestamp: 2025-08-04T04:48:19.103Z
Learning: ZStack项目在cherry-pick操作中，即使发现了性能优化机会（如IP地址批量保存的内存优化），也严格遵循不做额外修改的政策，优先保证cherry-pick的完整性和一致性。

Learnt from: ZStack-Robot
Repo: MatheMatrix/zstack PR: 2489
File: storage/src/main/java/org/zstack/storage/snapshot/VolumeTree.java:471-545
Timestamp: 2025-08-22T05:36:40.467Z
Learning: In ZStack项目中，对于核心逻辑相关的代码，团队倾向于暂时不进行重构，即使代码复杂度较高，优先保证核心功能的稳定性。

Learnt from: ZStack-Robot
Repo: MatheMatrix/zstack PR: 2325
File: compute/src/main/java/org/zstack/compute/vm/VmMigrateCallExtensionFlow.java:29-29
Timestamp: 2025-07-24T05:53:10.246Z
Learning: 在ZStack项目的重构过程中，团队采用务实的优先级策略：优先完成影响运行时功能的代码重构，对于注释中的旧引用等非功能性问题可以延后处理，因为这些不会影响系统的实际运行。

Learnt from: zstack-robot-1
Repo: MatheMatrix/zstack PR: 2360
File: compute/src/main/java/org/zstack/compute/vm/StaticIpOperator.java:364-501
Timestamp: 2025-08-04T03:19:07.454Z
Learning: In ZStack project, developers may prefer to keep related validation logic together in a single method (like validateStaticIpTagsInApiMessage with 130+ lines) when the architecture is clear and there's no code reuse, rather than splitting into smaller methods based purely on single responsibility principle.

Learnt from: ZStack-Robot
Repo: MatheMatrix/zstack PR: 2419
File: plugin/sdnController/src/main/java/org/zstack/sdnController/SdnControllerBase.java:986-1067
Timestamp: 2025-08-13T02:31:40.023Z
Learning: 在ZStack项目中，团队倾向于保持统一的业务流程方法不进行拆分，即使方法较长也会维持在单个方法中以保持业务逻辑的完整性。

Learnt from: zstack-robot-2
Repo: MatheMatrix/zstack PR: 2496
File: plugin/sharedMountPointPrimaryStorage/src/main/java/org/zstack/storage/primary/smp/KvmBackend.java:2545-2566
Timestamp: 2025-08-24T07:35:42.793Z
Learning: 在 ZStack 代码库中，当响应类包含数值字段（如 size、actualSize）时，优先使用原始类型（long）而不是包装类型（Long），以避免 NPE 风险和不必要的装箱/拆箱操作。如果 Agent 端可能不设置该字段，应在 Agent 端确保设置默认值，而不是在使用端做 null 检查。

🔇 Additional comments (2)

storage/src/main/java/org/zstack/storage/primary/PrimaryStorageBase.java (2)

5-5: LGTM！新增导入支持SingleFlightTask功能

新增的导入语句是实现容量同步去重机制所必需的，符合本次修复的目标。

Also applies to: 23-25

---

1251-1277: LGTM！SingleFlightTask实现正确，有效解决并发同步问题

这个变更通过SingleFlightTask机制解决了批量迁移时多个并发操作同步同一主存储容量的竞态问题：

1. 同步签名设计合理：基于主存储UUID（"sync-physical-capacity-on-ps-" + self.getUuid()），确保每个主存储只有一个在途的容量同步操作
2. 错误处理完整：从内层的syncPhysicalCapacity到外层的done处理器，错误传播链路清晰
3. 防御性编程：第1259行通过三元运算符确保availablePhysicalCapacity不会为负数
4. 业务逻辑保持不变：只是将原有的同步逻辑包装在SingleFlightTask中，降低了修改风险

这个实现符合ZStack项目对核心功能稳定性的要求，通过最小化的改动解决了并发问题。

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}