用途
该技能用于帮助集成商开发者正确编写调用 DJI Cloud API 2 Java SDK 地图域模块的集成代码，涉及 SafetyServiceModule 与 ElementModule 两个模块。两个模块都挂载在 Workspace 上，以纯 HTTP 业务接口为主，并各带少量 WebSocket 订阅（SafetyService 1 个、Element 3 个），与飞控、遥测这类 Drone、Dock 级事件驱动接口不同。
核心价值在于状态同步语义：飞行区和离线地图修改的是云端定义，必须再通过 sync 下发到机场才生效，并且 sync 返回不代表同步完成，还需轮询 *SyncStatus。
何时触发
- 编写代码管理自定义飞行区（nfz 限飞区、dfence 作业区、noland 禁降区）
- 将飞行区或离线地图下发到机场或地面站（sync、查同步状态）
- 地形障碍物离线地图的生成、取消、开关
- 接入 Flysafe 解锁证书（上传、校验、提交、查询、开关、清除）
- 查询信号地图（4G、SDR 覆盖网格）
- 管理地图元素（点、线、面、圆、分组层级、可见性）
- 遇到相关报错：同步失败、reason 码、几何校验不通过、回调参数写错、模块取到 null
不触发场景：运行时直接调用 MCP Tool 做运维操作（转交 cloudapi2-mcp-guide）；通用 SDK 规则、飞控、航线任务、媒体（转交 cloudapi2-sdk-core）；设备生命周期、固件升级、HMS 告警（转交 cloudapi2-device-management）；SEI、OSD 遥测、视频流与地图可视化融合（转交 cloudapi2-sei-osd）。
主要能力
模块位置：两个模块都在 Workspace 上获取：
SafetyServiceModule safety = workspace.getSafetyServiceModule();
ElementModule element = workspace.getElementModule();
它们不在 drone 或 dock 上。两个 getter 都可能返回 null，调用前必须判空。
方法规模（源码核实）：SafetyServiceModule 共 22 个方法，覆盖信号地图、自定义飞行区、地形障碍物离线地图、Flysafe 解锁证书；ElementModule 共 11 个方法，覆盖地图元素（点、线、面、圆）增删改查、可见性、分组层级与 3 组 WS 订阅。
核心规则
-
回调顺序统一为 (error, result)，但有一批方法只有 (error)：deleteCustomizedFlightAreas、updateOfflineMapsModelInfo、cancelOfflineMapsModelInfo、setOfflineMaps、switchUnlockLicense、submitUnlockLicense、clearDeviceUnlockLicense。另有 listenDroneOfflineMapEnable 为 (message) 单参数推送订阅。不要按“查询/命令”推断参数个数。
-
云端定义不等于设备生效，sync 是必经步骤：创建、更新或删除飞行区只改变云端；随后调用 syncCustomizedFlightAreas(网关 SN 列表) 提交下发；再调用 getFlightAreasSyncStatus(网关 SN 列表) 轮询直到 synchronized 或 fail。同步对象只能是网关类型设备 SN（机场 1/2/3、地面站），飞行器 SN 不会生效。离线地图同构：syncOfflineMaps → getOfflineMapsSyncStatus。失败时按 DeviceSyncStatusResults.reason 码给出可读原因（0–13 / 255）。
-
离线地图生成是长任务：updateOfflineMapsModelInfo 触发模型生成，并非即时完成。必须轮询 getOfflineMapsModelInfo 直到 percent == 100 或 status 进入终态，再考虑 syncOfflineMaps。中途可用 cancelOfflineMapsModelInfo 取消。
-
解锁证书是三段式，不能跳过任何一步：uploadUnlockLicenseFile(本地路径) 得到 fileStoreDir 并拼出 fileKey；checkUnlockLicense(fileKey, sn) 中 errFileNames 或 errCertMismatch 非空即中止；submitUnlockLicense(sn, certUrl) 提交解锁（仅 error）。check 通过不代表 submit 成功，submit 前必须确认 check 无错误项。
-
几何数据格式严格：Circle 需要 center 与 radius，radius > 0，单位为米；Polygon 需要 coordinates，不少于 3 点、顶点数小于 255、首尾必须闭合；Polyline 仅禁降区（noland）可用。坐标格式一律为 [经度, 纬度]。飞行区数量上限：nfz 不超过 100，noland 不超过 50。
-
订阅必须配对 cancel：listenDroneOfflineMapEnable 返回 int listenId，小于 0 表示失败，@PreDestroy 中必须调用 cancelListenDroneOfflineMapEnable(listenId)。ElementModule 的 listenElementCreate/Update/Delete 同样各返回一个 listenId，需分别保存并配对 cancel。其余方法均为一次性回调，不需要 cancel。
几何模型两套互不通用：SafetyServiceModule 飞行区几何用 ContentsGeometryData.type = Circle/Polygon/Polyline；ElementModule 几何用 ElementGeometry.type = Point/LineString/Polygon，圆形复用 Point + radius，没有 Circle 枚举值。两套模型字段名相似但取值不同，不要跨模块抄代码。
使用方式
技能按决策树路由到对应参考文档：飞行区增删改查、同步到设备、reason 码、离线地图、解锁证书、信号地图指向 references/safety-service.md 的不同章节；地图元素相关指向 references/element.md；模块获取为 null、回调参数写错等问题指向技能说明本身；需要调 MCP 工具做运维时转交 cloudapi2-mcp-guide。
工作流遵循 skills/_shared/sop-template.md 定义的 7 章节 SOP，按 L1/L2/L3 自动选档。澄清阶段需确认：目标对象类型、是否需要下发到设备、目标设备类型（飞行器 SN 还是网关 SN）、几何类型、是否已有对象存储上传链路。编码约束见 constraints.yaml；验证阶段需检查模块 getter 是否判空、回调参数个数是否与方法表一致、修改类操作后是否调用 sync 并轮询状态、几何数据是否满足约束、所有 listenXxx 的 listenId 是否已保存并配对 cancel、解锁流程是否包含 check 失败即中止的分支。
反幻觉规则：示例代码必须来源于本技能的 references/ 或用户提供的文档，不得凭模型记忆生成 API 签名、字段名或枚举值；不确定时明确告知用户需要确认 SDK 文档；任何建议必须可追溯到 references/ 文档路径或官方 SDK 源码。