<feature>[storage]: register and take over sblk

[zstack-robot-1]

APIImpact

Resolves: ZSV-10000

Change-Id: I70637377776e777070676c6a6c616e74786b6667

sync from gitlab !9403

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 271cbc8b-5d59-4543-a683-9129dcac9440

📥 Commits

Reviewing files that changed from the base of the PR and between 5924b9d and 306f551.

⛔ Files ignored due to path filters (1)

• conf/serviceConfig/primaryStorage.xml is excluded by !**/*.xml

📒 Files selected for processing (22)

• header/src/main/java/org/zstack/header/storage/primary/APICheckPrimaryStorageConsistencyMsg.java
• header/src/main/java/org/zstack/header/storage/primary/APICheckPrimaryStorageConsistencyMsgDoc_zh_cn.groovy
• header/src/main/java/org/zstack/header/storage/primary/APICheckPrimaryStorageConsistencyReply.java
• header/src/main/java/org/zstack/header/storage/primary/APICheckPrimaryStorageConsistencyReplyDoc_zh_cn.groovy
• header/src/main/java/org/zstack/header/storage/primary/APITakeoverPrimaryStorageEvent.java
• header/src/main/java/org/zstack/header/storage/primary/APITakeoverPrimaryStorageEventDoc_zh_cn.groovy
• header/src/main/java/org/zstack/header/storage/primary/APITakeoverPrimaryStorageMsg.java
• header/src/main/java/org/zstack/header/storage/primary/APITakeoverPrimaryStorageMsgDoc_zh_cn.groovy
• header/src/main/java/org/zstack/header/storage/primary/ConsistencyCheckReason.java
• header/src/main/java/org/zstack/header/storage/primary/ReconnectResult.java
• sdk/src/main/java/SourceClassMap.java
• sdk/src/main/java/org/zstack/sdk/CheckPrimaryStorageConsistencyAction.java
• sdk/src/main/java/org/zstack/sdk/CheckPrimaryStorageConsistencyResult.java
• sdk/src/main/java/org/zstack/sdk/ConsistencyCheckReason.java
• sdk/src/main/java/org/zstack/sdk/DiscoverSharedBlockGroupVgsAction.java
• sdk/src/main/java/org/zstack/sdk/DiscoverSharedBlockGroupVgsResult.java
• sdk/src/main/java/org/zstack/sdk/ReconnectResult.java
• sdk/src/main/java/org/zstack/sdk/SharedBlockGroupVgInfo.java
• sdk/src/main/java/org/zstack/sdk/TakeoverPrimaryStorageAction.java
• sdk/src/main/java/org/zstack/sdk/TakeoverPrimaryStorageResult.java
• storage/src/main/java/org/zstack/storage/primary/PrimaryStorageBase.java
• testlib/src/main/java/org/zstack/testlib/ApiHelper.groovy

---

Walkthrough

本PR引入两个新的主存储管理API：一致性检查（GET端点）和存储接管（PUT端点），以及相应的SDK、文档和基础处理器实现。主要包括消息类、应答类、中文文档、SDK操作类和处理器实现。

Changes

Cohort / File(s)	Summary
Consistency Check API - Header header/src/main/java/org/zstack/header/storage/primary/APICheckPrimaryStorageConsistencyMsg.java, APICheckPrimaryStorageConsistencyReply.java, APICheckPrimaryStorageConsistencyMsgDoc_zh_cn.groovy, APICheckPrimaryStorageConsistencyReplyDoc_zh_cn.groovy	新增GET端点用于检查主存储一致性，包含请求消息、应答类及对应的中文文档定义。应答包含一致性标志、检查原因和备选VG UUID字段。
Takeover Primary Storage API - Header header/src/main/java/org/zstack/header/storage/primary/APITakeoverPrimaryStorageMsg.java, APITakeoverPrimaryStorageEvent.java, APITakeoverPrimaryStorageMsgDoc_zh_cn.groovy, APITakeoverPrimaryStorageEventDoc_zh_cn.groovy	新增PUT端点用于接管主存储，包含请求消息、事件类及对应的中文文档定义。事件包含库存、重连结果和错误信息字段。
Type Definitions - Header header/src/main/java/org/zstack/header/storage/primary/ConsistencyCheckReason.java, ReconnectResult.java	定义一致性检查原因枚举（CONSISTENT、UUID_MISMATCH、VG_NOT_FOUND）和重连结果枚举（SUCCESS、FAILED、NOT_ATTEMPTED）。
SDK Action Classes sdk/src/main/java/org/zstack/sdk/CheckPrimaryStorageConsistencyAction.java, TakeoverPrimaryStorageAction.java, DiscoverSharedBlockGroupVgsAction.java	SDK层操作类，实现同步/异步调用、REST端点映射、参数处理和结果转换。
SDK Result Classes sdk/src/main/java/org/zstack/sdk/CheckPrimaryStorageConsistencyResult.java, TakeoverPrimaryStorageResult.java, DiscoverSharedBlockGroupVgsResult.java, SharedBlockGroupVgInfo.java	SDK层结果模型类，定义API响应数据结构和访问器。
SDK Type Definitions & Mappings sdk/src/main/java/org/zstack/sdk/ConsistencyCheckReason.java, ReconnectResult.java, ../storage/SourceClassMap.java	SDK包中的枚举定义及双向类映射配置，支持header包与SDK包间类型转换。
Implementation & Testing storage/src/main/java/org/zstack/storage/primary/PrimaryStorageBase.java, testlib/src/main/java/org/zstack/testlib/ApiHelper.groovy	基础存储类新增两个消息处理器方法（返回不支持错误），以及测试辅助类新增三个DSL方法用于API调用和路径跟踪。

Sequence Diagram

sequenceDiagram
    participant Client
    participant Server
    participant PrimaryStorageBase
    participant Storage System

    rect rgba(100, 150, 255, 0.5)
    Note over Client,Storage System: 一致性检查流程
    Client->>Server: GET /primary-storage/{uuid}/consistency
    Server->>PrimaryStorageBase: handle(APICheckPrimaryStorageConsistencyMsg)
    PrimaryStorageBase->>PrimaryStorageBase: 检查存储类型是否支持
    alt 存储类型不支持
        PrimaryStorageBase-->>Server: 返回错误应答
    else 存储类型支持
        PrimaryStorageBase->>Storage System: 执行一致性检查
        Storage System-->>PrimaryStorageBase: 返回检查结果
        PrimaryStorageBase-->>Server: 返回一致性应答
    end
    Server-->>Client: APICheckPrimaryStorageConsistencyReply
    end

    rect rgba(150, 200, 100, 0.5)
    Note over Client,Storage System: 存储接管流程
    Client->>Server: PUT /primary-storage/{uuid}/takeover
    Server->>PrimaryStorageBase: handle(APITakeoverPrimaryStorageMsg)
    PrimaryStorageBase->>PrimaryStorageBase: 检查存储类型是否支持
    alt 存储类型不支持
        PrimaryStorageBase-->>Server: 返回错误事件
    else 存储类型支持
        PrimaryStorageBase->>Storage System: 执行接管操作
        Storage System-->>PrimaryStorageBase: 返回库存及重连结果
        PrimaryStorageBase-->>Server: 发布事件
    end
    Server-->>Client: APITakeoverPrimaryStorageEvent
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 兔子欢呼新API登场，
一致性检查细心梳理，
存储接管展身手，
SDK映射配对精准，
文档中英双轨齐驱，
存储系统更臻完善！ 🌟

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	PR标题虽然简洁，但与变更内容关系密切，清晰表达了主要功能：注册和接管共享块存储(sblk)设备。
Description check	✅ Passed	PR描述包含相关信息(APIImpact、问题号ZSV-10000、Change-Id、GitLab同步来源)，与变更集相关，虽然简洁但足以说明变更背景。

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch sync/tao.gan/sblk-ZSV-10000@@3

📝 Coding Plan

• Generate coding plan for human review comments

---

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

[ZStack-Robot]

Comment from yaohua.wu:

Review: MR !9403 (zstack) — register and take over sblk

关联 MR: premium !13245 | zstack-utility !6777

Critical

无。

Warning

无。

Suggestion

1. [PrimaryStorageBase.java ~L950] 默认实现 — handle(APITakeoverPrimaryStorageMsg) 和 handle(APICheckPrimaryStorageConsistencyMsg) 的默认实现直接返回 "not supported" 错误，这是正确的扩展模式（只有 SharedBlock 子类实现真正逻辑）。建议考虑在 API 层面添加权限约束（如 admin-only），因为 takeover 是不可逆的危险操作。

2. [APICheckPrimaryStorageConsistencyReplyDoc_zh_cn.groovy / APITakeoverPrimaryStorageMsgDoc_zh_cn.groovy] 缺少末尾换行 — 文件结尾缺少换行符（\ No newline at end of file），建议补充。

3. [ConsistencyCheckReason.java / ReconnectResult.java] 枚举注释 — ConsistencyCheckReason 有清晰的 Javadoc 注释说明每个枚举值的语义，好的代码习惯。ReconnectResult 建议也添加类似注释（特别是 NOT_ATTEMPTED 的适用场景说明）。

Verdict: APPROVED

API 定义清晰：

• APICheckPrimaryStorageConsistencyMsg（GET 同步查询）和 APITakeoverPrimaryStorageMsg（PUT 异步操作）语义正确
• REST 路径设计合理（/primary-storage/{uuid}/consistency、/primary-storage/{uuid}/takeover）
• ConsistencyCheckReason 枚举覆盖了三种状态（CONSISTENT / UUID_MISMATCH / VG_NOT_FOUND），语义完整
• ReconnectResult 枚举（SUCCESS / FAILED / NOT_ATTEMPTED）正确分离了接管结果和重连结果
• SDK 类、中文文档、SourceClassMap 映射齐全

无阻塞问题。详细 review 见 premium !13245 评论。

---

🤖 Robot Reviewer