# 铁路无人机智能巡检平台能力补全设计方案

## 1. 文档说明

### 1.1 建设目的

本方案用于指导铁路无人机智能巡检平台从现有业务管理骨架升级为可接入真实无人机、真实空间数据和现场处置流程的生产级系统。建设范围覆盖任务发起、任务规划、自动巡检、数据回传、AI 智能识别、隐患告警、工单派发、现场处置和复核归档九个业务阶段，并补齐权限、安全、组织、审计、可观测性和部署保障能力。

### 1.2 现状基线

现有系统已经具备以下基础：

- Spring Boot 3.3 + Java 17 业务平台。
- Vue 3 + TypeScript + Element Plus 前端。
- PostgreSQL 16 + PostGIS 3.4、Redis、Kafka、MinIO。
- FastAPI 视觉推理、点云分析和模型制品安装服务。
- 巡检任务、资源登记、分析任务、AI 结果、告警、工单、样本与模型管理页面。
- 全链路运行节点、SSE 事件、节点快照、失败重试和运行结果导出。
- Docker Compose 本地及服务器部署基础。

当前主要不足是业务对象不完整、真实设备链路未接入、数据传输与空间计算未生产化、现场证据与复检归档缺失，以及用户组织和安全体系不足。

### 1.3 目标范围

目标系统应满足以下要求：

1. 支持日常、专项和应急巡检计划与任务。
2. 支持铁路线路、桥梁、隧道、防洪设施和电力设施的航线规划。
3. 支持大疆、纵横两类无人机平台并行接入，后续能够扩展其他厂商。
4. 支持无人机、机巢、载荷、航线、任务、遥测、直播和媒体文件统一管理。
5. 支持可见光、红外、视频、点云、TIF、飞行日志和定位数据可靠接入。
6. 支持真实地图、铁路中心线、设施、航线、航迹、告警和工单空间展示。
7. 支持 AI 识别、GIS 规则、告警策略、通知、工单、现场处置和复检销项闭环。
8. 支持本地开发、厂商模拟、服务器部署和生产环境灰度切换。

### 1.4 非目标范围

- 不自行实现飞控底层控制协议、避障算法和适航控制逻辑。
- 不绕过厂商授权直接控制无人机或机巢。
- 不将互联网地图服务作为铁路设施主数据来源。
- 不在第一阶段建设自研通用地图底图或通用低空监管平台。
- 不在缺少真实样本和验收集时宣称模型达到生产精度。

## 2. 设计原则

### 2.1 厂商解耦

巡检任务、航线、设备、遥测、媒体和命令使用平台统一领域模型。大疆、纵横协议只存在于各自适配器内，业务服务不得直接依赖厂商字段、错误码或 SDK 类型。

### 2.2 命令与事件分离

- 任务下发、暂停、恢复、取消、返航等操作属于命令。
- 设备在线、遥测、任务进度、媒体就绪和故障告警属于事件。
- 命令必须记录幂等键、操作者、请求摘要和厂商回执。
- 事件必须记录来源、事件时间、接收时间、序列号和原始报文摘要。

### 2.3 空间事实统一

- PostGIS 保存铁路空间主数据和业务事实数据。
- 无人机原始定位按设备实际坐标系接收并保留。
- 平台标准空间坐标统一为 WGS84，SRID 为 4326。
- 高德地图使用 GCJ-02 展示坐标，转换结果不覆盖主数据。
- 里程、轨道侧别、距离线路中心线等结果由平台空间服务计算。

### 2.4 安全优先

任何远程飞行控制必须经过权限、任务状态、设备状态、天气空域条件和二次确认校验。平台应优先使用厂商已经实现的安全能力，不替代飞控和机巢安全保护。

### 2.5 弱网可恢复

任务状态、遥测和媒体传输允许短时断网，支持本地缓存、重试、断点续传、去重和最终一致。链路恢复后不得产生重复任务、重复资源或重复工单。

### 2.6 渐进式演进

第一期在现有 Spring Boot 工程中按领域包拆分，新增独立无人机接入服务和边缘代理。达到设备数量、消息吞吐或团队规模阈值后，再将 GIS、通知、报告等模块拆分为独立服务。

## 3. 目标业务闭环

```mermaid
flowchart LR
    A["巡检计划"] --> B["巡检任务"]
    B --> C["航线规划与校验"]
    C --> D["厂商任务下发"]
    D --> E["自动巡检与遥测"]
    E --> F["多源数据回传"]
    F --> G["预处理与质量检查"]
    G --> H["AI 与空间规则研判"]
    H --> I["隐患告警与通知"]
    I --> J["责任匹配与工单派发"]
    J --> K["现场处置与证据"]
    K --> L["人工或复飞复检"]
    L --> M["销项归档与报表"]
    M --> N["样本与基线回流"]
    N --> G
```

### 3.1 九阶段目标能力

| 阶段 | 目标能力 | 主要交付模块 |
| --- | --- | --- |
| 任务发起 | 计划、模板、审批、对象、冲突检查 | 计划中心、任务中心、对象台账 |
| 任务规划 | 智能航线、航点编辑、载荷与飞参、安全校验 | 航线中心、GIS 工作台 |
| 自动巡检 | 多厂商下发、遥测、航迹、机巢与异常处置 | 无人机接入服务、飞行监控 |
| 数据回传 | 文件、视频、红外、点云、日志、弱网续传 | 媒体接入、边缘代理、资源中心 |
| AI 识别 | 模型制品、预处理、批处理、视频、多模态 | 算法服务、分析调度、模型中心 |
| 隐患告警 | 分级、去重、策略、通知、回执和升级 | 规则引擎、告警中心、通知中心 |
| 工单派发 | 责任规则、值班、SLA、协同与外部工单 | 工单中心、组织中心、集成适配器 |
| 现场处置 | 移动受理、签到、前中后证据、离线提交 | 移动作业端、证据服务 |
| 复核归档 | 人工复核、复飞、AI 比对、销项与报告 | 复检中心、归档报告中心 |

## 4. 总体架构设计

### 4.1 逻辑架构

```mermaid
flowchart TB
    subgraph Client["终端层"]
        WEB["Web 管理端"]
        MOBILE["移动作业端"]
        SCREEN["态势大屏"]
        PILOT["厂商遥控器或厂商客户端"]
    end

    subgraph Gateway["接入与网关层"]
        API["统一 API 网关"]
        WS["WebSocket/SSE 网关"]
        UAV["无人机接入服务"]
        MEDIA["媒体接入服务"]
        EDGE["机巢边缘代理"]
        NOTIFY["通知适配服务"]
    end

    subgraph Business["业务层"]
        PLAN["计划与任务"]
        ROUTE["航线与调度"]
        ASSET["巡检对象台账"]
        ANALYSIS["分析调度"]
        ALARM["告警中心"]
        ORDER["工单闭环"]
        REVIEW["复检归档"]
        IAM["用户组织权限"]
    end

    subgraph Intelligence["空间与算法层"]
        GIS["GIS 空间服务"]
        PRE["数据预处理"]
        VISION["视觉与红外推理"]
        POINT["点云与变化分析"]
        RULE["业务与空间规则"]
        MODEL["模型治理"]
    end

    subgraph Vendor["外部平台"]
        DJI["大疆 Cloud API"]
        JOUAV["纵横云或纵横云 SDK"]
        AMAP["高德地图开放平台"]
        EXT["既有工单、天气、空域、消息平台"]
    end

    subgraph Data["数据与运行基础"]
        PG["PostgreSQL/PostGIS"]
        REDIS["Redis"]
        KAFKA["Kafka"]
        MINIO["MinIO/S3"]
        OBS["Prometheus + 日志与审计"]
    end

    Client --> API
    Client --> WS
    API --> Business
    API --> Intelligence
    UAV --> DJI
    UAV --> JOUAV
    MEDIA --> DJI
    MEDIA --> JOUAV
    EDGE --> UAV
    GIS --> AMAP
    NOTIFY --> EXT
    Business --> Data
    Intelligence --> Data
    Gateway --> Data
```

### 4.2 物理部署

| 节点 | 部署组件 | 说明 |
| --- | --- | --- |
| 无人机/机巢 | 厂商固件、厂商网关 | 不部署平台核心业务代码 |
| 现场边缘节点 | 边缘代理、上传缓存、流媒体转发、轻量预处理 | 可选，用于弱网、低时延和断网续传 |
| 中心业务服务器 | Nginx、前端、Spring Boot、无人机接入、通知服务 | 业务和厂商接入主节点 |
| 数据基础设施 | PostgreSQL/PostGIS、Kafka、Redis、MinIO | 生产环境使用独立磁盘和备份策略 |
| 算法服务器 | FastAPI 算法服务、GPU 运行时、模型制品目录 | CPU 本地配置保留作开发降级模式 |
| 运维节点 | Prometheus、日志检索、告警、备份任务 | 与业务主机隔离部署时优先 |

### 4.3 服务拆分策略

| 服务 | 建议形态 | 主要职责 |
| --- | --- | --- |
| `platform-backend` | 保留现有 Spring Boot，按领域包重构 | 计划、任务、告警、工单、复检、归档、权限 |
| `uav-access-service` | 新增独立 Spring Boot 服务 | 厂商连接、设备、命令、事件、遥测、任务映射 |
| `media-ingestion-service` | 新增服务，可先并入接入服务 | 上传会话、分片、校验、媒体清单、视频流 |
| `edge-agent` | 新增轻量服务 | 现场缓存、断点续传、命令转发、健康上报 |
| `gis-service` | 第一阶段为后端领域模块 | 图层、坐标、里程、空间规则、地图供应商代理 |
| `notification-service` | 第一阶段为后端领域模块 | 站内信、短信、企业微信等渠道与回执 |
| `vision-inference` | 延续现有 FastAPI | 可见光、分割、红外、变化检测 |
| `pointcloud-analysis` | 延续现有 FastAPI | 点云、TIF、DEM、DSM、形变量测 |
| `artifact-installer` | 延续现有 FastAPI | 模型制品安装、卸载、加载和健康状态 |

### 4.4 关键运行模式

1. **本地开发模式**：厂商模拟器 + MapLibre 离线底图 + CPU 模型或基线引擎。
2. **厂商联调模式**：接入厂商测试环境，任务与命令只允许指定测试设备。
3. **试运行模式**：真实设备接入，远程控制需双人授权，告警和工单并行人工确认。
4. **生产模式**：真实设备、正式地图授权、生产模型、组织权限、通知回执和归档全部启用。

## 5. 多厂商无人机接入设计

### 5.1 统一接入模型

`uav-access-service` 对业务平台提供统一端口，各厂商实现适配器：

```java
public interface UavVendorAdapter {
    VendorCapabilities getCapabilities(String connectionId);
    DevicePage listDevices(DeviceQuery query);
    RouteValidationResult validateRoute(RoutePackage route);
    VendorMissionReceipt dispatchMission(DispatchMissionCommand command);
    CommandReceipt executeCommand(UavCommand command);
    StreamSession openLiveStream(OpenStreamCommand command);
    void acknowledgeEvent(VendorEventEnvelope event);
}
```

适配器不得直接更新业务表。厂商事件先转换为统一事件，再由任务、设备、媒体服务消费。

### 5.2 统一能力矩阵

| 能力 | 平台统一能力码 | 大疆适配 | 纵横适配 | 不支持时处理 |
| --- | --- | --- | --- | --- |
| 设备拓扑 | `DEVICE_TOPOLOGY` | Cloud API 设备拓扑 | 纵横云或 SDK 设备清单 | 设备只读登记 |
| 航线下发 | `MISSION_DISPATCH` | 航线文件与任务服务 | 纵横任务与航线接口 | 禁止下发 |
| 暂停/恢复 | `MISSION_PAUSE_RESUME` | 按产品能力映射 | 按授权接口映射 | 页面禁用并说明原因 |
| 取消/返航 | `MISSION_CANCEL/RTH` | 厂商服务命令 | 厂商服务命令 | 仅允许厂商端操作 |
| 实时遥测 | `TELEMETRY` | MQTT 设备属性/事件 | 纵横云或 SDK 遥测 | 轮询或标记不可用 |
| 直播 | `LIVE_STREAM` | 厂商直播能力 | 纵横实时双光视频能力 | 仅显示已录制视频 |
| 媒体回传 | `MEDIA_UPLOAD` | 媒体库与临时凭证 | 数据回传接口或 SDK | 边缘代理上传 |
| 机巢管理 | `DOCK_CONTROL` | Dock 能力 | 纵横昆仑机库能力 | 人工操作 |
| 远程控制 | `REMOTE_CONTROL` | 受支持产品的控制命令 | 以授权能力为准 | 默认关闭 |

### 5.3 大疆接入方案

#### 5.3.1 接入路径

优先采用大疆 Cloud API，对接 DJI Pilot 2 或 DJI Dock。平台侧建设：

- MQTT 5.0 Broker 或受控 MQTT 接入端，用于设备属性、事件和服务命令。
- HTTPS 接口，用于登录鉴权、航线库、媒体库、地图要素和临时上传凭证。
- WebSocket 接口，用于态势与地图要素实时推送。
- MinIO/S3 对象存储，用于航线文件和媒体文件。
- 直播网关，用于将厂商直播转为前端支持的低延迟播放协议。

Cloud API 通过通用 MQTT、HTTPS 和 WebSocket 协议抽象设备能力，适合在不开发专用飞行 App 的情况下接入第三方云平台。具体产品能力必须在设备采购和版本冻结时按官方支持清单确认。

#### 5.3.2 航线文件

- 平台内部航线使用统一航点模型。
- 大疆适配器负责生成或导入符合 WPML 版本要求的航线包。
- 航线发布前记录 `internal_route_version`、`vendor_format_version`、文件 SHA-256 和验证结果。
- 厂商格式升级时新增转换器版本，不修改已执行任务对应的历史航线文件。

#### 5.3.3 任务下发

1. 业务平台创建 `FlightMission`，状态为 `READY`。
2. 无人机接入服务检查设备、机巢、航线、天气和授权。
3. 通过 Outbox 写入 `MissionDispatchRequested`。
4. 大疆适配器上传航线资源并发送任务准备或执行命令。
5. 保存厂商任务 ID、事务 ID、请求摘要和回执。
6. MQTT 进度事件驱动任务状态更新，不以 HTTP 请求返回作为飞行成功依据。

#### 5.3.4 媒体与直播

- 媒体库上传使用临时凭证和对象存储回调。
- 媒体完成事件必须关联任务、航点、设备、载荷和拍摄时间。
- 直播地址不得直接暴露给非授权用户，统一由流媒体网关签发短时播放地址。
- 直播中断只影响实时观看，不应阻断任务状态和离线媒体回传。

### 5.4 纵横接入方案

#### 5.4.1 接入路径

纵横侧优先采用“纵横云管控平台开放接口或本地部署纵横云 SDK”接入。公开产品能力包含任务航线规划、任务计划、指挥调度、实时视频、遥测、数据回传、设备管理和无人值守机库，但接口路径、消息协议、错误码、授权方式和版本兼容矩阵需以项目获得的正式接口包为准。

#### 5.4.2 联调前置清单

在编码纵横生产适配器前必须取得并冻结以下资料：

- 正式 SDK/API 版本、授权文件和许可范围。
- 支持的无人机、机库、载荷和固件版本矩阵。
- 设备发现、登录、鉴权、令牌刷新和断线重连协议。
- 航线格式、任务下发、暂停、恢复、取消和返航接口。
- 遥测字段、上报频率、时间戳、坐标系和质量标识。
- 实时视频协议、播放鉴权和双光切换方式。
- 媒体清单、文件下载或推送、校验和重传机制。
- 机库开关舱、充电、环境状态和健康告警接口。
- 回调签名、幂等、错误码、限流和测试环境说明。

#### 5.4.3 适配策略

- `JouavCloudAdapter`：纵横云提供网络 API 时使用。
- `JouavSdkAdapter`：本地 SDK 只能运行在指定操作系统或专用主机时，通过边车进程封装为平台内部 gRPC/REST 接口。
- `JouavEdgeBridge`：现场机库网络不能直接访问中心时，由边缘代理建立出站安全通道。
- 正式协议未交付前只实现 `JouavSimulatorAdapter` 和契约测试，不在业务代码中猜测厂商接口。

### 5.5 厂商连接配置

每个连接实例保存：

- `vendor_code`：`DJI`、`JOUAV`。
- `connection_mode`：`CLOUD_API`、`LOCAL_SDK`、`EDGE_BRIDGE`、`SIMULATOR`。
- `environment`：`LOCAL`、`SANDBOX`、`STAGING`、`PRODUCTION`。
- 服务地址、工作空间、组织标识和能力开关。
- 密钥引用，不保存明文密钥。
- IP 白名单、证书、回调地址和时间同步配置。
- 最近连接、最后事件、延迟、错误和熔断状态。

连接检查分四层：网络可达、认证成功、能力查询成功、业务握手成功。页面不得仅凭端口可达显示“服务可用”。

### 5.6 统一设备与任务状态

#### 设备状态

`UNREGISTERED -> OFFLINE -> ONLINE -> BUSY -> ONLINE`

异常状态包括 `DEGRADED`、`MAINTENANCE`、`FAULT`、`DISABLED`。设备状态由最近遥测、厂商健康告警和人工维护状态共同计算。

#### 飞行任务状态

```text
DRAFT -> VALIDATING -> READY -> DISPATCHING -> DISPATCHED
       -> PREPARING -> FLYING -> PAUSED -> FLYING
       -> RETURNING -> UPLOADING -> COMPLETED
```

终止状态为 `CANCELLED`、`DISPATCH_FAILED`、`ABORTED`、`FAILED`。任何状态变化必须记录状态前值、后值、来源、原因和时间。

### 5.7 命令可靠性

- 所有厂商命令使用 `idempotency_key`。
- 命令先落库后发送，采用 Outbox 模式发布。
- 超时重试采用指数退避，飞行控制类命令不得无限重试。
- 厂商回执按 `vendor_transaction_id` 去重。
- 对状态不确定的命令先查询厂商任务状态，再决定重发。
- 暂停、恢复、取消、返航属于高风险命令，必须记录操作者和确认信息。

## 6. GIS 与高德地图接入设计

### 6.1 地图技术路线

GIS 采用“空间事实服务 + 可替换地图提供商”架构：

- PostGIS 管理铁路中心线、桥梁、隧道、防洪点、电力设施、航线、航迹、告警和工单空间对象。
- `gis-service` 提供图层、空间查询、里程换算、坐标转换和规则计算。
- 前端通过统一 `MapProvider` 接口选择高德在线地图或 MapLibre 自有/离线底图。
- 高德 Web 服务只通过后端代理访问，避免 Web 服务密钥暴露。

### 6.2 高德能力使用范围

| 高德能力 | 使用方式 | 平台用途 |
| --- | --- | --- |
| JavaScript API 2.0 | 前端按需加载 | 在线底图、覆盖物、交互编辑、标记与信息窗 |
| Web 服务 API | 后端代理 | 地理编码、逆地理编码、行政区和必要的坐标转换 |
| 天气服务 | 后端缓存，可选 | 任务规划的辅助天气信息 |
| 路线规划 | 仅用于地面车辆或人员 | 不用于无人机航线规划 |

生产使用前应完成账号、Key、域名白名单、配额和商用授权确认。铁路专有线路、里程、设施和禁飞区域不得依赖高德 POI 自动生成。

### 6.3 坐标体系

| 数据 | 入库坐标 | 展示处理 |
| --- | --- | --- |
| 无人机 GPS/RTK | 原始坐标保留，标准化为 WGS84 | 高德展示时转 GCJ-02 |
| 铁路中心线与设施 | WGS84 或工程坐标转换后的 WGS84 | 根据地图提供商转换 |
| 高德 API 返回 | GCJ-02 | 仅用于展示或地址辅助，标记来源 |
| 地方工程坐标 | 原始值和 EPSG/转换参数保留 | 通过受控转换服务得到 WGS84 |

禁止反复在 WGS84 与 GCJ-02 间转换。每条空间数据需记录 `source_crs`、`canonical_crs`、`transform_version` 和 `accuracy_m`。

### 6.4 铁路空间模型

- 线路中心线采用 `MULTILINESTRING`，按区段和上下行组织。
- 桥梁、隧道、防洪设施和电力设施采用点、线、面或三维包围体。
- 航线版本采用 `LINESTRINGZ`，航点使用 `POINTZ`。
- 实际航迹按任务分段保存，实时点写入时序分区表，任务结束后生成简化轨迹。
- 里程映射使用线性参考，保存线路里程原点、方向、断链和换算版本。

### 6.5 空间服务接口

```text
GET  /api/v1/gis/layers
GET  /api/v1/gis/features?layer=&bbox=&zoom=
POST /api/v1/gis/coordinates/transform
POST /api/v1/gis/linear-reference/locate
POST /api/v1/gis/routes/validate
GET  /api/v1/gis/missions/{missionId}/track
GET  /api/v1/gis/alarms?bbox=&severity=&status=
```

### 6.6 前端地图工作台

地图工作台提供稳定图层控制：铁路中心线、巡检对象、航线、实际航迹、无人机、机巢、禁飞区、告警、工单、天气和通信覆盖。支持航点编辑、距离面积量测、里程定位、告警聚合、任务回放和证据联动。

地图提供商切换只影响底图和坐标展示，业务覆盖物统一由平台接口返回。

## 7. 业务模块详细设计

### 7.1 巡检计划与任务中心

#### 7.1.1 业务对象

- 巡检计划：日常、专项、应急。
- 巡检模板：专业、对象类型、默认场景、载荷、飞参和验收要求。
- 巡检对象：线路区段、桥梁、隧道、防洪点、电力设施。
- 巡检任务：一次具体执行单元。
- 任务审批：申请、审核、驳回、撤回、变更。

#### 7.1.2 计划生成

周期计划支持按日、周、月、季度、汛期和自定义 Cron 规则生成任务。生成前检查：

1. 同一对象和时间窗口是否已有有效任务。
2. 无人机、机巢、载荷和飞手是否可用。
3. 天气、空域、线路天窗和施工计划是否冲突。
4. 航线是否已发布且在有效期内。
5. 模型组和规则方案是否已绑定。

应急任务允许跳过普通审批，但必须记录事件来源、授权人和风险确认。

#### 7.1.3 任务页面

- 计划日历、任务列表、任务详情和审批队列。
- 任务参数、对象、航线、设备、载荷、模型和规则完整展示。
- 任务状态、厂商任务、遥测、资源、告警和工单形成统一时间轴。
- 任务复制、批量创建、取消、重排和异常恢复均需权限控制。

### 7.2 巡检对象台账

台账字段包括对象编号、名称、专业、线路、上下行、起止里程、空间几何、责任部门、风险等级、巡检周期、设施属性、有效状态和数据来源。

台账导入支持 GeoJSON、Shapefile、CSV 和外部系统同步。导入时进行坐标系确认、几何合法性、线路归属、里程范围、对象编号唯一性和重复空间对象检查。

### 7.3 航线中心

#### 7.3.1 航线模板

| 对象 | 航线策略 | 关键参数 |
| --- | --- | --- |
| 铁路线路 | 沿中心线偏移或双向平行航线 | 高度、速度、侧偏、航向/旁向重叠率 |
| 桥梁 | 环绕、桥面纵向、桥墩定点 | 环绕半径、层高、云台角、停留时间 |
| 隧道 | 洞口、边坡、明洞和弱点定点 | 安全距离、补光、低速、失联策略 |
| 防洪设施 | 河道/堤坝走廊、重点点位复拍 | 点云密度、重叠率、基线范围 |
| 电力设施 | 通道巡检、杆塔环绕、部件定点 | 导线安全距离、热成像参数、变焦 |

#### 7.3.2 航线生成与校验

航线服务根据空间对象和模板生成候选航线，经人工调整后执行：

- 航点数量、航程、预计时长、电量余量和存储容量检查。
- 起降点、返航高度、地形、障碍物、禁飞区和安全距离检查。
- 载荷动作、云台角、变焦、拍照间隔和采样密度检查。
- 厂商能力与航线格式兼容检查。
- 航线版本审批、发布和回滚。

### 7.4 飞行监控

飞行监控页面按任务显示：

- 计划航线、实际航迹、当前航点和路线完成率。
- 无人机、机巢、载荷、RTK、卫星、电量、速度、高度和链路质量。
- 起飞准备、飞行、暂停、返航、上传和完成步骤。
- 厂商原始状态与平台标准状态的映射结果。
- 设备故障、偏航、低电、失联、强风和媒体异常。

遥测按设备和任务分别管理。前端实时展示使用 WebSocket，历史回放从数据库按时间窗口查询。常规遥测可按 1 Hz 入库，高频原始遥测在边缘端聚合或保存到对象存储，关键状态变化不得采样丢失。

### 7.5 多源数据接入

#### 7.5.1 上传协议

业务资源上传复用现有模型测试分片技术，扩展为：

1. 创建上传会话并声明任务、媒体类型、文件大小、SHA-256 和元数据。
2. 服务返回分片大小、已完成分片和预签名地址。
3. 客户端或边缘代理并发上传分片。
4. 完成时校验大小、摘要、MIME、扩展名和安全扫描。
5. 合并对象并写入资源表。
6. 发布 `inspection.resource.ready` 事件。

#### 7.5.2 资源类型

`IMAGE`、`VIDEO`、`THERMAL_IMAGE`、`THERMAL_MATRIX`、`POINT_CLOUD`、`TIF`、`DEM`、`DSM`、`FLIGHT_LOG`、`TELEMETRY_EXPORT`、`ROUTE_FILE`、`WORKORDER_EVIDENCE`、`REPORT`。

#### 7.5.3 弱网处理

- 边缘代理使用本地持久化队列保存待上传对象。
- 上传会话可跨进程和跨网络恢复。
- 分片重试不重复计算业务资源。
- 相同任务、设备、文件摘要只生成一个资源版本。
- 存储空间不足时按优先级保护遥测、告警证据和原始媒体。
- 中心不可用时保留本地清单，恢复后按采集时间补传。

#### 7.5.4 视频链路

厂商直播进入流媒体网关，转换为前端适配协议，并同步生成：

- 直播会话与授权记录。
- 关键帧、低码率预览和高危告警片段。
- 视频帧时间与遥测时间对齐索引。
- 直播质量、丢帧、码率、延迟和中断指标。

### 7.6 数据预处理与质量中心

预处理从页面固定展示值升级为实际作业流水线：

| 数据 | 处理步骤 | 质量检查 |
| --- | --- | --- |
| 图片 | 解码、EXIF/定位解析、畸变校正、清晰度 | 分辨率、模糊、曝光、定位完整性 |
| 视频 | 探测、转码、抽帧、时间轴建立 | 编码、帧率、丢帧、时长、音视频同步 |
| 红外 | 厂商格式解码、辐射温度矩阵、参数校正 | 发射率、环境温度、测温范围、坏点 |
| 点云 | 解码、去噪、裁剪、配准、坐标转换 | 点密度、覆盖率、配准误差、空洞 |
| TIF/DEM | 投影检查、重采样、切片、基线对齐 | CRS、分辨率、无效值、覆盖范围 |
| 遥测/日志 | 时间标准化、坐标标准化、轨迹重建 | 时间跳变、位置漂移、缺失率、乱序率 |

每个处理步骤生成 `PreprocessStepRun`，记录输入、输出、版本、耗时、日志、质量指标和错误。失败资源进入人工修复队列，不能以固定状态直接进入分析。

### 7.7 AI 分析与模型治理

#### 7.7.1 制品补全

五个模型组必须分别具备可安装制品、预处理配置、推理配置、类别字典、指标报告和回滚版本。制品就绪状态从“已安装”扩展为：

`REGISTERED -> DOWNLOADED -> VERIFIED -> INSTALLED -> LOADED -> WARMED_UP -> ACCEPTED`

只有 `ACCEPTED` 状态可以参与生产路由。

#### 7.7.2 场景覆盖

| 专业 | 首批生产类别 |
| --- | --- |
| 铁路 | 异物侵限、护网破损、轨旁垃圾、扣件异常、道床异常 |
| 桥梁 | 裂缝、渗漏、剥落、钢筋外露、结构变形 |
| 隧道 | 洞口边坡、衬砌裂缝、渗漏水、附属设施异常 |
| 防洪 | 水位异常、河道堵塞、冲刷、边坡塌落、体积变化 |
| 电力 | 异物、绝缘子破损、导线断股、杆塔倾斜、设备发热 |

#### 7.7.3 分析调度

- 根据任务场景、资源类型、设备、载荷和模型路由选择模型组。
- 高危视频进入边缘或实时队列，离线媒体进入批处理队列。
- 单资源失败可重试，不阻断同任务其他资源。
- 推理结果绑定模型版本、参数快照、输入摘要和运行时。
- 生产模型不可自动降级到未验收基线引擎；降级必须明确标记并阻止自动建单。

#### 7.7.4 多模态融合

第一阶段完成统一时间轴和空间配准；第二阶段实现可见光与红外目标关联、图像与点云空间关联；第三阶段再建设融合模型。融合结果必须保留各单模态证据，避免只能看到不可解释的最终分数。

### 7.8 GIS 与规则引擎

规则引擎分为四层：

1. 模型结果阈值规则。
2. PostGIS 空间关系规则。
3. 线路、设施、施工计划和豁免业务规则。
4. 告警去重、聚合和升级规则。

重点空间计算包括：

- `ST_DWithin`：目标与线路、设施或禁入区距离。
- `ST_Contains/ST_Intersects`：目标是否位于规则区或豁免区。
- `ST_LineLocatePoint`：目标在线路中心线上的比例位置。
- `ST_ClosestPoint`：最近线路点和侧别判定。
- GiST 空间索引：按任务范围和时间窗口缩小查询。

规则版本在任务创建时固化。规则调整不改变历史告警结论，重新计算必须生成新的判定版本。

### 7.9 告警与通知中心

#### 7.9.1 告警策略

告警等级和处置策略配置化：

| 等级 | 默认策略 | 自动动作 |
| --- | --- | --- |
| 一级 | 立即处置 | 强提醒、升级通知、自动建单、持续跟踪 |
| 二级 | 限期整改 | 自动建单、责任单位确认、SLA 计时 |
| 三级 | 纳入观察 | 人工研判，可生成观察任务 |
| 提示 | 数据或模型异常 | 进入质量队列，不生成隐患工单 |

#### 7.9.2 去重与聚合

按线路、里程、设施、类别、时间窗口、目标相似度和空间距离判断同一隐患。相同隐患追加新证据和最新观测时间，不重复创建工单。严重度上升时更新主告警并触发升级通知。

#### 7.9.3 通知渠道

第一阶段实现站内通知和 WebSocket 实时推送；第二阶段对接短信、企业微信或既有消息平台；移动 App 推送作为后续扩展。每次通知保存发送、送达、阅读、确认、失败和重试状态。

### 7.10 组织、责任与工单中心

#### 7.10.1 责任模型

组织树覆盖单位、专业、车间、工区、班组和人员，责任规则按以下优先级匹配：

1. 指定设施责任单位。
2. 线路区段 + 专业责任规则。
3. 空间责任区。
4. 值班表与班次。
5. 默认兜底岗位。

匹配过程必须保存命中规则和候选单位，不能继续使用固定责任人。

#### 7.10.2 工单状态

```text
CREATED -> DISPATCHED -> ACCEPTED -> EN_ROUTE -> ON_SITE
        -> PROCESSING -> SUBMITTED -> REVIEWING
        -> REINSPECTION_REQUIRED -> REINSPECTING -> REVIEWING
        -> CLOSED -> ARCHIVED
```

分支状态包括 `REJECTED`、`REDISPATCHED`、`SUSPENDED`、`CANCELLED` 和 `RETURNED`。

#### 7.10.3 SLA

按告警等级和专业配置确认时限、到场时限、处置时限和复核时限。支持暂停计时、恢复、超时升级、催办和免责原因。SLA 计算使用业务日历，所有变化保留审计记录。

### 7.11 现场处置与证据

移动作业端采用 Vue 3 响应式页面或独立 PWA，复用现有 API 和权限体系。主要功能：

- 工单接收、拒收、转派、协办和联系责任人。
- 出发、到场签到、隐患确认和处置步骤记录。
- 整改前、整改中、整改后照片和视频上传。
- GPS、拍摄时间、设备、上传人和水印信息绑定。
- 维修措施、材料、人员、设备、安全措施和结果填写。
- 离线缓存、恢复上传和冲突提示。
- 原始告警证据与现场证据并排对比。

附件上传使用统一上传会话，不允许前端直接提交任意对象存储地址。服务端校验工单权限、文件类型、摘要、位置和拍摄时间。

### 7.12 复检、销项与归档

#### 7.12.1 复检方式

- 人工复核：适合可直接确认的轻微隐患。
- 无人机复飞：继承原航线或自动生成目标点复拍航线。
- AI 比对：同目标配准后比较缺陷范围、温度、位移或体积。
- 组合复核：高风险隐患要求人工、复飞和 AI 结果同时通过。

#### 7.12.2 复飞任务

从工单创建 `ReinspectionRequest`，自动关联原任务、告警、航线、对象和目标坐标。复飞任务是新的巡检任务，但通过 `parent_task_id` 和 `workorder_id` 保持闭环关系。

#### 7.12.3 归档包

归档包至少包含：任务单、审批记录、航线版本、设备与飞行记录、原始资源清单、AI 结果、规则判定、告警、通知、工单操作、现场证据、复检结论、销项结论和文件摘要清单。

归档后业务数据只允许追加调阅和更正记录，不允许覆盖历史证据。

## 8. 数据模型设计

### 8.1 新增核心表

| 表 | 关键字段 | 用途 |
| --- | --- | --- |
| `inspection_plans` | id、type、schedule_rule、template_id、status | 巡检计划 |
| `inspection_objects` | id、type、line_id、mileage、geom、owner_org_id | 巡检对象台账 |
| `inspection_task_objects` | task_id、object_id、required_actions | 任务与对象关系 |
| `route_templates` | id、object_type、payload_rules、flight_rules | 航线模板 |
| `routes` | id、name、object_id、status | 航线主记录 |
| `route_versions` | id、route_id、version、geom、checksum、status | 航线版本 |
| `route_waypoints` | route_version_id、seq、geom、actions、speed | 航点与动作 |
| `uav_vendor_connections` | id、vendor、mode、environment、secret_ref、status | 厂商连接 |
| `uav_devices` | id、vendor_device_id、vendor、model、capabilities、status | 无人机设备 |
| `uav_docks` | id、vendor_dock_id、geom、capabilities、status | 机巢设备 |
| `uav_payloads` | id、device_id、type、model、calibration | 载荷台账 |
| `flight_missions` | id、task_id、route_version_id、device_id、status | 平台飞行任务 |
| `vendor_mission_bindings` | mission_id、vendor_mission_id、adapter_version | 厂商任务映射 |
| `uav_commands` | id、mission_id、type、idempotency_key、status | 厂商命令审计 |
| `vendor_event_inbox` | vendor、event_id、event_type、payload、processed_at | 厂商事件去重 |
| `telemetry_points` | mission_id、device_id、event_time、geom、metrics | 遥测与位置 |
| `flight_tracks` | mission_id、geom、start_at、end_at、quality | 任务航迹 |
| `upload_sessions` | id、task_id、file_name、size、sha256、status | 上传会话 |
| `upload_parts` | session_id、part_no、etag、size、status | 上传分片 |
| `preprocess_jobs` | id、resource_id、pipeline_version、status | 预处理作业 |
| `preprocess_step_runs` | job_id、step、input_ref、output_ref、metrics | 处理步骤 |
| `alarm_policies` | id、scene、severity_rules、sla_policy_id | 告警策略 |
| `notification_deliveries` | alarm_id、channel、recipient、status、receipt | 通知回执 |
| `organizations` | id、parent_id、type、name、status | 组织树 |
| `users` | id、org_id、account、status | 用户 |
| `roles` / `permissions` | id、code、scope | RBAC |
| `responsibility_rules` | line_id、object_type、scene、org_id、priority | 责任匹配 |
| `duty_rosters` | org_id、shift_start、shift_end、user_id | 值班表 |
| `workorder_actions` | workorder_id、action、operator、payload、created_at | 工单操作流水 |
| `workorder_attachments` | workorder_id、phase、resource_id、metadata | 现场证据 |
| `review_records` | workorder_id、type、decision、criteria、reviewer | 复核记录 |
| `reinspection_requests` | workorder_id、task_id、target_geom、status | 复飞申请 |
| `archive_packages` | id、business_id、manifest_url、checksum、status | 归档包 |
| `report_jobs` | id、type、scope、template_version、status | 报告生成 |

### 8.2 现有表扩展

`inspection_tasks` 增加 `plan_id`、`task_type`、`template_id`、`approval_status`、`object_scope`、`planned_start_at`、`parent_task_id` 和 `created_by`。

`inspection_resources` 增加 `upload_session_id`、`vendor`、`device_id`、`payload_id`、`mission_id`、`waypoint_index`、`sha256`、`size_bytes`、`mime_type`、`quality_status`、`source_crs` 和 `canonical_crs`。

`alarms` 增加 `policy_id`、`dedup_key`、`master_alarm_id`、`ack_due_at`、`handle_due_at` 和 `owner_org_id`。

`work_orders` 增加 `owner_org_id`、`assignee_user_id`、`sla_policy_id`、`accepted_at`、`arrived_at`、`submitted_at`、`reviewed_at` 和 `archived_at`。

### 8.3 数据约束

- 所有外部 ID 使用“厂商 + 连接实例 + 外部 ID”联合唯一约束。
- 所有命令使用幂等键唯一约束。
- 空间列使用明确 geometry 类型、SRID 和 GiST 索引。
- 遥测表按月或任务时间分区。
- 厂商原始报文放入 JSONB 或对象存储，但平台标准字段独立成列。
- 证据、模型结果、规则结果和归档文件保存 SHA-256。
- 业务主表使用乐观锁版本号，避免并发状态覆盖。

## 9. 事件与模块交互设计

### 9.1 Kafka 主题

| 主题 | 生产方 | 消费方 |
| --- | --- | --- |
| `inspection.task.events` | 任务中心 | 航线、接入、通知 |
| `uav.device.events` | 无人机接入 | 飞行监控、运维 |
| `uav.mission.events` | 无人机接入 | 任务、媒体、GIS |
| `uav.telemetry.events` | 无人机接入 | GIS、遥测落库、告警 |
| `inspection.resource.events` | 媒体接入 | 预处理、资源中心 |
| `inspection.preprocess.events` | 预处理 | 分析调度、质量中心 |
| `analysis.result.events` | AI 服务 | 规则引擎、样本中心 |
| `alarm.events` | 告警中心 | 通知、工单、GIS |
| `workorder.events` | 工单中心 | 告警、复检、归档 |
| `archive.events` | 归档中心 | 报告、审计 |

事件信封统一包含：

```json
{
  "event_id": "evt-uuid",
  "event_type": "uav.mission.progressed",
  "schema_version": "1.0",
  "occurred_at": "2026-07-22T10:00:00+08:00",
  "received_at": "2026-07-22T10:00:01+08:00",
  "source": "uav-access-service",
  "tenant_id": "railway-org-01",
  "correlation_id": "task-001",
  "idempotency_key": "vendor:event:001",
  "payload": {}
}
```

### 9.2 任务下发交互

```mermaid
sequenceDiagram
    participant U as "任务管理员"
    participant P as "任务与航线服务"
    participant A as "无人机接入服务"
    participant V as "厂商适配器"
    participant D as "无人机或机巢"

    U->>P: 审批并下发任务
    P->>P: 校验航线、设备、载荷、天气和权限
    P->>A: 创建统一飞行任务
    A->>A: 写入命令与 Outbox
    A->>V: 转换厂商航线和命令
    V->>D: 下发厂商任务
    D-->>V: 任务回执与进度事件
    V-->>A: 标准任务事件
    A-->>P: Kafka 任务状态事件
    P-->>U: WebSocket 实时状态
```

### 9.3 数据回传交互

```mermaid
sequenceDiagram
    participant D as "无人机、厂商云或边缘代理"
    participant M as "媒体接入服务"
    participant S as "MinIO/S3"
    participant Q as "Kafka"
    participant P as "预处理服务"
    participant A as "分析调度"

    D->>M: 创建上传会话
    M-->>D: 分片参数或临时凭证
    D->>S: 上传分片
    D->>M: 完成上传
    M->>S: 校验摘要与对象
    M->>Q: inspection.resource.ready
    Q->>P: 启动预处理
    P->>Q: inspection.preprocess.completed
    Q->>A: 创建分析任务
```

### 9.4 工单复检交互

```mermaid
sequenceDiagram
    participant F as "现场人员"
    participant W as "工单中心"
    participant R as "复检中心"
    participant T as "任务中心"
    participant AI as "分析服务"
    participant C as "归档中心"

    F->>W: 提交处置结果与前中后证据
    W->>R: 创建复核请求
    R->>T: 按规则创建复飞任务
    T-->>R: 返回复飞资源
    R->>AI: 整改前后比对
    AI-->>R: 比对指标与证据
    R->>W: 通过或退回
    W->>C: 关闭后生成归档包
```

## 10. 接口设计

### 10.1 通用规范

- 外部 REST 接口统一前缀 `/api/v1`，内部适配接口使用 `/internal/v1`。
- 用户接口采用 OAuth2/OIDC + JWT，服务间使用 mTLS 或短期服务令牌。
- 厂商回调按其协议验签，进入平台后转换为统一事件。
- 写操作支持 `Idempotency-Key`，并返回可追踪的 `request_id`。
- 分页使用 `page_token` 或稳定排序字段，禁止对大表无条件全量查询。
- 错误响应包含平台错误码、可读信息、下游错误摘要和请求 ID，不返回密钥及原始异常堆栈。
- OpenAPI 文档按领域拆分，厂商内部适配接口不暴露给普通用户。

### 10.2 计划、对象与任务接口

```text
POST   /api/v1/inspection/plans
GET    /api/v1/inspection/plans
POST   /api/v1/inspection/plans/{id}/activate
POST   /api/v1/inspection/plans/{id}/generate-tasks
POST   /api/v1/inspection/objects/import
GET    /api/v1/inspection/objects
POST   /api/v1/inspection/tasks
POST   /api/v1/inspection/tasks/{id}/submit
POST   /api/v1/inspection/tasks/{id}/approve
POST   /api/v1/inspection/tasks/{id}/dispatch
POST   /api/v1/inspection/tasks/{id}/cancel
GET    /api/v1/inspection/tasks/{id}/timeline
```

创建任务的目标请求：

```json
{
  "task_type": "SPECIAL",
  "plan_id": "plan-001",
  "object_ids": ["bridge-001"],
  "route_version_id": "route-ver-003",
  "planned_start_at": "2026-08-01T09:00:00+08:00",
  "device_selector": {
    "vendor": "DJI",
    "required_capabilities": ["RTK", "VISIBLE", "THERMAL"]
  },
  "scene_set": ["BRIDGE_CRACK", "BRIDGE_LEAKAGE"],
  "model_profile_id": "profile-bridge-prod",
  "rule_profile_id": "rule-bridge-v2",
  "priority": "HIGH"
}
```

### 10.3 航线接口

```text
POST /api/v1/routes/generate
POST /api/v1/routes
POST /api/v1/routes/{id}/versions
POST /api/v1/route-versions/{id}/validate
POST /api/v1/route-versions/{id}/publish
GET  /api/v1/route-versions/{id}/vendor-preview?vendor=DJI
GET  /api/v1/routes/{id}/versions
```

校验响应需区分 `ERROR`、`WARNING` 和 `INFO`。存在 `ERROR` 时禁止发布；`WARNING` 需要具备权限的人员确认后发布。

### 10.4 厂商与设备接口

```text
POST /api/v1/uav/connections
POST /api/v1/uav/connections/{id}/check
GET  /api/v1/uav/connections/{id}/capabilities
POST /api/v1/uav/connections/{id}/sync-devices
GET  /api/v1/uav/devices
GET  /api/v1/uav/devices/{id}/health
GET  /api/v1/uav/docks
POST /api/v1/uav/missions
GET  /api/v1/uav/missions/{id}
POST /api/v1/uav/missions/{id}/commands
GET  /api/v1/uav/missions/{id}/commands
GET  /api/v1/uav/missions/{id}/telemetry
GET  /api/v1/uav/missions/{id}/events
```

厂商事件入口不沿用当前单一通用回调直接修改任务状态，改为：

```text
POST /internal/v1/vendors/dji/http-callbacks/{eventType}
POST /internal/v1/vendors/jouav/callbacks/{eventType}
MQTT vendor-specific topics -> adapter consumer -> vendor_event_inbox
```

统一命令请求：

```json
{
  "command": "MISSION_PAUSE",
  "reason": "前方临时施工区域待确认",
  "expected_mission_version": 7,
  "confirmation": {
    "mode": "TWO_PERSON",
    "approver_token": "short-lived-reference"
  }
}
```

### 10.5 上传与资源接口

```text
POST   /api/v1/uploads
GET    /api/v1/uploads/{id}
PUT    /api/v1/uploads/{id}/parts/{partNo}
POST   /api/v1/uploads/{id}/complete
POST   /api/v1/uploads/{id}/abort
GET    /api/v1/inspection/resources
GET    /api/v1/inspection/resources/{id}
GET    /api/v1/inspection/resources/{id}/preview
GET    /api/v1/inspection/resources/{id}/download-token
GET    /api/v1/preprocess/jobs
POST   /api/v1/preprocess/jobs/{id}/retry
```

预览和下载均通过短期令牌代理，不直接返回长期可访问的 MinIO 管理地址。

### 10.6 告警、工单与复检接口

```text
GET  /api/v1/alarm-policies
POST /api/v1/alarm-policies
POST /api/v1/alarms/{id}/acknowledge
POST /api/v1/alarms/{id}/merge
GET  /api/v1/alarms/{id}/notifications
POST /api/v1/workorders/{id}/accept
POST /api/v1/workorders/{id}/arrive
POST /api/v1/workorders/{id}/actions
POST /api/v1/workorders/{id}/attachments
POST /api/v1/workorders/{id}/submit
POST /api/v1/workorders/{id}/review
POST /api/v1/workorders/{id}/reinspection
GET  /api/v1/workorders/{id}/timeline
GET  /api/v1/archive-packages/{businessId}
POST /api/v1/reports
GET  /api/v1/reports/{id}/download-token
```

### 10.7 实时接口

- `/ws/v1/uav/devices/{id}/telemetry`：设备实时遥测。
- `/ws/v1/uav/missions/{id}`：任务状态、航迹和告警。
- `/ws/v1/notifications`：当前用户站内通知。
- `/api/v1/runs/{id}/events`：保留 SSE，用于低频业务步骤。

WebSocket 连接必须校验用户对设备、任务和线路的数据权限，并限制订阅数量与消息频率。

## 11. 前端功能与页面改造

### 11.1 左侧导航目标结构

| 一级页面 | 二级功能 |
| --- | --- |
| 工作总览 | 运行指标、待办、设备状态、风险趋势 |
| GIS 态势 | 图层、航线、航迹、设备、告警、工单、回放 |
| 巡检计划 | 日历、周期计划、模板、审批 |
| 巡检任务 | 任务列表、任务详情、任务时间轴 |
| 航线中心 | 模板、自动生成、航点编辑、版本和发布 |
| 无人机运行 | 厂商连接、设备、机巢、飞行任务、实时监控 |
| 数据资源 | 上传、回传、预处理、质量、预览 |
| 智能分析 | 分析任务、结果、证据、规则判定 |
| 告警中心 | 告警、策略、通知、豁免和聚合 |
| 工单中心 | 列表、看板、地图、现场证据、SLA、复核 |
| 样本与模型 | 样本、标注、版本、参数、测试、制品、发布 |
| 报告归档 | 巡检报告、隐患台账、归档包、统计报表 |
| 系统管理 | 用户、组织、角色、责任规则、值班表 |
| 系统运维 | 服务、接口、厂商连接、事件、审计、容量 |

### 11.2 厂商连接页面

页面展示连接模式、环境、授权状态、支持能力、设备数、最后心跳、事件延迟、错误率和熔断状态。操作包括新增、编辑、检查连接、同步设备、停用和查看联调日志。

“检查连接”结果分层展示：

1. 网络可达。
2. 认证有效。
3. 工作空间或组织可访问。
4. 能力清单可读取。
5. 测试设备或模拟器业务握手成功。

### 11.3 航线编辑页面

地图为主体，右侧使用紧凑属性面板。支持：

- 从巡检对象和模板生成航线。
- 拖动、插入、删除航点。
- 配置高度、速度、云台、拍照、录像、变焦和悬停动作。
- 切换厂商预览，查看不支持能力和转换警告。
- 显示预计航程、时间、电量、存储和覆盖率。
- 执行空间与安全校验，定位错误航点。
- 保存草稿、提交审批、发布和查看版本差异。

### 11.4 飞行监控页面

页面固定包含地图、任务步骤、遥测仪表、设备健康、直播、告警和事件流。高风险命令使用明确图标、权限和二次确认；不支持的命令根据能力矩阵隐藏或禁用。

### 11.5 数据接入页面

按任务展示资源接入时间轴：发现文件、创建会话、传输、校验、预处理、质量检查和分析触发。用户可以查看失败原因、重试分片、重跑预处理、预览原始资源和处理后资源。

### 11.6 现场作业页面

移动优先，首页直接展示待接收、处理中和待补充工单。操作按钮随状态变化，证据拍摄支持阶段标签和离线队列。页面不得要求现场人员浏览后台管理表格完成处置。

## 12. 用户、组织、权限与安全

### 12.1 身份与权限

引入 Spring Security，支持对接企业 OIDC/统一身份平台；本地环境提供受限的开发身份服务。权限采用 RBAC + 数据范围：

- 角色控制可执行动作。
- 组织、线路、专业和任务控制可访问数据。
- 高风险飞控、模型发布、归档更正和密钥配置使用独立权限。
- 双人授权操作的发起人和批准人不能相同。

### 12.2 建议角色

`系统管理员`、`任务计划员`、`任务审批人`、`飞行管理员`、`告警研判员`、`工单调度员`、`现场处置人员`、`复核人员`、`算法工程师`、`模型审批人`、`审计员`、`只读用户`。

### 12.3 密钥与证书

- 厂商 AppKey、Secret、License、地图 Key、对象存储密钥保存到密钥管理服务或 Docker Secret。
- 数据库只保存 `secret_ref`。
- 配置页面只允许更新，不返回密钥原文。
- 密钥轮换具有生效时间、回滚窗口和审计记录。
- 厂商回调使用 HTTPS、签名、时间戳、nonce 和重放窗口。

### 12.4 数据安全

- 原始媒体、现场证据和归档包按组织与任务授权访问。
- 下载使用短期令牌，记录访问人、原因、文件、时间和 IP。
- 人员与车牌等敏感信息支持脱敏版本。
- 关键证据文件保存摘要，归档时生成不可变清单。
- 生产环境禁止使用默认密码和明文内部服务令牌。

### 12.5 飞行安全控制

- 生产环境默认关闭通用远程控制，仅开放任务级命令。
- 起飞、返航、应急降落等命令按设备能力和组织制度配置授权。
- 下发前校验航线发布状态、设备在线状态、固件兼容、机巢状态、天气和空域。
- 厂商端安全保护状态优先于平台命令。
- 操作日志记录用户、设备、任务、命令、确认、厂商回执和最终状态。

## 13. 可观测性与运行保障

### 13.1 指标

| 范围 | 关键指标 |
| --- | --- |
| 厂商连接 | 在线率、认证失败、事件延迟、重连次数、限流和错误码 |
| 飞行任务 | 下发成功率、准备时长、中断率、恢复率、任务完成率 |
| 遥测 | 每秒消息、丢失率、乱序率、延迟、位置异常率 |
| 数据传输 | 吞吐、失败分片、重试、摘要失败、上传积压和边缘磁盘 |
| 预处理/AI | 队列、耗时、失败率、GPU/CPU、模型加载和降级次数 |
| 告警/工单 | 告警量、重复率、确认时长、SLA 超时、关闭和复发率 |
| 地图 | 图层接口延迟、瓦片失败、坐标转换失败、空间查询耗时 |

### 13.2 日志与追踪

业务请求、Kafka 事件和厂商消息使用统一 `trace_id`、`correlation_id` 和 `task_id`。厂商原始报文日志进行字段脱敏和大小限制，完整报文按安全策略保存到受控对象存储。

### 13.3 故障处理

- 厂商不可用：熔断命令下发，保留任务并持续查询连接恢复。
- Kafka 不可用：Outbox 保证数据库业务状态不丢失，恢复后补发。
- MinIO 不可用：边缘和上传客户端保留会话，不宣布资源完成。
- 地图不可用：切换 MapLibre 离线底图，空间规则继续在 PostGIS 执行。
- AI 不可用：资源等待重试；未经 AI 验收的结果不得自动建单。
- 通知失败：按策略重试并升级到备用渠道。

## 14. 部署设计

### 14.1 本地开发

Docker Compose 增加以下可选服务：

- `uav-access-service`
- `uav-vendor-simulator`
- `media-ingestion-service`
- `edge-agent`
- `mqtt-broker`
- `stream-gateway`

本地默认使用模拟厂商连接和 MapLibre，不要求厂商密钥或高德 Key。通过环境变量切换：

```text
RAIL_UAV_PROFILE=simulator
RAIL_MAP_PROVIDER=maplibre
RAIL_AUTH_PROFILE=local
RAIL_MODEL_RUNTIME_PROFILE=cpu-local
```

### 14.2 厂商联调

```text
RAIL_UAV_PROFILE=vendor-sandbox
DJI_CONNECTION_ENABLED=true
JOUAV_CONNECTION_ENABLED=true
RAIL_MAP_PROVIDER=amap
RAIL_AUTH_PROFILE=oidc
```

密钥只通过 `.env.local`、Docker Secret 或外部密钥服务注入，`.env.local` 必须加入 `.gitignore`。

### 14.3 服务器生产部署

在现有 Docker Compose 技术路线下按职责拆分主机或节点：

- 接入节点：Nginx、API、WebSocket、MQTT、厂商适配器。
- 业务节点：Spring Boot、通知、报告。
- 算法节点：GPU 推理、点云分析、模型制品。
- 数据节点：PostgreSQL/PostGIS、Kafka、Redis、MinIO。
- 运维节点：Prometheus、日志、告警和备份。

生产数据库、消息队列和对象存储不得与本地默认账户复用。镜像从内网仓库或经过验证的国内代理同步并固定摘要，禁止生产环境使用浮动标签。

### 14.4 容量基线

首期按 20 架无人机、10 个机巢、5 个并发飞行任务设计。规划容量基线：

- 遥测标准入库 1 Hz，每任务高频原始数据单独归档。
- 单任务图片 2,000 张、视频 30 GB、点云 100 GB 可配置。
- 上传服务支持至少 20 个并发会话和分片续传。
- 飞行状态端到端展示延迟目标不高于 3 秒。
- 一级告警从规则命中到站内通知目标不高于 5 秒。

最终容量以试点设备真实码率、频率和任务时长压测结果为准。

## 15. 测试设计

### 15.1 测试分层

| 层级 | 测试内容 | 主要工具或方式 |
| --- | --- | --- |
| 单元测试 | 状态机、字段映射、坐标、规则、权限、SLA | JUnit、pytest、固定样本 |
| 组件测试 | 数据库、Kafka、MinIO、Redis、上传与重试 | Testcontainers 或 Docker Compose |
| 契约测试 | 平台统一接口与大疆/纵横适配器 | 厂商报文样例、JSON Schema、模拟器 |
| 集成测试 | 任务到资源、分析、告警、工单、复检 | 自动化全链路脚本 |
| 前端测试 | 页面状态、地图、上传、证据、权限 | Vitest、Playwright |
| 现场测试 | 真实设备、机巢、航线、弱网、异常恢复 | 厂商测试设备与试点线路 |
| 性能测试 | 遥测、上传、视频、AI、空间查询、并发任务 | k6/JMeter、资源监控 |
| 安全测试 | 鉴权、越权、签名、重放、文件、密钥 | 自动扫描与人工验证 |
| 恢复测试 | 断网、重启、磁盘、队列、数据库恢复 | 故障注入与备份恢复演练 |

### 15.2 厂商模拟器

`uav-vendor-simulator` 应模拟：

- 设备上线、离线、机巢状态和能力清单。
- 任务受理、准备、起飞、飞行、暂停、恢复、返航和完成。
- 正常遥测、乱序遥测、重复事件、延迟事件和时间跳变。
- 下发超时、回执丢失、任务失败、低电、失联和断点续飞。
- 媒体清单、上传成功、摘要错误、缺失分片和重复文件。
- 直播启动、切换清晰度、中断和恢复。

模拟器必须通过与真实适配器相同的统一端口接入，避免只在页面注入固定状态。

### 15.3 厂商契约测试

每个适配器建立版本化契约包：

- 设备与能力字段映射。
- 航线格式转换黄金文件。
- 命令请求和成功、失败、超时回执。
- 任务状态映射和非法状态跳转。
- 遥测精度、单位、坐标和时间戳。
- 媒体元数据和上传完成事件。
- 错误码、限流、重试和鉴权失效。

厂商 SDK/API 升级必须先通过契约测试，再进入联调环境。

### 15.4 GIS 测试

- WGS84、GCJ-02 和地方工程坐标转换样例回归。
- 线路里程映射、断链、上下行、左右侧和最近设施测试。
- 航线与禁飞区、设施和缓冲区相交测试。
- 真实底图与业务图层视觉偏差抽检。
- 高德不可用时切换离线底图，业务空间规则仍应正常。
- 10 万级设施和百万级轨迹点查询性能测试。

### 15.5 数据传输测试

- 1 MB、100 MB、5 GB 和 100 GB 文件分片上传。
- 20%、50% 和 80% 丢包或限速条件下断点续传。
- 客户端、边缘代理和服务重启后的会话恢复。
- SHA-256 不一致、重复分片、乱序分片和过期会话。
- 同一文件重复完成只生成一个业务资源。
- 非法类型、超限大小和恶意文件被拒绝并审计。

### 15.6 业务闭环测试

至少覆盖以下路径：

1. 日常计划自动生成任务并完成审批。
2. 桥梁任务生成航线、校验、发布并下发大疆设备。
3. 纵横任务通过模拟器或测试环境执行并回传遥测。
4. 弱网中断后媒体续传并完成预处理。
5. 生产模型识别结果经 PostGIS 规则生成二级告警。
6. 告警通知责任单位，自动建单并开始 SLA。
7. 现场人员到场并上传整改前中后证据。
8. 工单创建复飞任务，AI 比对通过后销项归档。
9. 重复隐患追加证据，不重复创建工单。
10. 厂商、地图或算法服务故障时执行降级和恢复。

### 15.7 生产验收指标

| 指标 | 验收目标 |
| --- | --- |
| 厂商任务下发成功率 | 测试条件满足时不低于 99% |
| 任务状态最终一致率 | 100% |
| 遥测标准链路延迟 | P95 不高于 3 秒 |
| 上传续传成功率 | 弱网测试场景不低于 99% |
| 文件摘要一致率 | 100% |
| 空间里程定位误差 | 以项目测绘基准验收，需形成专项指标 |
| 一级告警通知延迟 | P95 不高于 5 秒 |
| 工单证据完整率 | 关闭工单 100% 满足对应模板 |
| 未授权飞控命令拦截率 | 100% |
| 归档包摘要校验通过率 | 100% |

算法准确率按专业、类别、天气、距离和设备分别验收，不使用单一总体准确率代替分类指标。

## 16. 分阶段实施计划

### 16.1 阶段总览

| 阶段 | 参考周期 | 建设目标 | 主要退出条件 |
| --- | --- | --- | --- |
| M0 基础治理 | 2 周 | 领域边界、接口规范、权限基础、数据迁移框架 | 统一模型、状态机、API 与迁移评审通过 |
| M1 计划航线与 GIS | 4 周 | 计划、对象、航线、真实 GIS、空间规则 | 可生成、编辑、校验、发布一条真实对象航线 |
| M2 多厂商设备接入 | 6 周 | 接入服务、模拟器、大疆适配、纵横适配骨架 | 至少一家真实设备完成任务与遥测闭环 |
| M3 数据回传与预处理 | 4 周 | 分片上传、弱网、视频、质量流水线 | 多模态资源可靠入库并触发真实预处理 |
| M4 生产 AI 与告警 | 6 周 | 五模型制品、场景覆盖、规则、通知 | 首批类别通过验收集并生成可追溯告警 |
| M5 工单现场与复检 | 5 周 | 组织责任、移动处置、证据、SLA、复飞 | 完成发现到复飞销项的真实闭环 |
| M6 归档与生产加固 | 4 周 | 报告、归档、安全、监控、备份、压测 | 生产验收条件全部通过 |

周期从接口、设备、样本和试点线路资料齐备后开始计算。大疆与纵横可并行联调，但应先完成统一适配接口和模拟器。

### 16.2 M0：基础治理

#### 工作项

- 将现有后端按 `planning`、`mission`、`resource`、`analysis`、`alarm`、`workorder`、`review`、`iam`、`integration` 分包。
- 引入 Spring Security、用户、组织、角色、权限和审计上下文。
- 建立统一错误码、事件信封、Outbox/Inbox 和状态机组件。
- 新建 V13 起的 Flyway 迁移，禁止修改既有迁移。
- 完成厂商、地图、消息和模型配置的密钥引用机制。
- 建立 `uav-vendor-simulator` 和适配器契约测试框架。

#### 交付物

领域模型、数据库迁移、统一接口规范、权限矩阵、模拟器、基础自动化测试和升级回滚脚本。

### 16.3 M1：计划、对象、航线与 GIS

#### 工作项

- 建设巡检计划、任务模板、审批和对象台账。
- 导入试点线路、桥梁、隧道、防洪和电力空间数据。
- 建设航线模板、自动生成、航点编辑、校验、版本和发布。
- 将当前 SVG 示意地图替换为真实地图工作台。
- 实现 MapLibre 离线底图和高德在线底图提供商接口。
- 实现 PostGIS 里程定位、空间关系和规则区管理。

#### 退出条件

同一真实巡检对象可在两种底图上准确显示，能够生成和发布厂商无关航线，并通过空间、安全与能力校验。

### 16.4 M2：多厂商接入

#### 工作项

- 建设 `uav-access-service`、连接管理、设备台账、能力矩阵和命令审计。
- 完成 MQTT、WebSocket、HTTPS 接入基础和服务健康监控。
- 实现大疆 Cloud API 适配器、航线转换、任务、遥测、媒体和直播最小闭环。
- 获取纵横正式接口包，实现 Cloud 或 SDK 适配器；资料未齐时完成模拟器和内部封装骨架。
- 建设飞行监控、实际航迹、设备健康和异常处理页面。
- 完成厂商测试环境和真实设备联调。

#### 退出条件

至少一家厂商真实设备完成“平台下发、设备执行、遥测回传、任务结束、媒体关联”；另一家完成正式契约确认和主要接口联调。

### 16.5 M3：数据回传与预处理

#### 工作项

- 将现有业务资源完成通知升级为上传会话和文件协议。
- 建设边缘代理、断点续传、校验、重复检测和容量保护。
- 接入视频流和低延迟播放，建立视频、遥测和任务时间轴。
- 建设图片、视频、红外、点云、TIF 和日志预处理流水线。
- 数据资源页面使用真实进度、质量指标和处理步骤。

#### 退出条件

在规定弱网场景下多模态数据可恢复上传、摘要一致、元数据完整，预处理结果能够可靠触发分析。

### 16.6 M4：生产 AI、规则与告警

#### 工作项

- 安装、校验、加载并验收五个生产模型组。
- 建设首批铁路、桥梁、隧道、防洪和电力缺陷类别。
- 实现视频分析、目标跟踪和关键告警片段。
- 实现 PostGIS 规则、基线、豁免、去重和告警聚合。
- 建设告警政策、处置时限、站内通知和外部消息适配。
- 完成算法、规则、地图和业务联合验收集。

#### 退出条件

生产结果不依赖基线降级引擎，所有告警可追溯到资源、模型、参数、规则、空间位置和通知回执。

### 16.7 M5：现场处置与复检

#### 工作项

- 建设组织、专业、责任区、值班表和自动派单规则。
- 完成工单状态机、受理、转派、协办、SLA 和升级。
- 建设移动作业页面和现场证据上传。
- 建设复核标准、复飞请求、目标复拍和 AI 前后比对。
- 建设销项规则和复发隐患关联。

#### 退出条件

真实用户能够完成告警接收、现场处置、证据提交、复飞复检、退回或销项，所有环节有权限和审计记录。

### 16.8 M6：归档与生产加固

#### 工作项

- 生成巡检报告、隐患台账、处置记录、统计报表和 GIS 专题成果。
- 建设归档包、文件摘要、保留期限和调阅审计。
- 完成生产配置、密钥轮换、备份恢复、灾备和容量压测。
- 完成厂商接口限流、熔断、补偿和升级兼容验证。
- 完成安全测试、用户培训和运行手册。

#### 退出条件

全链路生产验收指标通过，备份可恢复，故障可告警，历史业务可追溯，正式运行和回退方案均已验证。

## 17. 优先级与能力差距映射

### 17.1 P0 必备能力

| 编号 | 能力 | 设计落点 | 实施阶段 |
| --- | --- | --- | --- |
| P0-01 | 巡检类型、周期计划、对象台账 | 计划中心、对象台账 | M1 |
| P0-02 | 智能航线与航点编辑 | 航线中心、GIS | M1 |
| P0-03 | 载荷与飞行参数 | 航线模板、设备能力 | M1-M2 |
| P0-04 | 真实厂商任务下发 | 无人机接入与适配器 | M2 |
| P0-05 | 实时遥测与实际航迹 | 遥测、WebSocket、GIS | M2 |
| P0-06 | 文件上传与弱网续传 | 媒体接入、边缘代理 | M3 |
| P0-07 | 生产模型制品 | 模型治理与算法服务 | M4 |
| P0-08 | 核心缺陷类别与验收集 | 算法服务、样本中心 | M4 |
| P0-09 | 告警策略与通知 | 告警和通知中心 | M4 |
| P0-10 | 组织与责任规则 | IAM、责任匹配 | M5 |
| P0-11 | 现场处置与证据 | 移动作业、统一上传 | M5 |
| P0-12 | 复飞复检与销项 | 复检中心、任务中心 | M5 |
| P0-13 | 正式归档与成果 | 报告归档中心 | M6 |
| P0-14 | 用户、组织与 RBAC | Spring Security、IAM | M0-M1 |

### 17.2 P1 管理效率与稳定性能力

| 编号 | 能力 | 设计落点 | 实施阶段 |
| --- | --- | --- | --- |
| P1-01 | 任务审批、模板、复制和批量创建 | 计划与任务中心 | M1 |
| P1-02 | 天气、空域、天窗和资源冲突检查 | 任务规划与外部集成 | M1-M2 |
| P1-03 | 视频流、关键帧、跟踪和告警片段 | 流媒体网关、视频分析 | M3-M4 |
| P1-04 | 多模态统一时间轴 | 资源与遥测索引 | M3 |
| P1-05 | 真实预处理与质量异常闭环 | 预处理与质量中心 | M3 |
| P1-06 | 可见光、红外、图像和点云融合 | 分析调度与多模态融合 | M4 后续迭代 |
| P1-07 | PostGIS 空间规则与设施图层 | GIS 服务、规则引擎 | M1-M4 |
| P1-08 | 告警去重、聚合、升级和催办 | 告警中心、通知中心 | M4-M5 |
| P1-09 | 工单受理、拒收、转派、协办和会签 | 工单状态机 | M5 |
| P1-10 | SLA、超时、暂停和恢复计时 | SLA 服务、业务日历 | M5 |
| P1-11 | 验收标准、签名和退回原因 | 复检中心 | M5 |
| P1-12 | 隐患台账、复发分析和专业统计 | 报告归档中心 | M6 |
| P1-13 | 数据分级、脱敏、水印和下载审计 | 安全与证据服务 | M5-M6 |
| P1-14 | 接口签名、幂等、重试、死信和补偿 | 接入层、Outbox/Inbox | M0-M3 |

### 17.3 P2 规模化能力

| 编号 | 能力 | 设计落点 | 建议启动条件 |
| --- | --- | --- | --- |
| P2-01 | 多无人机、多机巢智能调度 | 任务调度与资源优化 | 两家厂商单机任务稳定运行后 |
| P2-02 | 大屏态势与领导驾驶舱 | 工作总览、GIS 聚合 | 核心指标和真实数据稳定后 |
| P2-03 | 移动 App、微信和企业微信协同 | 通知适配与移动端 | 统一身份和通知回执完成后 |
| P2-04 | 三维走廊、点云与 BIM/GIS 融合 | 三维空间服务 | 点云基线和设施模型质量达标后 |
| P2-05 | 风险驱动的动态巡检频次 | 风险模型、计划中心 | 隐患台账积累一个完整业务周期后 |
| P2-06 | 自动训练、评测和持续交付 | 模型治理流水线 | 样本质量、算力和审批制度具备后 |
| P2-07 | 跨线路指标对标和趋势预测 | 数据仓库与统计分析 | 多线路数据口径统一后 |
| P2-08 | 灾备、跨节点切换和容量弹性 | 运维与数据基础设施 | 生产规模和 RTO/RPO 明确后 |

P2 能力在 P0/P1 模块中预留接口和数据字段，但不应优先于真实采集、现场证据、权限和归档闭环建设。

## 18. 数据迁移与兼容

### 18.1 迁移原则

- 保留现有任务、资源、分析、告警、工单、模型测试和全链路记录。
- 新增字段先允许为空，通过后台任务补齐后再增加约束。
- 现有 `route_id` 映射为新航线主记录；无法还原航点的航线标记为 `LEGACY_REFERENCE`。
- 当前固定责任人迁移为历史文本，不自动生成真实用户。
- 当前模拟厂商任务标记 `SIMULATED`，不得混入生产设备统计。
- 当前模型降级结果标记运行模式，不能作为生产模型验收数据。

### 18.2 接口兼容

- 现有 `/api/v1/inspection/tasks` 在过渡期保留，内部转换为新任务命令。
- 现有 `/api/v1/uav/callbacks/mission-status` 仅供模拟器和兼容系统使用，生产厂商回调进入专用适配器。
- 现有资源完成接口保留一个版本周期，新增上传会话后标记弃用。
- 前端逐页面迁移，不在一次发布中同时替换所有业务页面。

### 18.3 回退

每个阶段的数据库迁移、配置和服务发布必须具备回退方案。涉及不可逆数据变更时采用新表或新字段并保留旧数据，先双写校验，再切换读取路径。

## 19. 验收清单

### 19.1 业务验收

- 日常、专项、应急任务均能创建、审批和绑定真实对象。
- 航线可自动生成、编辑、校验、发布并转换为厂商格式。
- 大疆和纵横连接可以独立启停，任一厂商故障不影响另一厂商。
- 至少两类真实设备完成任务、遥测、媒体和状态闭环。
- 多源资源能够可靠上传、预处理、预览、分析和追溯。
- 告警能够按策略分级、去重、通知和派单。
- 工单能够自动匹配责任单位并完成现场证据、复检和销项。
- 报告、台账、GIS 成果和归档包能够生成和调阅。

### 19.2 技术验收

- 统一厂商模型中没有业务代码依赖厂商 DTO。
- 任务、命令、回调、资源和工单具有幂等与审计能力。
- PostGIS 空间事实和地图展示坐标职责清晰。
- 生产模型均为 `ACCEPTED`，不存在未标记的降级推理。
- 权限、数据范围、下载和高风险操作均可审计。
- 弱网、厂商故障、地图故障、算法故障和服务重启均通过恢复测试。
- 本地、联调和生产配置隔离，密钥未进入 Git 仓库或镜像。

### 19.3 交付物

- 详细设计、接口规范、数据库字典和事件字典。
- 大疆、纵横适配器及版本兼容矩阵。
- 厂商模拟器和契约测试包。
- 地图、坐标和线路里程专项说明。
- 部署、升级、回退、备份恢复和运维手册。
- 自动化测试、性能测试、安全测试和现场验收报告。
- 模型制品、参数、数据集、指标和发布审批记录。

## 20. 风险与控制措施

| 风险 | 影响 | 控制措施 |
| --- | --- | --- |
| 厂商接口资料或授权晚于开发 | 适配器无法按期联调 | 统一接口和模拟器先行；采购合同明确资料、测试环境与支持时限 |
| 厂商设备能力差异 | 同一功能无法跨设备一致 | 能力矩阵驱动 UI 和命令；不支持能力明确降级 |
| 固件或 SDK 升级 | 接口行为变化 | 固定版本、契约回归、灰度设备、快速回滚 |
| 高德授权或网络受限 | 地图不可用 | MapProvider 解耦、MapLibre 离线底图、PostGIS 独立规则 |
| 坐标系处理错误 | 航线、告警位置偏差 | 单一事实坐标、转换版本、控制点校核和专项验收 |
| 铁路空间数据质量不足 | 里程和责任匹配不准 | 导入校验、数据版本、人工修正和质量报告 |
| 弱网和大文件 | 数据丢失或积压 | 边缘缓存、分片续传、摘要、容量保护和监控 |
| 模型样本不足 | 误报漏报 | 分专业验收集、人工确认、样本回流、禁止未验收模型自动建单 |
| 远程控制误操作 | 飞行安全风险 | 默认关闭、能力校验、最小权限、双人确认和厂商安全优先 |
| 组织责任数据不完整 | 工单无法准确派发 | 责任规则预检查、候选责任队列和兜底调度岗位 |
| 现场证据不可信 | 无法审计销项 | 原文件摘要、拍摄元数据、位置、时间、水印和访问审计 |
| 容量增长超预期 | 队列与存储积压 | 分层存储、容量指标、压测、清理策略和水平扩展 |

## 21. 项目前置决策与外部依赖

正式进入 M2 前需确定：

1. 大疆具体产品、遥控器或机巢型号、固件和 Cloud API 支持范围。
2. 纵横具体产品、纵横云部署模式、SDK/API 版本和授权范围。
3. 两家厂商是否允许私有化部署、所需网络端口、证书和对象存储方式。
4. 试点线路、设备数量、并发任务、数据规模和现场网络条件。
5. 铁路线路中心线、里程、桥隧、防洪和电力设施数据来源与坐标系。
6. 高德地图商用授权、Key 类型、域名白名单和调用配额。
7. 组织、专业、责任区、值班表和工单系统对接方式。
8. 首批缺陷类别、业务阈值、算法验收指标和测试样本集。
9. 飞行审批、空域、天气和线路天窗数据来源。
10. 生产服务器、GPU、存储、备份、内网镜像和安全域规划。

以上事项未确定时，不阻断统一领域模型、模拟器、上传、权限和 GIS 空间服务建设，但不得将未确认的厂商协议和坐标规则固化到核心业务代码。

## 22. 外部接入依据

- [大疆 Cloud API 产品架构](https://developer.dji.com/doc/cloud-api-tutorial/en/overview/product-architecture.html)
- [大疆 Cloud API 功能与接口导航](https://developer.dji.com/doc/cloud-api-tutorial/en/tutorial-map.html)
- [大疆 Cloud API MQTT 基础](https://developer.dji.com/doc/cloud-api-tutorial/en/overview/basic-concept/mqtt.html)
- [大疆航线管理说明](https://developer.dji.com/doc/cloud-api-tutorial/en/feature-set/pilot-feature-set/pilot-wayline-management.html)
- [纵横软件产品与纵横云](https://www.jouav.com/zh/products/software/)
- [纵横昆仑无人值守系统能力](https://www.jouav.com/zh/products/jouav-multirotor-hangar.html)
- [纵横云 SDK 本地接入说明](https://www.jouav.com/zh/news/%E5%9C%A8%E5%B7%9D%E5%85%A8%E5%9B%BD%E4%BA%BA%E5%A4%A7%E8%A1%A8%E5%BC%80%E5%B1%95%E9%9B%86%E4%B8%AD%E8%A7%86%E5%AF%9F%EF%BC%8C%E7%BA%B5%E6%A8%AA%E8%82%A1%E4%BB%BD%E6%8A%A2%E6%8A%93%E4%BD%8E.html)
- [高德地图 JavaScript API 2.0](https://lbs.amap.com/api/javascript-api-v2/summary/)
- [高德地图 Web 服务 API](https://lbs.amap.com/api/webservice/summary)
- [高德地图 JavaScript API 使用与授权说明](https://lbs.amap.com/api/JavaScript-api/summary)

## 23. 结论

能力补全的核心不是在现有页面上继续增加静态状态，而是建立稳定的厂商适配、空间事实、数据传输、状态机、证据和审计体系。建设顺序应先打通真实任务、设备、航线、遥测和媒体，再完成生产模型、告警与现场闭环，最后进行归档和规模化加固。

大疆、纵横和高德均通过可替换适配层接入，PostGIS、统一任务模型和证据链作为平台长期稳定内核。按照 M0 至 M6 分阶段实施后，系统能够从当前管理与算法框架升级为覆盖真实巡检作业、隐患处置和复核归档的生产级铁路无人机智能巡检平台。
