# 铁路无人机智能巡检能力补全实施说明

## 1. 文档信息

| 项目 | 内容 |
|---|---|
| 文档版本 | V1.0 |
| 状态 | 已实施并完成本地集成验证 |
| 更新日期 | 2026-07-22 |
| 实施范围 | 任务规划、航线、无人机接入、数据回传、预处理、GIS、通知、工单、复检、归档及配套测试 |

## 2. 实施结论

本轮已建立从巡检对象、巡检计划、航线发布、任务下发、无人机执行、遥测回传、分片上传、数据预处理，到告警通知、工单处置、复检任务和归档清单的完整平台链路。

系统采用统一领域模型和厂商适配器架构。本地环境通过无人机模拟适配器完成全流程验证；大疆、纵横、高德地图、统一身份、外部消息渠道和生产算法制品均保留明确接入边界，不将缺少授权或业务材料的外部能力伪装为已完成能力。

当前可直接使用的核心能力如下：

1. 巡检对象、周期计划、专项计划、计划启用和任务生成。
2. 航点编辑、三维坐标、载荷动作、飞行参数、航线校验、版本发布和地图展示。
3. 统一无人机连接、设备、任务、命令、状态机、遥测、航迹和厂商事件模型。
4. 模拟无人机的连接检查、设备同步、任务下发、启停控制和飞行进度回传。
5. 大文件分片会话、完整性校验、对象存储、资源登记和预处理质量记录。
6. PostGIS 空间对象、航线、设备、实际航迹和告警的一体化 GIS 图层。
7. 告警责任匹配、站内通知、阅读回执、工单自动创建和全过程状态留痕。
8. 现场处置、证据上传与预览、复核、闭环、复检任务和十年保留归档清单。
9. 桌面端和移动端响应式页面，以及覆盖新增页面和业务接口的自动回归脚本。

## 3. 已落地系统结构

```mermaid
flowchart LR
    UI["Vue 3 前端"] --> API["Spring Boot 业务 API"]
    API --> PLAN["计划与航线领域"]
    API --> UAV["无人机接入领域"]
    API --> DATA["数据接入与预处理"]
    API --> LOOP["告警与工单闭环"]
    API --> GIS["GIS 空间服务"]
    UAV --> ADAPTER["统一厂商适配器"]
    ADAPTER --> SIM["本地模拟器"]
    ADAPTER -.待授权.-> DJI["大疆 Cloud API"]
    ADAPTER -.待接口包.-> JOUAV["纵横云或本地 SDK"]
    GIS --> POSTGIS["PostgreSQL + PostGIS"]
    GIS --> MAPLIBRE["MapLibre"]
    GIS -.待 Key 与授权.-> AMAP["高德地图"]
    DATA --> MINIO["MinIO 对象存储"]
    API --> REDIS["Redis"]
    API --> KAFKA["Kafka"]
```

### 3.1 后端实现

| 模块 | 实现内容 | 主要落点 |
|---|---|---|
| 能力状态 | 能力清单、状态、阻塞类型、阻塞原因和运行计数 | `capability_completion_status`、`/api/v1/capabilities/completion` |
| 计划与对象 | 对象台账、计划创建、启用、按对象生成任务 | `inspection_objects`、`inspection_plans` |
| 航线中心 | 航线、版本、航点、参数、载荷动作、校验和发布 | `routes`、`route_versions`、`route_waypoints` |
| 无人机接入 | 连接、设备、机巢、载荷、任务、命令、厂商事件 | `uav_vendor_connections`、`flight_missions`、`uav_commands` |
| 飞行状态 | 下发、开始、暂停、恢复、返航、取消、完成和幂等控制 | `MissionStateMachine` |
| 遥测与航迹 | 时序遥测点、设备位置、任务进度和实际轨迹 | `telemetry_points`、`flight_tracks` |
| 数据接入 | 分片会话、分片清单、SHA-256、合并和 MinIO 存储 | `upload_sessions`、`upload_parts` |
| 预处理 | 校验和、MIME 校验、元数据规范化和质量结论 | `preprocess_jobs`、`preprocess_step_runs` |
| 通知中心 | 站内通知、发送状态、阅读时间和告警关联 | `notification_deliveries` |
| 责任体系 | 组织、用户、角色、责任规则和值班表 | `organizations`、`platform_users`、`responsibility_rules` |
| 工单闭环 | 接单、出发、到场、处置、提交、复核、关闭、退回和重开 | `WorkOrderStateMachine`、`workorder_actions` |
| 现场证据 | 图片、视频、音频、PDF，阶段标签、哈希和空间位置 | `workorder_attachments` |
| 复检归档 | 复检任务、复检方式、归档清单、校验和与保留期限 | `reinspection_requests`、`archive_packages` |

### 3.2 前端实现

| 页面 | 已实现内容 |
|---|---|
| 计划中心 | 计划参数、对象选择、场景选择、启用和生成任务 |
| 航线中心 | 航点和参数编辑、校验结果、版本发布及状态展示 |
| 无人机作业 | 厂商连接、四层连接检查、设备同步、任务下发、命令和遥测进度 |
| 数据资源 | 文件上传、上传会话、资源质量和预处理步骤 |
| GIS | 巡检对象、发布航线、实际航迹、无人机和告警图层，支持图层开关和业务筛选 |
| 告警中心 | 告警处置、证据入口、站内通知和阅读回执 |
| 工单中心 | 状态动作、现场证据上传与预览、操作时间线、复检和复核 |
| 归档中心 | 归档包、归档编号、业务对象、校验和、状态和保留时间 |

## 4. P0 能力实施对照

| 编号 | 能力 | 当前状态 | 已完成内容 | 未完成原因或边界 |
|---|---|---|---|---|
| P0-01 | 巡检类型、周期计划和对象台账 | 已实现 | 对象台账、计划类型、周期规则、启用、按对象生成任务 | 无 |
| P0-02 | 智能航线规划与航点编辑 | 部分实现 | 航点编辑、三维坐标、载荷动作、飞行参数、校验、版本和发布 | 桥梁环绕、隧道内飞、防洪走廊等自动生成算法需要真实构筑物尺寸、净空、障碍物、地形及设备能力参数 |
| P0-03 | 载荷与飞行参数配置 | 已实现 | 航线级速度、高度、返航策略、云台角度和载荷动作 | 厂商设备的最终参数上限需在真实适配器中二次校验 |
| P0-04 | 真实无人机厂商任务下发 | 部分实现 | 已新增司空 2 私有化 OpenAPI 接入服务、拓扑同步、WPML/KMZ 航线导入、飞前检查、高级任务、控制命令、异步状态和对账；飞行控制默认关闭 | 需在私有化实例确认 Token、项目、设备枚举、任务参数并完成真机安全验收；纵横适配仍待正式材料 |
| P0-05 | 实时遥测与实际航迹 | 部分实现 | 已新增 EventAPI、MQTT Bridge、事件去重、Kafka Outbox/Inbox、设备/任务/遥测/实际航迹投影 | 真实 MQTT 主题、EventAPI 鉴权、字段、频率、时钟和质量规则需部署及设备联调后冻结 |
| P0-06 | 巡检文件上传与弱网续传 | 部分实现 | 服务端分片会话、断点数据结构、分片校验、合并、哈希和对象存储已实现 | 机巢或现场边缘代理、弱网重试策略和真实大视频压力参数依赖目标硬件与网络测试 |
| P0-07 | 生产模型制品就绪 | 外部受阻 | 模型配置、安装卸载、运行时路由、健康检查和本地 CPU 调试链路已实现 | 缺少四类已训练验收的 ONNX 制品、类别映射、预后处理清单、校验和及使用许可；Open3D 几何分析已可运行 |
| P0-08 | 核心缺陷类别模型与验收集 | 外部受阻 | 样本管理、预览、上传测试、测试记录和模型选择已实现 | 缺少铁路专业标注样本、独立验收集、缺陷等级口径和误漏报验收阈值 |
| P0-09 | 告警策略与通知中心 | 部分实现 | 责任匹配、站内通知、阅读回执、告警与工单关联已实现 | 短信、企业微信或既有消息平台缺少账号、模板、签名、回调和网络白名单 |
| P0-10 | 组织、部门、工段和责任规则 | 已实现 | 组织树、用户、角色、线路/专业/级别规则和值班数据模型已实现 | 生产组织数据需由业务单位确认后批量导入 |
| P0-11 | 现场处置与证据上传 | 已实现 | 接单至复核的有序状态机、证据上传、预览、下载、哈希和审计时间线已实现 | 无 |
| P0-12 | 复飞复检与闭环销项 | 部分实现 | 闭环后创建复检任务、指定航线和复检方式已实现 | 真实复飞依赖 P0-04；自动前后对比依赖验收模型和同位置基线数据 |
| P0-13 | 正式归档与成果输出 | 部分实现 | 归档编号、业务清单、操作记录、证据清单、哈希和保留期限已实现 | 正式 PDF 版式、电子签章和单位归档目录规则尚未提供 |
| P0-14 | 用户、组织与 RBAC | 部分实现 | 用户、组织、角色和用户角色模型已实现 | 统一身份平台地址、OIDC/SAML 协议、客户端参数、Claims 映射及退出策略未提供，接口强制鉴权暂不能按生产方式启用 |

## 5. P1 能力实施对照

| 编号 | 能力 | 当前状态 | 说明 |
|---|---|---|---|
| P1-01 | 任务审批、模板、复制和批量创建 | 部分实现 | 已有计划生成、路线模板基础和任务审批字段；多级审批、复制和批量导入待补 |
| P1-02 | 天气、空域、天窗和资源冲突检查 | 未实施 | 缺少天气服务、空域系统、铁路天窗系统和资源日历接口 |
| P1-03 | 视频流、关键帧、跟踪和告警片段 | 未实施 | 缺少厂商直播地址、转码协议、真实视频样本和目标并发指标 |
| P1-04 | 多模态统一时间轴 | 部分实现 | 资源、遥测、任务和采集时间已统一登记；跨设备时钟校准规则待真实设备验证 |
| P1-05 | 真实预处理与质量异常闭环 | 部分实现 | 基础完整性、MIME 和元数据规范化已实现；相机标定、点云去噪配准、影像质量算法和异常返工待样本及标定参数 |
| P1-06 | 可见光、红外、图像和点云融合 | 未实施 | 依赖成对采集样本、外参标定、时空同步和融合验收集 |
| P1-07 | PostGIS 空间规则与设施图层 | 部分实现 | 空间对象、航线、设备、轨迹和告警图层已实现；缓冲区、净空、距离和地理围栏规则需现场阈值 |
| P1-08 | 告警去重、聚合、升级和催办 | 部分实现 | 已有告警策略、通知和责任匹配；跨帧去重、事件聚合、升级定时器和催办策略待业务规则 |
| P1-09 | 工单受理、拒收、转派、协办和会签 | 部分实现 | 有序受理与处置闭环已实现；拒收、多人协办和联合会签待权限与组织流程确认 |
| P1-10 | SLA、超时、暂停和恢复计时 | 未实施 | 数据模型已有策略入口，缺少业务日历、各专业 SLA 和暂停计时规则 |
| P1-11 | 验收标准、签名和退回原因 | 部分实现 | 复核、退回、重开和意见留痕已具备；正式签名、签章与结构化验收标准待提供 |
| P1-12 | 隐患台账、复发分析和专业统计 | 部分实现 | 隐患、工单和归档数据可追溯；复发口径、统计指标和数据仓库模型待业务确认 |
| P1-13 | 数据分级、脱敏、水印和下载审计 | 部分实现 | 证据哈希、对象键和业务审计已实现；分级目录、水印模板、脱敏规则和下载审批待安全制度 |
| P1-14 | 接口签名、幂等、重试、死信和补偿 | 部分实现 | 任务命令幂等、厂商事件 Inbox 和 Kafka 已具备；Outbox、死信处理台、补偿规则和外部签名需结合真实接口实施 |

## 6. P2 能力延期说明

| 编号 | 能力 | 当前状态 | 启动条件 |
|---|---|---|---|
| P2-01 | 多无人机、多机巢智能调度 | 延期 | 至少一家厂商的单机、机巢任务和故障恢复稳定运行，并取得设备容量约束 |
| P2-02 | 大屏态势与领导驾驶舱 | 延期 | 核心指标口径、真实线路数据和统计周期稳定后建设 |
| P2-03 | 移动 App、微信和企业微信协同 | 延期 | 统一身份、消息渠道、移动设备管理和安全要求明确 |
| P2-04 | 三维走廊、点云与 BIM/GIS 融合 | 延期 | 点云基线、设施 BIM、坐标基准和模型精度达标 |
| P2-05 | 风险驱动的动态巡检频次 | 延期 | 隐患台账积累完整业务周期并形成风险标签和调整规则 |
| P2-06 | 自动训练、评测和持续交付 | 延期 | 样本治理、GPU 算力、评测门禁、审批制度和模型回退机制具备 |
| P2-07 | 跨线路指标对标和趋势预测 | 延期 | 多线路数据口径、组织维度、里程编码和历史周期统一 |
| P2-08 | 灾备、跨节点切换和容量弹性 | 延期 | 明确生产规模、部署地域、RTO、RPO、等保等级和预算 |

## 7. 外部系统接入所需材料

### 7.1 大疆

1. 具体无人机、遥控器、机巢、相机和载荷型号。
2. 固件版本、DJI Pilot 2 或 Dock 使用方式及 Cloud API 支持矩阵。
3. AppKey、AppSecret、License、工作空间、测试租户和设备绑定信息。
4. MQTT、HTTP、WebSocket、直播和媒体回传的正式接口资料。
5. 回调地址、出入站网络白名单、证书、限流和错误码说明。
6. WPML 版本、航线参数约束、返航和失联策略。
7. 可用于联调的设备、飞行场地、操作人员和安全审批。

### 7.2 纵横

1. 产品、载荷和昆仑机库型号，固件及纵横云版本。
2. 采用公有云、私有化纵横云或本地 SDK 的最终接入方式。
3. 正式 SDK/API 包、授权文件、头文件或 OpenAPI、报文样例和错误码。
4. 任务、航线、设备、遥测、直播、媒体和机库控制协议。
5. 操作系统、CPU 架构、驱动、运行时、线程和重连要求。
6. 测试环境、测试账号、测试设备、回调网络和厂商技术联系人。

### 7.3 高德地图

1. 商用授权范围、账号、Web Key、JavaScript Key 和安全密钥。
2. 允许访问域名、服务端出口 IP、调用配额和并发限制。
3. 在线与离线使用边界、缓存许可和故障降级要求。
4. WGS84、GCJ-02 与地方工程坐标的转换责任和精度要求。
5. 铁路专有线路、设施、里程和禁飞区的权威数据源。

当前系统不依赖高德完成业务空间计算。PostGIS 保存 WGS84 权威业务几何，MapLibre 负责本地显示；取得高德材料后，只需新增地图提供商和后端 Web 服务代理，不改变任务、告警和工单领域模型。

### 7.4 其他外部材料

| 类别 | 所需材料 |
|---|---|
| 统一身份 | IdP 地址、OIDC/SAML 方式、客户端、证书、Claims、组织映射和退出策略 |
| 消息渠道 | 短信或企业微信账号、模板、签名、回调、白名单、重试和费用策略 |
| 天气与空域 | 服务地址、授权、字段字典、预报时效、空域审批和铁路天窗接口 |
| 生产模型 | ONNX 制品、清单、SHA-256、类别映射、输入尺寸、预后处理、阈值、许可证和回退版本 |
| 样本数据 | 专业标注规范、训练集、验证集、独立验收集、隐私要求和指标口径 |
| 正式报告 | 单位模板、编号规则、签章服务、归档目录、保留年限和审批人规则 |
| 现场边缘 | 机巢/边缘计算机规格、操作系统、网络带宽、断网时长、存储容量和视频规模 |

## 8. 自动验证

### 8.1 全链路能力回归

执行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\capability_completion_test.ps1
```

最近一次验证结果：

| 检查项 | 结果 |
|---|---|
| 能力登记 | 14 项 P0 能力可查询 |
| 航线 | 创建、校验并发布成功 |
| 计划任务 | 启用并生成任务成功 |
| 飞行任务 | 下发成功，最终 `COMPLETED`、进度 100% |
| 遥测 | 5 条时序遥测记录 |
| 数据接入 | 分片上传、合并和 SHA-256 成功 |
| 预处理 | 3 个步骤完成，质量结论 `PASSED` |
| 工单 | 7 个有序状态动作和证据上传完成，最终关闭 |
| 复检 | 自动创建复检任务 |
| 归档 | 生成 `READY` 归档包和校验和 |
| GIS | 对象、路线、轨迹、设备和告警要素可查询 |
| 通知 | 站内通知和阅读回执成功 |

### 8.2 页面与接口回归

执行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\navigation_pages_test.ps1
```

当前覆盖 14 个前端路由和 22 个数据接口，包括计划、对象、航线、厂商连接、设备、飞行任务、预处理、GIS、通知和归档。桌面视口与 390 像素宽移动视口均已检查，无页面横向溢出；GIS 容器和业务图层能够正常显示。

### 8.3 构建与单元测试

| 项目 | 结果 |
|---|---|
| 后端 Maven 测试 | 14 项通过，0 失败 |
| 前端生产构建 | 通过 |
| 后端 Docker 镜像构建 | 通过 |
| 前端 Docker 镜像构建 | 通过 |
| Docker 健康检查 | PostgreSQL、Redis、Kafka、MinIO、后端、前端及算法服务正常 |

## 9. 部署与调试

### 9.1 本地或单机容器部署

```powershell
docker compose -f infra\docker-compose.yml build
docker compose -f infra\docker-compose.yml up -d
```

访问地址：

- 业务前端：`http://localhost:8088`
- 后端健康检查：`http://localhost:8080/actuator/health`
- MinIO 控制台：http://localhost:9001`
`
容器基础镜像已使用国内可访问镜像地址，Python 依赖安装可通过项目 Dockerfile 中的阿里云 PyPI 镜像配置完成。生产环境应将数据库、对象存储和密钥改为受管资源或独立持久化服务，并通过环境变量或密钥管理服务注入凭据。

### 9.2 外部能力切换原则

1. 本地调试始终保留 `SIMULATOR` 连接，不需要厂商账号即可验证平台逻辑。
2. 生产连接按厂商和环境独立配置，可单独启停，不影响本地模拟连接。
3. 厂商密钥只保存引用，不在前端、数据库明文字段或代码仓库中保存密钥原文。
4. 地图业务数据保持 WGS84，在线高德仅作为可替换显示与地址服务。
5. 模型以模型组、版本、运行时和路由配置切换，本地 CPU 与服务器 GPU 使用同一管理入口。

## 10. 后续实施顺序

1. 收齐大疆材料后实现 `DjiCloudAdapter`，先完成连接、设备和任务，再接遥测、媒体和直播。
2. 收齐纵横接口包后按部署方式实现 `JouavCloudAdapter` 或 `JouavSdkAdapter`，使用同一适配器契约执行契约测试。
3. 取得高德 Key 和授权后增加在线地图提供商、坐标显示转换和后端代理，继续保留 MapLibre 降级路径。
4. 导入正式组织、线路、设施、责任区和值班数据，启用统一身份和接口权限控制。
5. 导入生产模型和独立验收集，完成阈值标定、性能压测和误漏报验收。
6. 接入消息、天气、空域、天窗和正式报告系统，补齐 P1 业务能力。
7. 在真实设备、真实线路和目标网络中进行稳定性、容量、安全及故障恢复验证后再切换生产流量。
