# 铁路无人机智能巡检系统实现说明

## 1. 当前实现范围

本仓库已按《铁路无人机智能巡检系统设计说明书》定义的架构重新实现，主实现不再采用单体 Python 原型，而是采用以下工程结构：

- `platform/backend`：Spring Boot 业务平台。
- `ai-services/vision-inference`：FastAPI 视觉/红外/变化检测服务。
- `ai-services/pointcloud-analysis`：FastAPI 点云/TIF/DEM 形变分析服务。
- `frontend`：Vue3 + TypeScript 前端。
- `infra`：PostGIS、Redis、Kafka、MinIO、Prometheus、各服务 Docker Compose 编排。
- `docs/IMPLEMENTATION_COMPLIANCE.md`：设计说明书到实现的映射关系。
- `docs/full-chain-visualization-design.md`：全链路可视化设计方案。
- `docs/full-chain-node-visualization-analysis-design.md`：全链路节点交互与数据展示设计。

当前 AI 服务保留确定性推理适配器，接口、模型组、返回结构均按真实模型接入方式设计。全链路运行已实现 12 个节点工作台、节点快照、SSE 实时事件、失败重试、实体索引和结果导出。后续接入 YOLO、Mask R-CNN、SAM、ONNX Runtime、TensorRT、Open3D/PCL、GDAL 等模型或算法时，替换对应 FastAPI 服务内的推理适配逻辑即可。

模型管理工作台已完成模型台账、版本与制品、JSON Schema 参数方案、固定回归集、临时样本上传、断点续传、异步测试、多模态结果查看、横向评估、报告导出、反馈回流和发布治理。入口为 `/algorithm-assets/models`。

## 2. 目录结构

```text
platform/backend/                 Spring Boot 业务平台
ai-services/vision-inference/      FastAPI 视觉/红外/变化检测服务
ai-services/pointcloud-analysis/   FastAPI 点云/TIF 分析服务
frontend/                          Vue3 + TypeScript 前端
infra/                             Docker Compose 与 Prometheus 配置
scripts/                           启停与冒烟测试脚本
docs/                              实现映射与说明
```

## 3. 本地启动完整技术栈

```powershell
.\scripts\start_stack.ps1
```

Docker 镜像默认走已验证可用的华为云 SWR Docker Hub 代理 `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io`，Python 依赖走阿里 PyPI，Maven 依赖配置华为云、腾讯云、阿里云和 Maven Central 多源兜底，前端依赖走 npmmirror。

访问：

```text
http://localhost:8088
```

个人 CPU 电脑使用专用配置启动：

```powershell
.\scripts\start_cpu_stack.cmd
```

CPU 模式启用 ONNX Runtime CPU、Open3D CPU、单并发、批量 1、模型懒加载和 500,000 点上限。五类模型的制品目录、安装方式、真实推理与基线结果区分见 `docs/local-cpu-model-runtime.md`。

## 4. 核心接口

```text
POST /api/v1/inspection/tasks
POST /api/v1/uav/callbacks/mission-status
POST /api/v1/inspection/resources/complete
POST /api/v1/analysis/jobs
POST /api/v1/analysis/jobs/{job_id}/run
GET  /api/v1/alarms
POST /api/v1/workorders/callbacks/status
POST /api/v1/exemptions
GET  /api/v1/models
GET  /api/v1/stats/overview
POST /api/v1/demo/run-full-chain
POST /api/v1/demo/runs
GET  /api/v1/demo/runs/{run_id}
GET  /api/v1/demo/runs/{run_id}/events
GET  /api/v1/demo/runs/{run_id}/events/history
POST /api/v1/demo/runs/{run_id}/cancel
GET  /api/v1/demo/runs/{run_id}/steps/{step_key}
POST /api/v1/demo/runs/{run_id}/steps/{step_key}/retry
GET  /api/v1/demo/runs/{run_id}/entities
GET  /api/v1/demo/runs/{run_id}/export
GET  /api/v1/inspection/resources/{resource_id}/preview
GET  /api/v1/analysis/results/{result_id}/evidence
GET  /api/v1/alarms/{alarm_id}/evidence-chain
POST /api/v1/workorders/{workorder_id}/redispatch
POST /api/v1/workorders/{workorder_id}/review
POST /api/v1/samples/{sample_id}/decision
GET  /api/v1/models/{model_group_id}/versions
GET  /api/v1/models/{model_group_id}/parameter-profiles
POST /api/v1/parameter-profiles/validate
GET  /api/v1/models/{model_group_id}/sample-sets
POST /api/v1/sample-sets/preview
POST /api/v1/test-uploads
POST /api/v1/test-uploads/{session_id}/files
POST /api/v1/test-uploads/{session_id}/chunked-files
PUT  /api/v1/test-uploads/{session_id}/chunked-files/{manifest_id}/parts/{part_index}
POST /api/v1/test-uploads/{session_id}/chunked-files/{manifest_id}/complete
POST /api/v1/model-tests
POST /api/v1/model-tests/{task_id}/validate
POST /api/v1/model-tests/{task_id}/start
GET  /api/v1/model-tests/{task_id}/events
GET  /api/v1/model-tests/{task_id}/results
GET  /api/v1/model-tests/{task_id}/summary
GET  /api/v1/model-tests/{task_id}/report
POST /api/v1/model-test-results/{result_id}/feedback
POST /api/v1/model-releases
POST /api/v1/model-releases/{release_id}/approve
POST /api/v1/model-releases/{release_id}/gray
POST /api/v1/model-releases/{release_id}/promote
POST /api/v1/model-releases/{release_id}/rollback
```

## 5. 验证

```powershell
.\scripts\smoke_test.ps1
```

冒烟脚本默认通过前端 Nginx 反向代理访问 API，即 `http://localhost:8088`。脚本会启动新的全链路运行实例，轮询运行快照直到完成，并校验 12 个节点快照、22 条有序事件、实体数量、工单接口与前端入口。如需直连后端，可设置 `RAIL_API_BASE_URL=http://localhost:8080`。

完整交互回归：

```powershell
.\scripts\full_chain_interaction_test.ps1
```

该脚本覆盖资源预览、算法证据、告警证据链、工单改派与复核、样本处置、结果导出、运行取消及从失败节点重试。

离线静态校验：

```powershell
.\scripts\run_static_checks.ps1
```

## 6. 单服务开发命令

```powershell
# 后端
docker run --rm -v "$PWD\platform\backend:/workspace" -w /workspace swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/maven:3-eclipse-temurin-17 mvn -s maven-settings.xml -B -Ptests test

# 前端
cd frontend
npm install --registry=https://registry.npmmirror.com
npm run build

# 视觉推理服务
cd ai-services/vision-inference
python -m pytest

# 点云分析服务
cd ai-services/pointcloud-analysis
python -m pytest
```

## 7. 部署说明

当前部署使用 Docker Compose 拉起完整技术栈。生产环境建议将 Compose 配置迁移到 Kubernetes/K3s，并按设计说明书继续扩展：

- Spring Boot 服务横向扩展。
- FastAPI 推理服务按模型组独立扩展。
- PostgreSQL/PostGIS、Kafka、Redis、MinIO 使用生产级高可用部署。
- Prometheus/Grafana 接入告警策略。
- AI 模型改为 ONNX Runtime/TensorRT/Triton 推理。
- 点云分析接入 Open3D/PCL/GDAL 生产处理链。

已在本机生成前端 `dist` 时，可跳过容器内 npm 安装并使用预构建覆盖配置：

```powershell
docker compose -f infra/docker-compose.yml -f infra/docker-compose.prebuilt.yml build frontend
docker compose -f infra/docker-compose.yml -f infra/docker-compose.prebuilt.yml up -d
```

后端镜像构建会执行 JUnit 测试；两个 Python 服务使用多阶段镜像构建，测试阶段执行 `pytest`，生产层不保留测试依赖。

## 8. 验证路径

1. 启动完整技术栈。
2. 打开 Web 前端。
3. 点击“启动全链路”。
4. 查看 12 个节点工作台中的任务参数、航线下发、多源接入、预处理流水线、推理过程、规则判定、告警、工单闭环、样本回流和完成汇总。
5. 查看任务、AI 结果、告警、工单、模型版本。
6. 执行 `scripts/smoke_test.ps1` 与 `scripts/full_chain_interaction_test.ps1` 验证 API 和节点交互。

## 9. 多页面导航实现

前端已按业务域拆分为固定左侧导航和独立路由页面：

| 页面 | 路由 | 主要能力 |
| --- | --- | --- |
| 工作总览 | `/overview` | 核心指标、重点待办、健康状态和快捷入口 |
| GIS 态势 | `/gis` | 线路、规则区域、航线、告警点位和实体联动 |
| 全链路运行 | `/runs` | 12 节点工作台、运行记录、异常恢复和历史回放 |
| 巡检任务 | `/tasks` | 任务创建、航线下发、取消和任务详情 |
| 数据资源 | `/resources` | 资源库、接入监控、预处理、质量和预览 |
| 智能分析 | `/analysis` | 分析任务、AI 结果、规则判定和失败恢复 |
| 告警中心 | `/alarms` | 证据链、确认、抑制、恢复和工单关联 |
| 工单中心 | `/workorders` | 表格、泳道、地图、改派、复核和退回 |
| 样本与模型 | `/algorithm-assets` | 样本决策、标注队列、数据集和模型版本 |
| 系统运维 | `/operations` | 服务健康、接口集成、平台事件和系统配置 |

前端页面使用路由级懒加载。告警、工单、分析结果和样本等高数据量列表使用分页，详情通过抽屉或独立实体路由加载。桌面端使用固定左侧导航，窄屏改为导航抽屉。

页面和接口验收：

```powershell
.\scripts\navigation_pages_test.ps1
```

该脚本检查 10 个页面路由、11 组页面数据接口、任务创建与航线状态、任务取消及告警确认操作。

## 10. 模型管理工作台

| 页面 | 路由参数 | 能力 |
| --- | --- | --- |
| 模型列表 | `/algorithm-assets/models` | 模型类型、输入模态、生产/候选版本、服务状态和测试统计 |
| 能力概览 | `?panel=overview` | 生产基线、适用场景、版本关系和近期活动 |
| 版本与制品 | `?panel=versions` | 制品哈希、运行约束、契约和校验报告 |
| 运行配置 | `?panel=runtime` | 本地/服务器端点、版本绑定、资源参数、健康检查和原子切换 |
| 参数方案 | `?panel=parameters` | 动态表单、跨字段校验、不可变修订、比较与启停 |
| 测试工作台 | `?panel=test` | 快速测试、批量回归、版本对比、参数对比、样本库与本地上传 |
| 评估记录 | `?panel=evaluations` | 指标比较、结果明细、运行事件和 Markdown 报告 |
| 发布记录 | `?panel=releases` | 申请、审批、灰度、生产切换、回滚和审计 |

大于 `8 MB` 的本地样本自动使用幂等分片上传，每片最多重试 3 次；服务端按清单验证分片数量与总大小，合并后计算 SHA-256，再写入 MinIO。上传会话默认保留 7 天，未被测试任务引用的过期对象由定时任务清理。

测试编排使用独立异步执行器和 SSE 事件流，固化模型制品、参数修订、输入校验和与运行环境。视觉检测、分割、红外、变化检测和点云结果使用专用查看器；三维点云基于 Three.js，可切换距离、高程和强度着色。

运行配置将模型版本绑定到实际推理端点，并管理运行引擎、执行提供程序、设备、精度、副本、并发、超时和降级策略。切换前会校验端点健康、运行档案、注册版本和制品状态，切换与回退写入审计记录。服务器部署提供 CUDA/ONNX Runtime GPU 镜像、版本化模型注册表和独立 Compose 覆盖配置，详见 `docs/model-runtime-configuration-and-deployment.md`。

## 11. 本次验证记录

- Spring Boot：6 个 JUnit 测试全部通过。
- 视觉推理服务：4 个 FastAPI 契约与运行时测试全部通过。
- 点云分析服务：4 个 FastAPI 契约与运行时测试全部通过。
- Vue3：`vue-tsc --noEmit` 与 Vite 生产构建通过。
- 分片上传：`8 MB + 1 MB` 两分片合并成功，下载对象为 `9,437,184` 字节，SHA-256 已生成。
- 测试任务：浏览器选样后完成 8 个可视化执行步骤，结果、汇总指标和验收结论可查询。
- 点云画布：WebGL 画布为 `916 × 537`，截图抽样区域包含 2000 余种颜色，确认场景正常渲染。
- 响应式：`390 × 844` 下模型列表与结果查看器无页面级横向溢出。
- 运行配置：完成创建、健康检查、动态切换、切回和删除验收；本地环境能够阻止误切 `server-gpu` 档案。
- 部署：PostGIS、Redis、Kafka、MinIO、后端、前端和两个 AI 服务均处于运行或健康状态。
