# 铁路无人机智能巡检平台——司空 2 私有化 OpenAPI 集成设计

> 文档状态：方案基线
>
> 编写日期：2026-07-25
>
> 适用范围：本仓库巡检平台与大疆司空 2 私有化版的系统集成
>
> 替代关系：本文件替代 `docs/dji-cloud-api-integration-design.md` 中“大疆设备直接接入 Cloud API”的厂商协议方案；旧文档的独立接入服务、统一领域模型、Inbox/Outbox 和多厂商隔离原则继续沿用。

## 1. 执行摘要

本项目不应继续按“平台直接实现 DJI Cloud API、直接承接设备 MQTT/Pilot H5/Dock 协议”的方式集成大疆设备。司空 2 私有化部署后，应把它视为大疆设备与飞行作业的厂商平台，由司空 2 负责设备接入、设备运维、航线执行、飞行控制、直播、媒体和建模等厂商能力；铁路巡检平台继续负责铁路业务计划、巡检对象、审批、AI 分析、隐患告警、工单、复检和归档。

推荐建设独立的 `uav-access-service`，其中新增 `flighthub2` 适配器，通过以下通道与司空 2 交互：

1. **OpenAPI V2**：组织/项目查询、设备和机巢管理、航线、飞行任务、媒体、直播、模型、地图、远程控制等低频查询和业务命令。
2. **FlightHub Sync / EventAPI**：任务状态、媒体、文件和业务事件的异步同步，避免持续轮询。
3. **MQTT Bridge**：高频设备遥测、设备状态和物模型数据转发到平台侧 Broker。
4. **文件同步与 STS 对象存储**：航线 KMZ、巡检照片/视频、模型输入输出等大文件交换。
5. **RTSP/RTMP/GB28181**：直播流接入；按司空 2 私有化版实际许可和部署组件选择。
6. **前端组件（可选）**：选择性复用司空 2 航线编辑器、远程驾驶舱等复杂界面，而不是把完整司空 2 页面嵌入业务主流程。

首期优先完成“连接与项目绑定 → 设备同步 → 航线上传 → 任务下发 → 状态/遥测回传 → 媒体同步 → 平台 AI 分析”的闭环。直播、远程控制、司空 2 建模和变化检测属于后续能力，尤其远程控制必须单独进行飞行安全评审。

## 2. 资料、版本与重要澄清

### 2.1 本次使用的资料

| 资料 | 用途 | 版本注意事项 |
| --- | --- | --- |
| [司空 2 官方使用手册](https://fh.dji.com/user-manual/cn/overview.html) | 产品能力、设备使用、私有化差异、扩展能力 | 官方在线手册会持续更新 |
| [OpenAPI 介绍](https://fh.dji.com/user-manual/cn/custom-development/open-api/api-introduction.html) | OpenAPI 定位、鉴权和基础调用方式 | 官方网页仍包含部分旧版 V1 示例，不能替代私有化 V2 导出规范 |
| [FlightHub Sync](https://fh.dji.com/user-manual/cn/custom-development/flighthub-sync-release/sync-introduction.html) | 文件同步、EventAPI、直播转发、第三方空域 | 应优先使用当前 Sync/EventAPI，不新接已经进入迁移路径的旧云互联 API |
| [MQTT Bridge](https://fh.dji.com/user-manual/cn/custom-development/mqtt-bridge/mqtt-bridge-introduction.html) | 私有化遥测和物模型转发 | 官方说明当前主要验证 EMQX，必须完成实际 Broker 兼容测试 |
| [前端组件](https://fh.dji.com/user-manual/cn/custom-development/frontend-components/component-introduction.html) | 航线编辑、驾驶舱、地图组件 | 需要核对私有化包内 `paas.js` 版本、组件授权和浏览器兼容性 |
| [私有化版本发布记录](https://fh.dji.com/user-manual/en/release-notes/release-notes-private.html) | 部署形态和当前私有化版本边界 | 截至本文日期官方页面最新记录为 v1.6（2026-06-16），实际交付包必须另行冻结 |
| 用户提供的 `【私有化】司空 2 OpenAPI V2.0` 全量文本 | 私有化 V2 能力目录、接口路径、模型和错误码 | 本地附件，不纳入仓库；实现前必须从实际部署环境再次导出 OpenAPI/Apifox 规范 |
| `https://henvmbbf6x.apifox.cn/8983545m0` | OpenAPI 高级能力教程 | 该页面实际内容是“AI 变化检测”，不是私有化部署手册 |

### 2.2 必须澄清的材料问题

用户提供的 `8983545m0` 页面经内容核对，是媒体/模型 AI 变化检测教程。司空 2 官方手册所说的“私有化部署手册”是随交付获取的另一份部署材料，当前附件中没有服务器规格、节点拓扑、端口矩阵、离线安装、备份恢复、升级回滚等完整部署内容。

因此在进入生产实施前，必须向大疆或实施方补齐：

- 实际交付版本对应的《私有化部署手册》和《运维手册》；
- 该版本的 OpenAPI V2 OpenAPI/Swagger JSON 或 Apifox 导出文件；
- FlightHub Sync、EventAPI 的事件 Schema 与签名/重试规则；
- MQTT Bridge Topic、物模型字段、频率和 QoS 说明；
- 支持设备、固件、机场、载荷、直播和建模的兼容矩阵；
- License 项、在线设备数、可用模块和扩容方式；
- 域名、证书、端口、对象存储、Broker、时钟同步、备份和灾备要求。

### 2.3 当前版本边界

司空 2 公有版 OpenAPI V2.0 在官方发布记录中于 2026-05-27 发布，私有版文档随后独立。私有化平台版本、OpenAPI 文档版本和设备固件版本不是同一个版本号，三者必须组成一张冻结矩阵：

| 维度 | 需要冻结的值 |
| --- | --- |
| 司空 2 私有化平台 | 交付版本、补丁号、镜像/安装包校验和 |
| OpenAPI | V2.0 文档导出时间、Schema 版本、网关前缀 |
| FlightHub Sync/EventAPI | 客户端/服务端版本、事件版本 |
| MQTT Bridge | 司空 2 端版本、EMQX 版本、Topic/物模型版本 |
| 设备 | 机型、机场、遥控器、负载、固件和 Pilot 2 版本 |
| 前端组件 | `paas.js` 和组件包版本 |

本文中的路径来自当前附件，用于设计和范围估算；开发时必须以部署环境暴露的规范为准。

## 3. 司空 2 私有化平台定位

### 3.1 与原 DJI Cloud API 直连方案的区别

| 维度 | 原方案：平台直连 Cloud API | 新方案：集成司空 2 私有化 |
| --- | --- | --- |
| 设备接入 | 平台承接 DJI MQTT、设备 Topic、Pilot H5 | 设备先接司空 2，平台通过司空 2 扩展接口获取能力 |
| 设备运维 | 平台自行实现拓扑、固件、日志、HMS | 司空 2 负责，大部分只在平台形成业务投影 |
| 航线和任务 | 平台直接编译并向设备协议下发 | 平台上传/创建司空 2 航线和任务，由司空 2 执行 |
| 遥测 | 直接订阅设备 Topic | 通过 MQTT Bridge 转发，必要时结合 OpenAPI 查询 |
| 任务事件 | 解析设备服务回复和事件 | 通过 EventAPI/Sync/任务查询归一化 |
| 媒体 | 平台为设备签发 STS 并处理设备回调 | 优先通过司空 2 媒体/文件同步，再镜像到平台对象存储 |
| 直播 | 平台承接设备推流协议 | 从司空 2 直播能力取流或转发 |
| 远程控制 | 平台直接实现 DRC Topic | 通过司空 2 控制权、飞行命令和 DRC API |
| 厂商适配成本 | 高，且需长期追随设备协议 | 主要适配平台级 API，边界更稳定 |
| 责任边界 | 平台承担大量飞行基础能力 | 司空 2 承担厂商飞行能力，平台聚焦铁路巡检业务 |

原 Cloud API Demo 仍可用于理解大疆概念和 KMZ/WPML，但不应作为新集成的代码基座，也不应在新架构中再部署一套与司空 2 争夺设备连接的 Cloud API 服务。

### 3.2 私有化版的主要价值

依据官方功能差异和扩展能力说明，私有化版适合本项目的原因包括：

- 可部署在内网/专网，数据、地图、媒体和模型留在用户环境；
- 支持定制登录/OAuth、界面和部分前端组件；
- 支持自定义地图、离线地图和高程数据导入；
- 支持完整 OpenAPI，以及 FlightHub Sync、EventAPI 和 MQTT Bridge；
- 支持直播转发、文件同步和第三方业务系统集成；
- 支持私有化自动建模能力，具体额度和并发由交付 License 决定。

私有化也不是公有版的完全镜像。官方资料明确列出部分在线服务在私有版不可用或受限，例如在线天气/电离层信息、一键机场诊断、部分短信/保障服务等；飞行安全数据库也不能假设自动保持最新。平台必须自行保障离线环境下的空域、气象、铁路天窗、禁飞区和固件更新流程。

## 4. OpenAPI V2 能力全景

### 4.1 附件目录统计

对用户提供的全量文本进行结构化解析后，共识别出：

- 638 个文档记录；
- 其中 340 个功能说明、教程或接口记录；
- 298 个数据模型/Schema 记录；
- 14 个主要功能域。

功能记录分布如下：

| 功能域 | 功能/接口记录数 | 主要能力 |
| --- | ---: | --- |
| 设备管理 | 41 | 组织/项目设备、拓扑、设备影子、HMS、网络、NTP、RTK、校准、配对、异步命令 |
| 实时控制 | 40 | 控制权、飞行命令、负载命令、FlyTo、环绕、航线中执行、语音、DRC、TCA |
| 模型 | 33 | 模型文件、分享、下载、地图展示、坐标转换、二维/三维重建 |
| 地图 | 32 | 地图元素、图标、飞行区域、离线地图、信号热力图 |
| 组织与项目 | 29 | 组织、项目、成员、角色、权限树、项目配置 |
| 直播 | 29 | 开停流、状态、Token、清晰度、镜头、录制、分享、C2C |
| 飞行任务 | 28 | 预检、高级创建、列表、详情、活动、航迹、续飞、AI 告警、日志 |
| 高级能力 | 28 | 图片/模型变化检测、人工复核、报告和评估 |
| 媒体 | 27 | 秒传、STS、回调、目录、标签、裁剪、下载、归档、批处理 |
| 航线 | 20 | KMZ 导入、回调、查询、文件夹、锁定、下载、复制、拼接、精细复拍 |
| 开放建模 | 13 | 资源上传、建模任务、任务状态和成果下载 |
| 回收站 | 9 | 软删除、恢复、永久删除、保留策略和磁盘统计 |
| 公共基础 | 6 | 健康检查、STS、飞行记录存储、序列号解密 |
| 调用指南 | 5 | 鉴权、公共参数、请求、响应和错误码 |

这说明司空 2 OpenAPI 已覆盖从组织/设备到飞行、媒体、模型的完整平台能力，但“文档存在”不等于本项目应该全部接入。应按业务必要性、稳定性和飞行风险分级实施。

### 4.2 能力分级建议

| 级别 | 能力 | 集成意见 |
| --- | --- | --- |
| P0 | 鉴权、健康、项目绑定、设备/机场拓扑、航线、任务、状态、遥测、媒体 | 首个生产闭环必须具备 |
| P1 | HMS/设备告警、飞行记录、直播、地图元素、飞行区域、断点续飞 | 形成可运维版本后接入 |
| P1-S | 控制权、暂停/继续/终止、返航、应急命令 | 单独安全设计后启用 |
| P2 | 远程驾驶舱、FlyTo、负载控制、语音、PSDK、TCA | 明确业务场景和责任制度后启用 |
| P2 | 二维/三维重建、变化检测、开放建模 | 与平台现有 AI/点云能力做成本和效果对比后选择 |
| P3 | 组织成员/角色全量同步、回收站管理、复杂分享 | 非业务主链路，按需实现 |
| 不建议首期 | 通过 OpenAPI 管理司空 2 内部所有配置 | 容易把巡检平台变成司空 2 的复制管理后台 |

## 5. 调用协议与通用约束

### 5.1 Base URL 与鉴权

私有化 V2 的典型地址为：

```text
https://<flighthub-private-domain>/openapi/v2.0/...
```

主要请求头：

| 请求头 | 含义 | 实施要求 |
| --- | --- | --- |
| `x-user-token` | 组织级 OpenAPI Key/JWT | 仅保存在密钥管理系统；不得下发浏览器 |
| `X-Project-Uuid` | 当前项目 UUID | 与本地项目绑定表取值，防止跨项目调用 |
| `X-Request-Id` | 请求追踪 ID | 使用平台 trace/request ID，写入协议审计 |
| `X-Organization-Key` | 个别 C2C/转换服务使用 | 与 `x-user-token` 分开建凭据类型，不得混用 |

组织级 OpenAPI Key 需要在司空 2 控制台复制。重新生成后旧 Key 立即失效，因此密钥轮换必须支持“更新密钥引用 → 新连接验证 → 切换流量”的操作流程，不能把 Key 写死在配置文件或数据库明文字段。

### 5.2 响应判断

OpenAPI 通用响应形态为：

```json
{
  "code": 0,
  "data": {},
  "message": "success"
}
```

必须同时判断 HTTP 状态码和业务 `code`：

- HTTP 200 仍可能是业务失败；
- 业务成功以 `code == 0` 为准；
- 不允许通过解析 `message` 判定错误类型；
- 401 表示凭据无效或过期，403 表示权限不足；
- 400/业务参数错误通常不可重试；
- 5xx、网络超时和限流只能按接口幂等性有条件重试。

附件中的错误码按领域分段，覆盖通用鉴权、组织项目、设备 IoT、直播、航线任务、变化检测、远程控制、RTK、AI、同步、设备和机场环境风险等。适配器应保存：

```text
http_status
business_code
business_message
request_id
endpoint
request_digest
response_digest
vendor_task_id
occurred_at
```

同时建立可配置的错误分类表，将厂商错误归一化为：

- `AUTHENTICATION_FAILED`
- `PERMISSION_DENIED`
- `INVALID_REQUEST`
- `DEVICE_OFFLINE`
- `DEVICE_BUSY`
- `SAFETY_PRECHECK_FAILED`
- `WEATHER_BLOCKED`
- `COMMAND_TIMEOUT`
- `CONFLICT`
- `RATE_LIMITED`
- `VENDOR_UNAVAILABLE`
- `UNKNOWN_VENDOR_ERROR`

典型飞行风险错误（例如航线合法性失败、起点与机场距离过远、避障暂停、降雨、大风、结冰风险）不能自动降级绕过，必须进入飞行任务时间线并提示人工处理。

### 5.3 异步任务

设备命令、飞行任务、媒体批处理、建模、变化检测等大量接口是异步的。HTTP 返回只表示“受理”，不表示真实执行成功。

统一处理模式：

```mermaid
sequenceDiagram
    participant P as "巡检平台"
    participant A as "uav-access-service"
    participant F as "司空 2 OpenAPI"
    participant E as "EventAPI/查询接口"

    P->>A: "业务命令 + idempotency_key"
    A->>A: "持久化命令与 Outbox"
    A->>F: "X-Request-Id + OpenAPI 请求"
    F-->>A: "业务 code + task/transaction ID"
    A-->>P: "ACCEPTED"
    E-->>A: "状态事件，或 A 按退避策略查询"
    A->>A: "更新协议命令和映射"
    A-->>P: "标准状态事件"
```

飞行控制命令严禁因为客户端超时就盲目重发。必须先使用请求 ID、厂商任务 ID或查询接口确认结果；无法确认时进入 `UNKNOWN`/`RECONCILING`，由对账任务处理。

### 5.4 文件和 STS

航线、媒体、模型等文件不通过普通 OpenAPI 请求体传输，通用流程为：

1. 获取 STS 或上传上下文；
2. 按返回的 `provider`、`region`、`bucket`、`endpoint`、`object_key_prefix` 上传对象；
3. 调用对应 `upload-callback` / `import-callback`；
4. 查询导入或处理状态；
5. 保存文件摘要和司空 2 资源 ID。

STS 凭据有效期是秒级临时值。不得缓存为长期凭据，不得硬编码 Endpoint、Bucket 或对象前缀。上传器要支持大文件分片、超时、摘要校验和凭据临近过期时重取。

## 6. 各领域接口能力与项目用途

### 6.1 公共基础与健康

代表能力：

- DRC 健康检查：`GET /openapi/v2.0/drc/health`；
- 项目 STS：`POST /openapi/v2.0/storage/api/v1/workspaces/{workspace_id}/sts`；
- 自定义 STS、飞行记录 STS；
- 飞行记录设备序列号解密。

集成用途：

- 连接检查不能只做 TCP/HTTP 探测，要分别验证 DNS/TLS、OpenAPI 鉴权、项目权限、对象存储和可选 DRC；
- 现有 `uav_vendor_connections.health_detail` 可保存分层检查结果；
- 飞行记录中的敏感标识只在有业务依据和授权时解密。

### 6.2 组织、项目、用户与权限

代表能力：

- 查询组织详情和项目列表；
- 项目 CRUD、项目配置；
- 成员、角色和权限树；
- 自动录制等项目设置。

集成边界：

- 司空 2 的“组织/项目”是设备和飞行业务空间，不替代平台已有的铁路局/站段/工区组织体系；
- 鉴权教程明确组织本身不能通过 OpenAPI 创建，必须先在司空 2 控制台创建组织、配置项目并绑定设备；
- 本地保存“平台组织/巡检范围 → 司空 2 组织 UUID/项目 UUID”的显式绑定；
- 首期只读同步项目，项目创建和成员/角色管理继续由司空 2 管理员操作；
- 不同步司空 2 密码或用户 Token，不把司空 2 RBAC 当作铁路业务审批授权。

附件 V2 教程包含快速加入、项目 CRUD 等能力，但官方当前私有化使用手册仍写明部分“快速加入/归档项目”能力不支持。此类冲突必须在实际版本上做契约测试，不能仅凭文档标题启用。

### 6.3 设备、机场和负载

代表接口：

```text
GET /openapi/v2.0/manage/api/v1/organizations/{org_uuid}/manage-devices
GET /openapi/v2.0/manage/api/v1/projects/{proj_uuid}/topologies
GET /openapi/v2.0/manage/api/v1/projects/{proj_uuid}/devices
PUT /openapi/v2.0/manage/api/v1/organizations/{org_uuid}/manage-devices/active-project
```

其他能力：

- 组织和项目设备列表、设备详情、上下级拓扑；
- 一个设备当前激活到一个项目；
- HMS、设备影子、网络、NTP、APN/SIM；
- RTK、账号、校准、配对；
- 通用异步设备命令和命令状态查询。

集成用途：

- 以设备 SN/厂商设备 ID 建立稳定映射，不以显示名称关联；
- 把机场、飞行器、遥控器、负载建为拓扑，不把它们扁平化成一张“无人机”表；
- `uav_devices`、`uav_docks`、`uav_payloads` 保存业务投影，司空 2 仍是厂商状态权威源；
- 设备在项目间切换属于高影响管理操作，首期不从巡检平台开放；
- 网络、校准、配对、固件等运维操作优先跳转司空 2，由司空 2 保留完整操作语义。

### 6.4 航线

主要流程：

1. 将本地已审批的 `route_version` 编译为 DJI KMZ/WPML；
2. 获取司空 2 STS，上传 KMZ；
3. 调用 `/wayline/api/v1/workspaces/{workspace_id}/upload-callback` 或 `import-callback`；
4. 查询导入状态和校验结果；
5. 保存司空 2 航线 ID、文件 ID、摘要和本地版本号；
6. 只有导入成功且设备兼容时才能创建飞行任务。

其他能力包括航线列表/详情、302 下载、文件夹、批量移动/删除、锁定、复制、拼接和精细复拍。

推荐规则：

- 本地 `routes/route_versions/route_waypoints` 是铁路巡检航线权威源；
- 司空 2 航线是不可变的厂商执行制品；
- 本地版本一旦发布后修改，应生成新的厂商航线，不覆盖正在使用的制品；
- 保存 KMZ SHA-256，按 `(connection_id, project_uuid, route_version_id, checksum)` 幂等；
- 司空 2 在线编辑器生成的航线若需要回流，必须经过“导入草稿 → 平台校验 → 业务审批 → 发布”，不能直接成为已审批航线。

### 6.5 飞行任务

附件中任务类型包括：

- 立即任务；
- 周期任务；
- 单次定时任务；
- 连续任务。

代表能力：

```text
GET  /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/check
POST /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/advanced
GET  /openapi/v2.0/task/api/v2/workspaces/{proj_uuid}/flight-tasks
GET  /openapi/v2.0/task/api/v2/workspaces/{workspace_id}/flight-tasks/detail
POST /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/reject-takeoff
```

还包括活动记录、实际航迹、断点续飞、AI 告警、导出和操作日志。运行中的暂停、继续、终止通过 DRC 航线任务命令完成，不应通过数据库状态或普通任务更新接口模拟。

任务下发前必须完成：

- 本地任务已审批，航线版本已发布；
- 平台项目与司空 2 项目绑定有效；
- 设备/机场在线、属于当前项目且能力匹配；
- 司空 2 任务预检通过；
- 航线导入完成且设备可执行；
- 天气、空域、铁路天窗和现场安全策略通过；
- 相同本地任务不存在有效执行任务；
- 计划时间和时区明确。

对于铁路周期计划，推荐由本平台维护周期规则并按执行批次在司空 2 创建单次任务。这样可以把审批、天窗、缺陷复检和计划变更保留在业务平台。只有明确需要司空 2 独立运行且双方已建立对账规则时，才使用司空 2 周期/连续任务。

### 6.6 实时控制与 DRC

控制权接口：

```text
GET    /openapi/v2.0/drc/api/v1/projects/{project_uuid}/cloud_controls
POST   /openapi/v2.0/drc/api/v1/projects/{project_uuid}/cloud_controls
DELETE /openapi/v2.0/drc/api/v1/projects/{project_uuid}/cloud_controls
POST   /openapi/v2.0/manage/api/v1/projects/{project_uuid}/flight-commands
POST   /openapi/v2.0/manage/api/v1/projects/{project_uuid}/payload-commands
```

能力包括飞行控制权、负载控制权、起飞、FlyTo、多点飞行、环绕、返航、在飞航线、负载/相机、PSDK、语音、扬声器和 TCA。

安全要求：

- 飞行控制权和负载控制权分开建模；
- 文档同时提供直接获取控制权和经过授权确认的流程；生产默认采用需要现场/遥控端确认的授权流程，是否允许直接获取必须单独审批；
- 控制权必须有租约、操作者、审批依据、获取时间、过期时间和显式释放；
- UI 必须显示当前控制者和控制权状态；
- 高风险命令二次确认，并写不可篡改审计；
- 业务 HTTP 请求不能同步等待飞行完成；
- 失联、超时、重复点击和多端竞争必须有确定策略；
- 默认禁止自动重试起飞、FlyTo、返航、终止等飞行命令；
- 未完成现场飞行安全评审、应急预案和真机验收前，生产环境只开放只读状态。

官方资料说明第三方直播/控制可能与司空 2 原生操作存在优先级或抢占关系，控制权冲突测试必须纳入验收。

### 6.7 遥测、状态与设备事件

OpenAPI 适合查询和补偿，不适合用高频轮询承载实时遥测。推荐：

- MQTT Bridge：飞机、机场和负载高频 OSD/状态；
- EventAPI：设备上下线、任务、媒体、告警等业务事件；
- OpenAPI：启动同步、详情查询和周期对账；
- FlightHub Sync：文件和跨系统事件同步。

平台消费后归一化为：

```text
DEVICE_TOPOLOGY_CHANGED
DEVICE_ONLINE_CHANGED
DEVICE_HEALTH_CHANGED
TELEMETRY_RECEIVED
MISSION_STATUS_CHANGED
MISSION_PROGRESS_CHANGED
MISSION_TRACK_UPDATED
MEDIA_AVAILABLE
HMS_REPORTED
```

遥测处理要求：

- 以 `(connection_id, device_id, vendor_sequence/event_time, payload_hash)` 去重；
- 同时保存设备事件时间和平台接收时间；
- 标记迟到、乱序、缺失和时钟漂移；
- 高频点批量写入 `telemetry_points`，最新状态进入 Redis，任务结束生成 `flight_tracks`；
- 断线恢复后使用任务详情/航迹接口补偿，不要求 MQTT 绝对不丢；
- MQTT 原始 Topic 和厂商字段只留在适配器协议日志，不扩散到业务 DTO。

### 6.8 直播

推荐使用项目维度 V2 直播接口：

```text
POST /openapi/v2.0/drc/api/v2/projects/{project_uuid}/live-channels/stream/start
POST /openapi/v2.0/drc/api/v2/projects/{project_uuid}/live-channels/stream/stop
GET  /openapi/v2.0/drc/api/v2/projects/{project_uuid}/live-channels/stream/state
```

相关能力包括 Token 更新、清晰度切换、相机/镜头切换、录制、分享和 C2C 转换。直播服务提供方由服务端配置决定，客户端不应硬编码某个云厂商。

平台接入建议：

- `uav-access-service` 管理直播会话、Token 和厂商状态；
- 浏览器只取得平台签发的短时播放授权，不取得组织 OpenAPI Key；
- 视频网关负责协议转换、并发控制、超时释放和审计；
- 需要 AI 视频分析时，从网关旁路取流，不从浏览器回传；
- 专网优先评估 RTSP/GB28181，跨网访问必须经过安全边界；
- 首期以单路低并发验证，明确带宽、端到端延迟和断流恢复指标。

### 6.9 媒体

司空 2 媒体流程覆盖：

- 指纹检查和秒传；
- STS 直传和上传回调；
- 媒体列表、详情、文件夹和飞行任务关联；
- 标签、裁剪和地图展示；
- 软删除、永久删除、异步批处理；
- 302 单文件下载和异步批量打包。

推荐数据策略：

| 数据 | 权威位置 | 处理方式 |
| --- | --- | --- |
| 司空 2 原始飞行媒体 | 司空 2 存储 | 用于飞行作业和原厂功能 |
| 平台巡检原始资源 | 平台 MinIO | 经 Sync/EventAPI 触发后镜像，校验摘要，进入现有 AI 管线 |
| 预处理/切片/AI 证据 | 平台 MinIO | 由平台生成和管理 |
| 司空 2 模型成果 | 司空 2 或镜像到平台 | 按是否参与业务归档决定 |

不建议让 AI 服务长期直接读取司空 2 临时下载 URL。应由接入服务生成媒体可用事件，平台创建 `inspection_resources`，后台复制到平台对象存储并记录来源、厂商媒体 ID、飞行 ID、拍摄时间、位姿和 SHA-256。

### 6.10 地图、飞行区域与离线地图

能力包括地图元素组/元素/图标、分发设备、飞行区域、离线地图包、信号热力图。飞行区域更新使用 `area_hash` 做并发控制。

边界建议：

- 铁路线路、里程、桥隧、边坡、隐患、工区等业务图层继续由平台 PostGIS 管理；
- 只把飞行器执行所需的点线面、警示区和临时作业区同步到司空 2；
- 建立坐标系、WGS84 高程基准和转换精度规范；
- 离线底图和高程由部署团队统一导入司空 2，不通过业务接口频繁管理；
- 同步记录源版本、目标 ID、`area_hash` 和最后对账时间。

### 6.11 模型、重建和开放建模

司空 2 提供：

- 模型文件上传、回调、CRUD、分享和下载；
- 模型地图展示、WKT 和坐标转换；
- 实时二维重建；
- 后处理二维/三维重建、停止、重试和报告；
- 开放建模资源上传、任务创建、状态和成果下载。

与现有平台的关系：

- 司空 2 建模适合航测正射、实景三维和原厂飞行数据快速生产；
- 平台现有 AI 服务负责铁路缺陷识别、点云几何分析、规则判断和样本闭环；
- 两者不是替代关系。建模成果可以成为平台 AI 的输入资源；
- 首期不迁移平台模型管理到司空 2；
- 开放建模的计费/额度在私有化场景可能与公有版文档不同，以 License 和实际返回为准。

### 6.12 AI 变化检测

`8983545m0` 所述高级能力是图片和模型变化检测，包括匹配预检、异步对比、结果查询、人工新增/编辑/删除/忽略、报告和评估。

可用于：

- 同一桥梁/边坡/接触网区段的前后期影像对比；
- 复飞复检前后变化辅助；
- 三维模型周期变化筛查。

不建议直接把变化检测结果作为铁路隐患最终结论。应映射为平台 `AI 候选发现`，经过坐标/里程关联、规则分级和人工复核后再生成告警或工单。

### 6.13 回收站与数据生命周期

支持软删除、恢复、永久删除、保留天数和磁盘统计。项目默认保留天数在文档示例中为 30 天，但实际值应从部署配置读取。

平台不得把司空 2 回收站当作铁路业务归档。业务闭环证据应在平台对象存储和 `archive_packages` 中独立、长期、可校验地保存。永久删除属于高风险管理操作，首期不从巡检平台开放。

## 7. 目标集成架构

```mermaid
flowchart LR
    subgraph Edge["大疆设备侧"]
        DOCK["DJI Dock"]
        UAV["飞行器/负载"]
        PILOT["DJI Pilot 2"]
        UAV --> DOCK
        UAV --> PILOT
    end

    subgraph FH["司空 2 私有化"]
        FHCORE["设备与飞行作业平台"]
        OPENAPI["OpenAPI V2"]
        SYNC["FlightHub Sync / EventAPI"]
        BRIDGE["MQTT Bridge"]
        FILES["司空 2 对象存储"]
        LIVE["直播/媒体/建模"]
        FHCORE --> OPENAPI
        FHCORE --> SYNC
        FHCORE --> BRIDGE
        FHCORE --> FILES
        FHCORE --> LIVE
    end

    subgraph Access["独立 uav-access-service"]
        APP["接入应用层"]
        ADAPTER["FlightHub2 Adapter"]
        INBOX["协议 Inbox / Outbox"]
        RECON["对账与补偿"]
        STREAM["直播/文件连接器"]
        APP --> ADAPTER
        APP --> INBOX
        APP --> RECON
        APP --> STREAM
    end

    subgraph Platform["铁路巡检平台"]
        PLAN["计划/对象/航线/审批"]
        DOMAIN["统一无人机任务域"]
        GIS["遥测/航迹/GIS"]
        RESOURCE["巡检资源"]
        AI["预处理/AI/规则"]
        CLOSED["告警/工单/复检/归档"]
        PLAN --> DOMAIN
        DOMAIN --> GIS
        DOMAIN --> RESOURCE
        RESOURCE --> AI
        AI --> CLOSED
    end

    subgraph Infra["平台基础设施"]
        KAFKA["Kafka"]
        EMQX["EMQX"]
        PG["PostgreSQL/PostGIS"]
        REDIS["Redis"]
        MINIO["MinIO"]
    end

    DOCK --> FHCORE
    PILOT --> FHCORE
    OPENAPI <--> ADAPTER
    SYNC --> ADAPTER
    BRIDGE --> EMQX
    EMQX --> ADAPTER
    FILES <--> STREAM
    LIVE <--> STREAM
    APP <--> KAFKA
    KAFKA <--> DOMAIN
    INBOX --> PG
    DOMAIN --> PG
    GIS --> PG
    RESOURCE --> MINIO
    APP --> REDIS
```

### 7.1 系统责任边界

| 能力 | 司空 2 | `uav-access-service` | 巡检平台 |
| --- | --- | --- | --- |
| 大疆设备接入/协议 | 权威 | 不重复实现 | 不感知协议 |
| 设备厂商状态 | 权威 | 同步和归一化 | 保存业务投影 |
| 铁路设备/线路台账 | 不负责 | 不负责 | 权威 |
| 铁路巡检计划与审批 | 不负责 | 不负责 | 权威 |
| 航线业务版本 | 执行副本 | 编译/导入/映射 | 权威 |
| 飞行任务执行 | 权威执行状态 | 命令、事件、对账 | 业务状态和关联 |
| 高频遥测 | 数据源 | 接收、归一化 | 长期存储、GIS |
| 原始飞行媒体 | 首个落点 | 同步和校验 | 巡检归档权威副本 |
| 原厂直播/建模 | 能力提供者 | 会话和成果适配 | 场景消费 |
| 铁路 AI/规则 | 不负责 | 不负责 | 权威 |
| 告警/工单/复检/归档 | 不负责 | 发布资源事件 | 权威 |

### 7.2 为什么仍然需要独立接入服务

即使司空 2 已经屏蔽设备协议，仍不建议在现有 Spring Boot 业务后端中直接散落 OpenAPI 调用：

- 组织 Key、项目头、STS、错误码和异步状态属于厂商集成语义；
- MQTT Bridge、EventAPI、文件同步与 HTTP 查询需要统一去重和对账；
- 飞行命令的超时处理不同于普通业务接口；
- 司空 2 升级不应迫使巡检业务服务同步发布；
- 后续纵横或其他厂商仍需要相同的统一领域接口；
- 直播、文件传输和高频遥测的伸缩特征与业务 API 不同。

建议沿用原设计的独立 `uav-access-service`，但将 DJI 目录从设备协议实现调整为：

```text
adapter/vendor/flighthub2/
├── auth
├── organization
├── device
├── wayline
├── task
├── control
├── eventapi
├── mqttbridge
├── media
├── livestream
├── model
├── map
├── error
└── reconciliation
```

## 8. 当前项目映射与改造

### 8.1 可直接复用的基础

当前仓库已经具备：

- `UavVendorAdapter` 和 `UavVendorAdapterRegistry`；
- `MissionStateMachine` 和 `InspectionTaskWorkflow`；
- `uav_vendor_connections`、`uav_devices`、`uav_docks`、`uav_payloads`；
- `flight_missions`、`uav_commands`、`vendor_event_inbox`；
- `telemetry_points`、`flight_tracks`；
- 分片上传、`inspection_resources`、预处理和 AI 分析；
- 告警、工单、复检和归档闭环；
- 无人机连接/设备/任务/遥测前端工作台；
- PostgreSQL/PostGIS、Redis、Kafka、MinIO 基础设施。

这些模型证明平台的业务闭环已经形成，不需要重新建设一套巡检业务系统。

### 8.2 现有实现需要调整的点

| 当前实现 | 问题 | 改造 |
| --- | --- | --- |
| 非模拟器连接返回 `MATERIALS_REQUIRED` | 尚无真实厂商适配器 | 增加 `FLIGHTHUB2` 连接类型和独立适配服务 |
| `UavVendorAdapter` 同步返回调用结果 | 不适合司空 2 异步任务和跨服务 | 拆分查询、命令受理、事件消费、文件和直播端口 |
| `dispatchMission` 同步把命令标为 `SUCCEEDED` | 司空 2 返回通常只代表受理 | 改为 `PENDING → ACCEPTED → EXECUTING → SUCCEEDED/FAILED/UNKNOWN` |
| 本地命令直接推动任务状态机 | 会造成“平台认为已飞、实际未执行” | 只有司空 2 事件/查询结果才能确认执行状态 |
| `SIMULATE_PROGRESS` 生成遥测 | 仅适合本地演示 | 生产从 MQTT Bridge/EventAPI 写入 |
| 前端只有单个设备选择 | Dock 任务需要机场、飞行器、负载拓扑 | 按执行模式选择项目、机场/设备、航线能力 |
| 前端立即提示“命令完成” | 异步语义错误 | 显示“已受理”，再订阅状态时间线 |
| 平台分片上传 | 不能直接代替司空 2 媒体同步 | 保留为平台资源入口，新增司空 2 文件镜像作业 |

### 8.3 适配器端口建议

现有单接口可以作为模拟器兼容层，生产端拆为：

| 端口 | 职责 |
| --- | --- |
| `VendorConnectionPort` | 健康、鉴权、项目和依赖检查 |
| `VendorTopologyPort` | 设备/机场/负载同步与能力快照 |
| `VendorWaylinePort` | KMZ 编译后导入、查询、下载和版本绑定 |
| `VendorMissionPort` | 任务预检、创建、查询、取消和对账 |
| `VendorControlPort` | 控制权、飞行/负载命令和命令查询 |
| `VendorTelemetryConsumer` | MQTT Bridge 消息解析和归一化 |
| `VendorEventConsumer` | EventAPI/Sync 事件验签、去重和归一化 |
| `VendorMediaPort` | 媒体发现、下载/同步和元数据归一化 |
| `VendorLivePort` | 直播会话、Token、取流和录制 |
| `VendorModelPort` | 建模和变化检测，可选 |
| `VendorReconciliationPort` | 项目、设备、航线、任务和媒体周期对账 |
| `VendorCapabilityProvider` | 按平台/License/设备/固件返回能力矩阵 |

业务平台只调用厂商无关的命令，不出现司空 2 路径、错误码或模型。

## 9. 数据模型设计

### 9.1 保留和扩展现有业务表

| 表 | 建议 |
| --- | --- |
| `uav_vendor_connections` | 保留业务投影；增加司空 2 连接类型和能力快照，敏感值仍只存 `secret_ref` |
| `uav_devices` | 增加父设备、网关设备、固件、项目、在线/绑定状态字段或扩展 JSON |
| `uav_docks` / `uav_payloads` | 保存从司空 2 拓扑同步的投影 |
| `flight_missions` | 增加外部任务 UUID、flight ID、执行模式、外部状态、对账时间 |
| `uav_commands` | 保留平台业务命令，增加受理/执行/未知状态，不保存完整敏感协议报文 |
| `vendor_event_inbox` | 若独立服务上线则迁移为接入侧 Inbox，平台只消费标准事件 |
| `telemetry_points` / `flight_tracks` | 保留，增加数据源和质量/补偿标记 |
| `inspection_resources` | 增加司空 2 媒体/飞行来源和对象摘要 |

### 9.2 接入服务建议表

| 表 | 核心字段 | 用途 |
| --- | --- | --- |
| `access_vendor_connections` | `id, vendor, base_url, org_uuid, secret_ref, tls_profile, capabilities` | 私有化实例连接 |
| `flighthub_project_bindings` | `connection_id, platform_scope_id, org_uuid, project_uuid, status` | 平台范围与司空 2 项目绑定 |
| `access_device_bindings` | `connection_id, vendor_device_id, platform_device_id, parent_vendor_id, project_uuid` | 设备标识映射 |
| `route_vendor_artifacts` | `route_version_id, project_uuid, vendor_wayline_id, checksum, import_status` | 本地航线版本与 KMZ/司空 2 航线绑定 |
| `mission_vendor_bindings` | `mission_id, vendor_task_uuid, vendor_flight_id, task_type, last_vendor_status` | 飞行任务关联 |
| `access_commands` | `platform_command_id, endpoint, request_id, vendor_task_id, state, result_code` | 厂商命令受理和执行 |
| `control_leases` | `project_uuid, device_id, control_type, holder, acquired_at, expires_at, released_at` | 飞行/负载控制权 |
| `access_event_inbox` | `source, vendor_event_id, event_type, payload_hash, raw_payload, processed_at` | 原始事件幂等 |
| `access_outbox_events` | `event_id, type, aggregate_id, payload, publish_state` | 标准事件可靠发布 |
| `mqtt_ingest_offsets` | `client_id, topic, sequence, event_time, payload_hash` | 遥测去重和恢复 |
| `media_vendor_bindings` | `vendor_media_id, flight_id, platform_resource_id, checksum, mirror_state` | 媒体镜像 |
| `live_stream_sessions` | `device_id, channel, vendor_session_id, token_expiry, state` | 直播生命周期 |
| `reconciliation_checkpoints` | `resource_type, project_uuid, cursor, last_success_at` | 增量对账 |

每张接入表必须包含 `connection_id`，项目级数据包含 `project_uuid`。禁止仅用一个全局 `workspace_id` 支持所有司空 2 项目。

### 9.3 关键 ID 映射

```text
inspection_tasks.id
  └── flight_missions.id
        ├── mission_vendor_bindings.vendor_task_uuid
        ├── mission_vendor_bindings.vendor_flight_id
        ├── uav_commands.id
        │     └── access_commands.vendor_task_id/request_id
        ├── telemetry_points.mission_id
        ├── flight_tracks.mission_id
        └── inspection_resources.mission_id
              └── media_vendor_bindings.vendor_media_id

route_versions.id
  └── route_vendor_artifacts.vendor_wayline_id + checksum

uav_devices.id
  └── access_device_bindings.vendor_device_id/SN
```

所有关联都使用专用映射表。不得从任务名称、航线名称或媒体文件名反推关系。

## 10. 核心业务流程

### 10.1 初始化和设备同步

```mermaid
sequenceDiagram
    participant O as "平台管理员"
    participant P as "巡检平台"
    participant A as "uav-access-service"
    participant F as "司空 2"

    O->>P: "配置私有化地址、组织/项目绑定和 secret_ref"
    P->>A: "连接变更事件"
    A->>F: "健康、鉴权、项目、STS/可选 DRC 检查"
    F-->>A: "能力和权限"
    A-->>P: "连接健康与能力矩阵"
    A->>F: "查询项目设备和拓扑"
    F-->>A: "机场/飞机/负载/在线状态"
    A-->>P: "标准拓扑事件"
    P->>P: "更新设备业务投影"
```

连接检查建议分层：

1. DNS 和 TCP；
2. TLS 证书与主机名；
3. OpenAPI 鉴权；
4. 项目访问权限；
5. 设备/任务 API；
6. STS 与对象存储；
7. EventAPI 回调可达；
8. MQTT Bridge；
9. 直播/DRC（启用时）。

### 10.2 航线发布和任务下发

```mermaid
sequenceDiagram
    participant U as "调度员"
    participant P as "巡检平台"
    participant A as "uav-access-service"
    participant F as "司空 2"
    participant D as "DJI Dock/飞行器"

    U->>P: "审批并发布巡检航线"
    P->>A: "生成厂商航线制品"
    A->>A: "编译 KMZ/WPML + 摘要"
    A->>F: "STS 上传 + import callback"
    F-->>A: "导入任务 ID"
    A->>F: "查询导入结果"
    F-->>A: "司空 2 航线 ID/校验"
    A-->>P: "航线制品可用"
    U->>P: "下发巡检任务"
    P->>A: "MISSION_DISPATCH"
    A->>F: "设备建议/任务预检"
    F-->>A: "预检结果"
    A->>F: "创建高级飞行任务"
    F-->>A: "厂商任务 UUID，已受理"
    A-->>P: "MISSION_ACCEPTED"
    F->>D: "执行任务"
    F-->>A: "EventAPI/MQTT 状态和遥测"
    A-->>P: "标准进度、航迹和设备事件"
```

### 10.3 媒体进入 AI 闭环

```mermaid
sequenceDiagram
    participant F as "司空 2"
    participant A as "uav-access-service"
    participant M as "平台 MinIO"
    participant P as "巡检平台"
    participant AI as "AI 服务"

    F-->>A: "媒体可用事件/文件同步"
    A->>F: "查询媒体详情和下载授权"
    A->>M: "流式镜像并计算 SHA-256"
    A-->>P: "inspection.resource.available"
    P->>P: "创建 inspection_resources"
    P->>AI: "预处理和推理任务"
    AI-->>P: "缺陷候选、坐标、置信度、证据"
    P->>P: "规则分级 → 告警 → 工单 → 复检 → 归档"
```

## 11. 状态、幂等与一致性

### 11.1 飞行任务状态

平台统一状态继续使用：

```text
READY
DISPATCHING
DISPATCHED
PREPARING
FLYING
PAUSED
RETURNING
UPLOADING
COMPLETED
CANCELLED
ABORTED
FAILED
DISPATCH_FAILED
UNKNOWN
RECONCILING
```

司空 2 原始枚举必须在部署版本冻结后建立映射表。原则：

- 创建 API 成功只进入 `DISPATCHED`/`ACCEPTED`，不进入 `FLYING`；
- `FLYING`、`PAUSED`、`RETURNING` 由司空 2 状态事件确认；
- 飞行完成但媒体未同步时进入 `UPLOADING`；
- 业务平台收到重复或乱序事件时按厂商事件时间、状态序号和合法转换处理；
- 不识别的厂商状态进入 `UNKNOWN` 并告警，不能默认为成功；
- 周期对账纠正漏事件，但要保留原始事件和更正审计。

### 11.2 幂等键

| 操作 | 幂等键建议 |
| --- | --- |
| 航线导入 | `connection + project + route_version + checksum` |
| 任务创建 | `connection + project + inspection_task + execution_attempt` |
| 平台命令 | 平台生成 UUID，贯穿 `uav_commands` 和 `access_commands` |
| EventAPI | 厂商 event ID；没有时使用稳定字段和 payload hash |
| MQTT 遥测 | 设备 + Topic + 厂商序号/时间 + payload hash |
| 媒体镜像 | 厂商媒体 ID + 文件摘要 |
| 建模/变化检测 | 业务请求 ID + 输入版本摘要 |

如果司空 2 接口没有原生幂等参数，适配器必须先在本地持久化唯一键并串行化同一聚合根的发送。

### 11.3 对账

即使 EventAPI/MQTT 正常，也要运行：

- 设备在线和拓扑短周期对账；
- 活跃飞行任务高频退避查询；
- 当日任务和航迹日终对账；
- 媒体数量、大小和摘要对账；
- 航线制品发布前/使用前对账；
- 长时间 `UNKNOWN` 命令人工处置；
- 司空 2 项目、License 和存储容量每日检查。

## 12. 安全设计

### 12.1 密钥和权限

- `x-user-token`、组织 Key、OAuth 密钥只以 `secret_ref` 引用；
- 使用 Vault/KMS/Kubernetes Secret 等统一密钥设施，禁止明文落库、日志和前端；
- 为不同环境、不同司空 2 实例使用不同凭据；
- 按组织/项目最小权限配置，控制和管理操作与只读同步分开；
- 密钥轮换要考虑旧 Key 立即失效，轮换期间停止高风险命令；
- 请求日志对 Header、STS 临时凭据和下载 Token 全部脱敏。

### 12.2 网络和链路

- 生产仅使用 HTTPS，部署内部 CA 时将证书链显式加入信任库；
- 固定允许的司空 2 域名/IP，防止可配置 Endpoint 形成 SSRF；
- EventAPI 回调使用专用入口、来源白名单、签名、时间戳和重放保护；
- MQTT 使用 TLS、独立账号、最小 Topic ACL 和持久 Client ID；
- 对象存储 Endpoint 单独做网络和证书验证；
- 管理面、API 面、设备面、媒体面和直播面按部署手册分区；
- 所有节点使用统一 NTP，飞行事件、遥测和媒体时间可追溯。

### 12.3 飞行安全

- 司空 2 的接口可调用不代表业务允许调用；
- 起飞、控制权、FlyTo、返航、终止任务、机场操作必须配置角色和二次确认；
- 本地审批、铁路天窗、空域、天气和现场人员确认是独立前置条件；
- 私有化环境不能假设在线飞行安全数据库自动更新，要建立离线更新制度；
- 接口异常不得绕过司空 2 或设备的安全预检；
- 远程控制全程记录操作者、时间、控制权、命令、回执、画面和异常；
- 紧急处置优先遵循设备和现场规程，业务系统不能自创飞控兜底动作。

## 13. 可靠性与可观测性

### 13.1 重试原则

| 请求类型 | 策略 |
| --- | --- |
| GET 查询 | 对网络、5xx、限流做指数退避和抖动 |
| STS 获取 | 可重试；上传前检查剩余有效期 |
| 航线/媒体回调 | 使用本地状态和摘要保证幂等后重试 |
| 任务创建 | 不盲重试；先按本地映射和司空 2 查询对账 |
| 飞行/负载命令 | 默认不自动重试；进入未知状态后查询确认 |
| EventAPI 消费 | Inbox 去重，处理失败进入重试/死信 |
| MQTT 遥测 | 允许少量丢失，依靠序号、质量标记和任务航迹补偿 |

### 13.2 关键指标

```text
flighthub_openapi_requests_total{endpoint,code}
flighthub_openapi_latency_seconds{endpoint}
flighthub_auth_failures_total
flighthub_command_unknown_total{command}
flighthub_event_lag_seconds{event_type}
flighthub_event_duplicates_total
flighthub_mqtt_messages_total{topic_family}
flighthub_mqtt_out_of_order_total
flighthub_reconciliation_drift_total{resource_type}
flighthub_media_mirror_backlog
flighthub_media_mirror_failures_total
flighthub_live_sessions{state}
flighthub_control_leases{type}
```

每次外部调用都关联 `trace_id`、`X-Request-Id`、本地命令 ID、厂商任务 ID 和业务任务 ID。原始请求/响应按安全策略保存摘要或脱敏副本。

## 14. 前端集成策略

### 14.1 推荐组合

主业务采用平台原生 UI，复杂飞行界面选择性使用司空 2 组件：

| 场景 | 推荐方式 |
| --- | --- |
| 计划、审批、巡检任务 | 平台原生 |
| 连接、项目、设备业务投影 | 平台原生，只读为主 |
| 航线业务参数和版本审批 | 平台原生 |
| 复杂航线几何编辑 | 可嵌入司空 2 航线组件，成果回传平台草稿 |
| 飞行任务时间线、遥测、航迹 | 平台原生 |
| 远程驾驶舱 | 后续可嵌入司空 2 驾驶舱组件 |
| 设备固件、校准、深度运维 | 跳转司空 2 |
| 告警、工单、复检、归档 | 平台原生 |

不要在浏览器直接调用 OpenAPI。前端只调用平台 API。官方前端组件示例中的 `projectToken` 属于组织级项目访问凭据；实施前必须向大疆确认该版本是否支持最小范围、短有效期的组件 Token。若只能使用长期组织 Key，不得把它放进普通业务前端，应改用受控内网的专用组件宿主、网关隔离方案，或暂不启用该组件。

### 14.2 当前页面改造

`UavOperationsView.vue` 后续需要：

- 连接表展示司空 2 实例、组织/项目、OpenAPI/EventAPI/MQTT/存储分层健康；
- 同步设备按钮对 `FLIGHTHUB2` 可用，不再只允许 `SIMULATOR`；
- 设备卡片支持机场—飞行器—负载拓扑；
- 下发页面展示司空 2 航线导入状态和任务预检结果；
- 命令反馈从“命令完成”改成“已受理/执行中/完成/未知”；
- 任务抽屉增加厂商任务 UUID、活动记录、命令回执、媒体数量和对账状态；
- 遥测使用 WebSocket/SSE 增量更新，不持续拉取完整列表；
- 高风险控制入口受能力矩阵、角色和安全开关控制。

## 15. 私有化部署与联调前置条件

### 15.1 环境清单

官方私有化发布记录显示，早期版本已经支持容器化部署、离线地图、本地账号和 OAuth2，近期版本又增加了可视化部署、增量升级和一体化运维控制台。但这些发布说明不能代替交付版本的节点拓扑、资源规格和升级手册，部署设计仍须以实际交付材料为准。

| 项目 | 必须确认 |
| --- | --- |
| 服务器 | 节点角色、CPU/GPU、内存、磁盘、容器运行时、操作系统 |
| 网络 | 管理/设备/API/媒体/直播网段，DNS、NAT、防火墙和端口 |
| 域名/TLS | 司空 2 域名、内部 CA、证书轮换和设备信任 |
| 时间 | NTP 源、所有服务器和设备时区 |
| 存储 | 司空 2 对象存储、平台 MinIO、容量、保留、备份、跨域复制 |
| 消息 | MQTT Bridge 目标 EMQX、TLS、账号、ACL、QoS、保留消息 |
| 回调 | EventAPI 可达地址、签名、重试、限流和高可用 |
| 直播 | SRS/其他服务、RTSP/RTMP/GB28181、带宽和并发 |
| 地图 | 离线地图、高程、坐标系、更新流程 |
| License | 在线设备数、建模、直播、Sync、组件和扩容上限 |
| 运维 | 安装、升级、回滚、备份恢复、日志、监控和大疆支持窗口 |

官方资料建议使用现代浏览器并为实时视频准备充足带宽；实际项目应以并发直播路数、码率和跨网链路重新计算，不能把单终端建议值当成集群容量设计。

### 15.2 Broker 和文件网络

当前仓库基础设施已有 Kafka，但没有可替代 MQTT Bridge 的 MQTT Broker。Kafka 用于巡检平台内部事件，EMQX 用于接收司空 2 MQTT Bridge，两者职责不同：

```text
司空 2 MQTT Bridge → EMQX → uav-access-service → 标准化/批处理 → Kafka → 巡检平台
```

不能要求司空 2 直接连接 Kafka，也不建议让业务服务直接订阅厂商 Topic。

MQTT Bridge 的启用还可能改变媒体转发链路；开启后是否由设备/司空 2 将媒体直接发送到第三方存储，取决于交付版本和存储配置。必须把“遥测桥接”和“媒体落点”放在同一次联调中确认，不能只验证 Topic 可达。

对象存储需要验证四条链路：

1. 适配服务访问司空 2 STS/OpenAPI；
2. 适配服务按 STS 返回地址访问司空 2 对象存储；
3. 适配服务访问平台 MinIO；
4. 大文件跨网复制的带宽、超时和断点恢复。

## 16. 首批接口最小集合

首期不追求覆盖 340 个功能记录，建议先冻结以下接口集合：

| 序号 | 接口能力 | 目的 |
| ---: | --- | --- |
| 1 | DRC/平台健康 | 基础连通 |
| 2 | 组织详情/项目列表 | 连接和项目绑定 |
| 3 | 项目设备列表 | 设备同步 |
| 4 | 项目设备拓扑 | 机场—飞机—负载关系 |
| 5 | 设备详情/状态/HMS | 可飞性和运维信息 |
| 6 | 航线 STS | KMZ 上传 |
| 7 | 航线上传/导入回调 | 创建司空 2 航线 |
| 8 | 航线导入状态/详情 | 发布门禁和对账 |
| 9 | 任务设备建议/预检 | 下发前安全检查 |
| 10 | 高级飞行任务创建 | 立即/定时任务 |
| 11 | 飞行任务列表/详情 | 状态确认 |
| 12 | 飞行任务活动/操作日志 | 时间线和审计 |
| 13 | 飞行航迹 | MQTT 缺失补偿 |
| 14 | 暂停/继续/终止/返航 | 安全评审后启用 |
| 15 | 媒体列表/详情 | 发现巡检资源 |
| 16 | 媒体下载/文件同步 | 镜像到平台 MinIO |
| 17 | EventAPI | 异步状态和媒体事件 |
| 18 | MQTT Bridge | 高频遥测 |
| 19 | 直播开停/状态/Token | P1 直播 |
| 20 | 项目/设备/任务增量对账 | 可靠性兜底 |

每个接口进入开发前都要形成契约样例：请求头、请求体、成功响应、业务失败、权限失败、超时、重复请求、异步状态、分页和限流。

## 17. 分阶段实施计划

### M0：交付和契约冻结，3～5 个工作日

- 获取真正的私有化部署/运维手册；
- 冻结司空 2、OpenAPI、Sync/EventAPI、MQTT Bridge 和设备固件矩阵；
- 确认首批 Dock/飞行器/负载和业务场景；
- 创建专用组织 Key 和测试项目，完成网络/TLS/NTP/对象存储探测；
- 导出机器可读 OpenAPI 规范和事件/物模型 Schema；
- 明确 License、在线设备数、直播、建模和组件授权；
- 冻结统一命令/事件 Schema 和数据所有权。

**退出条件**：测试环境可访问，至少一套真实设备完成司空 2 绑定，所有接口材料可版本化保存。

### M1：接入底座和只读同步，1～2 周

- 创建独立 `uav-access-service` 和 `uav_access` Schema；
- 实现鉴权、通用响应、错误分类、审计、限流和健康检查；
- 实现连接/项目绑定、设备拓扑和能力矩阵；
- 部署 EMQX，接通 MQTT Bridge；
- 接入 EventAPI/Sync，完成 Inbox/Outbox；
- 改造平台命令为异步事件，前端展示真实连接和设备。

**退出条件**：设备上下线、机场/飞机/负载拓扑和遥测在平台稳定可见，断线后可自动恢复。

### M2：航线和单次任务，2～3 周

- 统一航线到 KMZ/WPML 编译；
- STS 上传、导入回调、状态查询和制品映射；
- 任务设备建议、预检、高级创建和任务详情；
- 建立状态机映射、命令状态、对账和时间线；
- 真机完成“平台审批航线 → 司空 2 → Dock 执行 → 航迹回传”。

**退出条件**：至少 20 次受控真机任务无重复下发、无错误成功状态，异常场景可对账恢复。

### M3：媒体和 AI 闭环，1～2 周

- 接入媒体事件/文件同步；
- 镜像到平台 MinIO，校验摘要和元数据；
- 创建巡检资源并触发现有预处理/推理；
- 跑通告警、工单、复检和归档；
- 验证弱网、大文件、重复媒体、缺失媒体和补传。

**退出条件**：一条真实任务形成可追溯的“飞行—媒体—AI—工单—归档”链路。

### M4：HMS、直播和运维，1～2 周

- 接入设备 HMS 和运维告警；
- 接入直播会话、播放授权、断流恢复和录制；
- 完善连接对账、容量监控、死信和补偿工作台；
- 完成升级、密钥轮换和备份恢复演练。

### M5：远程控制和高级能力，按风险评审实施

- 控制权租约、远程驾驶舱和高风险命令；
- FlyTo、负载控制、语音和 PSDK；
- 司空 2 建模/变化检测和平台 AI 协同；
- 完成专项安全评审、现场 SOP 和真机故障演练。

## 18. 测试与验收

### 18.1 自动化测试

- OpenAPI 契约测试：成功、业务失败、401、403、429/限流、5xx、超时；
- 鉴权轮换测试：旧 Key 失效、新 Key 生效和在途任务不丢；
- 状态映射测试：重复、乱序、未知枚举和非法转换；
- 幂等测试：重复航线导入、重复任务创建、重复命令和事件；
- EventAPI 验签、重放、重试和死信；
- MQTT 重连、重复、乱序、高频和积压；
- STS 过期、分片中断、回调重复和摘要不一致；
- 任务/媒体对账和漏事件补偿；
- 前端权限、控制权竞争和高风险二次确认；
- 接入服务故障不阻塞巡检平台其他业务。

### 18.2 真机验收场景

1. 设备绑定、项目切换、上下线和拓扑变化；
2. 航线合法/非法、设备不兼容和重复发布；
3. 立即任务、单次定时任务、取消和冲突；
4. 起飞前预检失败、机场忙、设备离线；
5. 飞行中暂停/恢复/返航和异常中止；
6. 降雨、大风、结冰风险或模拟错误码；
7. MQTT/EventAPI 断网、恢复、乱序和补偿；
8. 照片/视频正常回传、补传、重复和损坏；
9. 直播切换镜头、断流、Token 过期和并发限制；
10. 司空 2、适配服务、Broker、对象存储任一组件重启；
11. 密钥轮换、证书更新和平台升级；
12. 完整巡检 AI、告警、工单、复检和归档闭环。

### 18.3 建议验收指标

具体数值需结合网络和设备确认，至少应度量：

- 设备上下线传播延迟；
- 遥测端到端延迟、丢失率、乱序率；
- 任务命令受理延迟和最终状态确认时间；
- 重复任务/命令发生率必须为 0；
- 媒体发现、镜像和 AI 启动延迟；
- 任务、媒体日终对账差异；
- 服务重启后的恢复时间；
- 直播首帧、延迟、断流恢复和并发；
- 未知命令状态和人工介入次数。

## 19. 主要风险和待确认事项

| 风险/问题 | 影响 | 处理 |
| --- | --- | --- |
| 当前缺少真正部署手册 | 无法完成生产拓扑和容量设计 | M0 向交付方补齐 |
| 平台版、API 版、固件版不一致 | 字段、枚举和能力漂移 | 建兼容矩阵和契约测试 |
| 附件与官方手册存在能力差异 | 误用不存在/未授权接口 | 以实际部署导出规范和实测为准 |
| OpenAPI 中含大量 `/manage`、`/drc` 内部领域路径 | 升级兼容风险 | 只使用正式文档能力，冻结接口，不逆向调用 UI 私有接口 |
| EventAPI/MQTT 精确 Schema 尚缺 | 无法完成实时数据实现 | 获取正式 Schema 和样例报文 |
| HTTP 受理被误判为执行成功 | 飞行状态错误 | 全面异步化和对账 |
| 司空 2 与平台双份媒体 | 容量和生命周期不一致 | 明确权威副本、摘要和保留策略 |
| 控制权竞争或重复命令 | 飞行安全风险 | 租约、幂等、审计、禁止盲重试 |
| 私有网飞行安全数据更新滞后 | 空域/禁飞风险 | 建立离线更新和人工校验制度 |
| License/设备在线数不足 | 上线后容量受限 | 提前核对授权并做容量压测 |
| 过度同步司空 2 管理能力 | 项目范围膨胀 | 按 P0/P1/P2 分级，管理能力优先留在司空 2 |

需要业务和大疆实施方确认：

1. 首批是 Dock 2、Dock 3 还是 Pilot 2 人工巡检；
2. 飞行器、负载、固件和 Pilot 2 的具体版本；
3. 一个铁路业务范围对应一个还是多个司空 2 项目；
4. 是否完全断外网，地图、高程、气象和飞行安全数据如何更新；
5. 是否采购 Sync、MQTT Bridge、直播、建模、前端组件和 OAuth 能力；
6. 首期是否允许平台远程控制，还是只做任务下发和状态查看；
7. 司空 2 媒体保留期限和平台长期归档期限；
8. 任务、遥测、照片/视频、直播的日峰值和并发；
9. EventAPI 回调和 MQTT Bridge 能否跨安全区访问平台接入服务；
10. 大疆交付方是否承诺 OpenAPI V2 向后兼容和升级通知机制。

## 20. 最终结论

司空 2 私有化不是对现有巡检平台的替代，而是大疆设备与飞行作业的基础平台。正确的集成方式是：

- 用司空 2 承担大疆设备接入、运维、航线执行、飞行控制、媒体、直播和原厂建模；
- 用独立 `uav-access-service` 封装 OpenAPI V2、Sync/EventAPI、MQTT Bridge、STS 和直播协议；
- 继续以当前平台的巡检计划、航线审批、任务、资源、AI、告警、工单和归档为业务权威；
- 用不可变航线制品、显式 ID 映射、异步命令、Inbox/Outbox 和周期对账保证一致性；
- 首期只做设备、航线、任务、遥测和媒体闭环，远程控制及高级能力后置；
- 在编码前先补齐真正的私有化部署手册、实际版本 OpenAPI 规范、EventAPI/MQTT Schema 和真机环境。

旧 Cloud API 方案中“独立接入服务、多厂商适配器、事件化解耦、PostGIS/MinIO/Kafka 复用”的架构判断仍然正确；需要废弃的是“平台直接成为 DJI Cloud API 服务端并承接设备协议”的实现路径。

## 附录 A：关键资料链接

- [司空 2 官方手册首页](https://fh.dji.com/user-manual/cn/overview.html)
- [OpenAPI 介绍](https://fh.dji.com/user-manual/cn/custom-development/open-api/api-introduction.html)
- [使用前准备与设备要求](https://fh.dji.com/user-manual/cn/before-using.html)
- [设备管理](https://fh.dji.com/user-manual/cn/organization-management/device-management.html)
- [创建项目](https://fh.dji.com/user-manual/cn/organization-management/create-a-project.html)
- [公有版发布记录/OpenAPI V2.0](https://fh.dji.com/user-manual/cn/release-notes/release-notes-public.html)
- [私有化版发布记录](https://fh.dji.com/user-manual/en/release-notes/release-notes-private.html)
- [公有版与私有化版功能差异](https://fh.dji.com/user-manual/en/functional-differences.html)
- [FlightHub Sync 介绍](https://fh.dji.com/user-manual/cn/custom-development/flighthub-sync-release/sync-introduction.html)
- [MQTT Bridge 介绍](https://fh.dji.com/user-manual/cn/custom-development/mqtt-bridge/mqtt-bridge-introduction.html)
- [前端组件介绍](https://fh.dji.com/user-manual/cn/custom-development/frontend-components/component-introduction.html)
- [单机场计划库及私有化差异](https://fh.dji.com/user-manual/cn/task-plan-library/single-dock-plan-library.html)
- 私有 OpenAPI V2 调用指南：[认证](https://henvmbbf6x.apifox.cn/8983503m0)、[请求](https://henvmbbf6x.apifox.cn/8983485m0)、[公共参数](https://henvmbbf6x.apifox.cn/8983495m0)、[响应](https://henvmbbf6x.apifox.cn/8983500m0)、[错误码](https://henvmbbf6x.apifox.cn/8983516m0)
- 私有 OpenAPI V2 核心领域：[公共基础](https://henvmbbf6x.apifox.cn/8983521m0)、[组织与项目](https://henvmbbf6x.apifox.cn/8983522m0)、[设备管理](https://henvmbbf6x.apifox.cn/8983525m0)、[实时控制](https://henvmbbf6x.apifox.cn/8983527m0)、[飞行任务](https://henvmbbf6x.apifox.cn/8983529m0)、[航线](https://henvmbbf6x.apifox.cn/8983533m0)
- 私有 OpenAPI V2 数据能力：[地图](https://henvmbbf6x.apifox.cn/8983538m0)、[直播](https://henvmbbf6x.apifox.cn/8983539m0)、[媒体](https://henvmbbf6x.apifox.cn/8983540m0)、[模型](https://henvmbbf6x.apifox.cn/8983542m0)、[开放建模](https://henvmbbf6x.apifox.cn/8996219m0)、[回收站](https://henvmbbf6x.apifox.cn/8983543m0)、[高级能力/变化检测](https://henvmbbf6x.apifox.cn/8983545m0)

## 附录 B：实施产物清单

M0 至 M3 应形成以下可版本化产物：

- `flighthub2-compatibility-matrix.md`
- `flighthub2-openapi-v2.json`
- `flighthub2-eventapi-schemas/`
- `flighthub2-mqtt-thing-model/`
- `flighthub2-error-mapping.yml`
- `flighthub2-capability-matrix.yml`
- `uav-access-events-v1/`
- `wayline-wpml-mapping.md`
- `flighthub2-contract-tests/`
- `flighthub2-runbook.md`
- `flighthub2-secret-rotation-runbook.md`
- `flighthub2-reconciliation-runbook.md`
- 真机测试报告、飞行安全评审记录和上线回滚方案。
