FlightHubSDK（静态入口）
  → initialize(FlightHubSdkConfig)                ← 同步阻塞，返回 ErrorCode，必须检查
    → getWorkspaceInstance()                       ← 可能返回 null
      → workspace.getDeviceManageModule().getDeviceList(cb)
        → getDroneInstance(sn)                     ← 可能返回 null
        → getDockInstance(sn)                      ← 可能返回 null
          → drone.getXxxModule()                   ← 通过子模块 getter 访问能力
            → module.listenXxx(callback)           ← 返回 int listenId (≥0 成功, <0 失败)
            → module.cancelListenXxx(id)           ← 服务关闭时必须调用

FlightHubError {
    FlightHubSdkErrorCode errorCode;  // SDK 层枚举
    int httpCode;                      // HTTP 状态码（0=网络层失败）
    int serverCode;                    // 服务端业务码（0=成功）
    int deviceCode;                    // 设备端错误码（0=无设备错误）
    String serverMessage;              // 服务端错误描述
}

import com.dji.flighthubsdk.core.JniLibraryLoader;
 
JniLibraryLoader.loadLibrary();   // 必须先调用，再注入鉴权头

// SDK 鉴权通过 HTTP + WebSocket 双通道头注入，不是 appId/appSecret
// key/value 是网关约定的头名与头值，由 FH2 服务端决定（测试环境常见 user_id / paas_test），
// 不一定是 Authorization / Bearer —— 以服务端提供的鉴权头对为准。
List<HeaderKeyValue> headers = new ArrayList<>();
headers.add(new HeaderKeyValue(authKey, authValue));   // 例如 ("user_id", "paas_test")
 
FlightHubSDK.setHttpHeaders(headers);            // HTTP 请求鉴权
FlightHubSDK.setWebSocketAuthHeaders(headers);    // WebSocket 推送鉴权
// 必须检查返回值：两者任一非 SUCCESS，说明注入失败，后续推送必然 401

FlightHubSdkConfig config = new FlightHubSdkConfig();
config.setAddress("https://<fh2-host>");                                                    // HTTP 地址，含协议前缀
config.setPort("30812");                                                                     // HTTP 端口，注意是 String 类型
config.setNotificationServerAddress("wss://<fh2-host>:30812/openapi/v0.9/notification/ws/v1/notifications"); // WebSocket 推送地址
config.setLogLevel("info");                                                                  // 可选：debug / info / warn / error

// ✅ 正确：检查返回值
FlightHubSdkErrorCode code = FlightHubSDK.initialize(config);
if (code != FlightHubSdkErrorCode.SUCCESS) {
    throw new IllegalStateException("SDK init failed: " + code);
}
 
// ❌ 错误：未检查返回值
FlightHubSDK.initialize(config); // 可能返回 ERROR_INIT_FAILED
Workspace ws = FlightHubSDK.getWorkspaceInstance(); // null

// ✅ 正确（注意：回调参数顺序是 data 在前、error 在后）
workspace.getDeviceManageModule().getDeviceList((devices, error) -> {
    if (error.getErrorCode() != FlightHubSdkErrorCode.SUCCESS) {
        log.error("获取设备列表失败: sdk={}, server={}", error.getErrorCode(), error.getServerCode());
        return;
    }
    // 安全使用 devices
});
 
// ❌ 错误：errorCode 非 SUCCESS 时 devices 可能为 null
workspace.getDeviceManageModule().getDeviceList((devices, error) -> {
    devices.forEach(d -> ...); // NPE
});

// ✅ 正确（Spring Boot）— 订阅位置 + 电量（OSD 由多个独立 listener 组成）
@Component
public class DroneTelemetryListener {
    private int locationListenId = -1;
    private int batteryListenId  = -1;
 
    @PostConstruct
    public void start() {
        Drone drone = FlightHubSDK.getDroneInstance(sn);
        if (drone == null) return;
 
        DroneOsdModule osd = drone.getDroneOsdModule();
        locationListenId = osd.listenAircraftLocation(loc -> handleLocation(loc));
        if (locationListenId < 0) log.error("订阅位置失败");
 
        batteryListenId = osd.listenAircraftBatteryInfo(bat -> handleBattery(bat));
        if (batteryListenId < 0) log.error("订阅电量失败");
    }
 
    @PreDestroy
    public void stop() {
        Drone drone = FlightHubSDK.getDroneInstance(sn);
        if (drone == null) return;
        DroneOsdModule osd = drone.getDroneOsdModule();
        if (locationListenId >= 0) osd.cancelListenAircraftLocation(locationListenId);
        if (batteryListenId  >= 0) osd.cancelListenAircraftBatteryInfo(batteryListenId);
    }
}
 
// ❌ 错误：不保存 listenId → 无法 cancel → 回调泄漏
drone.getDroneOsdModule().listenAircraftLocation(loc -> { ... }); // listenId 被丢弃

// ✅ 正确：acquire → 指令 → release（无论成败）
ControlAuthModule auth = drone.getControlAuthModule();
auth.acquireFlightControlAuthority(acquireError -> {
    if (acquireError.getErrorCode() != FlightHubSdkErrorCode.SUCCESS) {
        log.error("获取控制权失败: {}", acquireError.getErrorCode());
        return;
    }
    drone.getFlightControlModule().returnHome(cmdError -> {
        // 无论成败都释放控制权
        auth.releaseFlightControlAuthority(e -> {});
        if (cmdError.getErrorCode() != FlightHubSdkErrorCode.SUCCESS) {
            log.error("返航失败: {}", cmdError.getErrorCode());
        }
    });
});
 
// ❌ 错误：未抢权直接发指令 → 返回权限错误
drone.getFlightControlModule().returnHome(error -> { ... });

// ✅ 正确
Drone drone = FlightHubSDK.getDroneInstance(sn);
if (drone == null) {
    log.warn("Drone not found or offline: {}", sn);
    return;
}
 
// 模块 getter 也可能返回 null（如设备不支持该模块）
CameraControlModule cam = drone.getCameraControlModule();
if (cam == null) {
    log.warn("CameraControlModule not available: {}", sn);
    return;
}
 
// ❌ 错误：NPE
FlightHubSDK.getDroneInstance(sn).getDroneOsdModule().listenAircraftLocation(...);

⚠️ **危险操作警告**
- 操作类型：[takeoff / returnHome / drcEmergencyStop / drcEmergencyLanding / drcForceLanding / flyToPoint]
- 不可逆性：[具体描述，如"drcForceLanding 强制降落并停转螺旋桨，不可撤销"或"drcEmergencyStop 立即悬停，螺旋桨保持运转"]
- 物理影响：此代码将控制真实无人机执行物理动作，操作失误可能导致坠机或财产损失
- 生产建议：务必实现前端二次确认弹窗（confirm dialog）；建议支持 dry_run 参数做预校验

public void executeWithCallback(Drone drone) {
    CompletableFuture<Void> future = new CompletableFuture<>();
 
    drone.getFlightControlModule().returnHome(error -> {
        if (error.getErrorCode() != FlightHubSdkErrorCode.SUCCESS) {
            future.completeExceptionally(new RuntimeException("失败: " + error.getErrorCode()));
        } else {
            future.complete(null);
        }
    });
 
    // Controller 层等待结果（带超时保护）
    try {
        future.get(30, TimeUnit.SECONDS);
    } catch (TimeoutException e) {
        throw new RuntimeException("SDK 回调超时");
    }
}

用户问题
├─ getDroneInstance / getDockInstance / getWorkspaceInstance 返回 null
│    → 加载 references/设备管理流程.md#常见问题 + references/错误码诊断.md#常见问题速查
├─ 报错 / errorCode / httpCode / serverCode
│    → 加载 references/错误码诊断.md，按 4 层优先级定位
├─ 接入新功能 / 添加模块 / 订阅数据
│    → 先判断是订阅式(规则3)还是命令式(规则4)，按对应规则生成代码
├─ 质量检查 / 自检 / review
│    → 加载 references/接入质量检查清单.md
└─ SDK 概念 / 架构 / "xxx 是什么"
     → 加载 references/文档检索与问答.md