项目状态：开发中，尚未上线，当前没有对外发布的项目版本号。本仓库包含可运行的软件实现、模拟适配器和 REFERENCE/BASELINE AI 运行档案；它们用于本地验证平台契约和业务状态机，不代表真实无人机、甲方外部系统或生产模型已经完成现场验收。

版本说明：文档中的“V2.1”是需求、设计和测试文档版本/基线，不是当前项目的软件版本号，也不表示项目已经完成发布或生产部署。

项目范围

平台采用模块化单体为核心，按独立资源或故障域拆分设备接入、媒体、AI 推理和边缘代理能力。平台是全局业务事实源；AI 服务只返回结构化结果，不直接创建告警、工单或修改业务事实。

当前代码库主要包含：

目录	说明
`frontend/`	Vue 3、TypeScript、Vite 前端
`platform/backend/`	Java 17、Spring Boot 业务后端、状态机、审计与 API
`uav-access-service/`	无人机厂商协议和设备接入隔离层
`ai-services/`	视觉、点云分析和模型制品安装服务
`edge-agent/`	现场缓存、断点续传和边缘回传
`infra/`	本地 Compose、基础设施和模型注册配置
`deploy/`	Helm、Ansible、离线部署及发布校验
`docs/`	需求、设计、实施和验收资料

厂商参考快照目录 Cloud-API-Demo-Web-1.10.0/ 和 DJI-Cloud-API-Demo-1.10.0/ 仅作为参考资料，不属于平台核心实现。

主要能力

任务计划、审批、预飞检查、资源锁和任务状态管理
无人机、机巢、载荷、电池、航线版本和设备能力管理
边缘队列、分片上传、断点续传、SHA-256 校验和媒体登记
视觉、红外、变化检测、点云/TIF 分析及模型版本治理
告警聚合、确认、误报、证据链、通知和升级
工单派发、改派、处置、审核、复检、归档和审计
PWA 移动作业、离线证据队列、冲突保留和幂等提交
视频会话、WebRTC/HLS、数据治理、报表和运维就绪度

系统架构

Web/PWA
   │
   ▼
Nginx ── Spring Boot 平台后端 ── PostgreSQL/PostGIS
              │                 ├─ Redis
              │                 ├─ Kafka
              │                 └─ MinIO
              ├─ UAV Access Service ── FlightHub/设备适配器
              ├─ Vision Inference / Pointcloud Analysis
              ├─ Artifact Installer
              ├─ Edge Agent
              └─ Media Gateway (WebRTC/HLS)

核心业务 API 使用 /api/v1 前缀，统一响应包络为 { code, message, requestId, data }。跨服务请求、回调、上传和异步任务应保留关联 ID、幂等语义、超时、重试及审计信息。

快速开始

前置条件

Windows 10/11
Docker Desktop，且 Compose V2 可用
Git
如需单独开发前端：Node.js 与 npm
如需运行单服务测试：Java 17、Maven 或 Python 运行环境

启动本地完整栈

在仓库根目录执行：

.\scripts\windows\start_stack.cmd

启动后访问 http://localhost:8088。CPU-only 设备可使用：

.\scripts\windows\start_cpu_stack.cmd

本地登录配置和密钥由启动脚本及环境模板管理；请勿把 .env、真实账号、Token、证书或设备凭据提交到仓库。生产环境必须替换本地开发配置，使用正式身份源和密钥注入机制。

单独构建前端

cd frontend
npm ci
npm run build

查看 API 文档

启动后可通过后端提供的 OpenAPI/Swagger 入口查看当前接口契约；业务接口以代码和运行中的 API 为准，完整接口清单及示例见 IMPLEMENTATION.md。

验证

按变更范围运行最小充分验证：

# 基础冒烟与前端入口
.\scripts\windows\smoke_test.ps1

# 页面导航与交互链路
.\scripts\windows\navigation_pages_test.ps1
.\scripts\windows\full_chain_interaction_test.ps1

# 静态检查
.\scripts\windows\run_static_checks.ps1

单服务验证命令、已执行测试结果和测试边界见 docs/铁路无人机智能巡检系统V2.1开发完成与测试报告_V1.0.md。会创建或修改业务数据的端到端脚本只应在隔离测试环境执行。

生产部署

项目尚未上线，以下内容是面向后续生产交付的部署路径，不代表当前已经完成生产部署。研发和本地验证使用 Docker Compose；正式交付使用 deploy/ 中的 Helm、Ansible 和离线发布工具。部署前需填写站点配置并完成密钥、镜像、集群和依赖检查：

bash deploy/scripts/deploy.sh deploy/config/site.example.yaml
bash deploy/scripts/verify.sh deploy/config/site.example.yaml

正式环境至少应完成 OIDC/TLS、镜像摘要或签名、Secret 注入、健康检查、网络策略、备份恢复、RPO/RTO、容量和故障演练。不得把本地默认口令、开发路径、明文凭据或 latest 镜像带入生产。

安全与保密

这是闭源项目。源代码、架构细节、接口契约、部署配置、模型制品和测试数据均属于受限资产，未经授权不得复制、公开发布、反向工程、再分发或用于其他项目。

不提交或输出 .env*、密钥、证书、Token、真实客户数据、生产地址和精确敏感点位。
身份和操作者来自认证上下文，不信任请求体中的 operator、userId 或角色字段。
飞控、机场控制、模型发布、告警确认、工单销项和数据导出必须经过权限、状态、幂等键、操作者、原因及审计门禁。
生产模型缺失、未验收或仅为 REFERENCE/BASELINE 时，不得静默生成可进入生产告警链的结论。
发现安全问题请通过项目约定的内部安全渠道报告，不要公开发布漏洞细节或复现数据。

生产验收边界

上线前仍需由实施方或甲方提供并验收：

真实无人机、机巢、载荷、固件、FlightHub/设备账号及异常工况。
权威铁路线路、坐标系、控制点、禁限飞、天气、空域和天窗数据源。
生产模型、类别映射、验收集、精度/召回率阈值及误报漏报口径。
OIDC/组织目录、TLS 证书、消息渠道、视频流源和正式对象存储。
正式 Kubernetes/离线集群的安全、容量、高可用、灾备和合规验收。

自动化测试证明的是代码、接口和状态机在测试环境中的行为；不能替代上述外部条件下的生产验收。

文档

IMPLEMENTATION.md：实现范围、接口、启动和验证说明
docs/铁路无人机智能巡检系统V2.1详细系统设计说明书_V1.0.md：系统设计基线
docs/铁路无人机智能巡检系统V2.1开发完成与测试报告_V1.0.md：完成范围、测试证据和外部验收清单
deploy/README.md：正式部署与运维说明

如文档声明与当前代码、数据库迁移或自动化测试不一致，以代码和可复核测试证据为准。

许可证与第三方软件

本项目为闭源专有软件。除非另有书面授权，项目不授予任何复制、修改、分发、反向工程或商业使用许可。

项目依赖 Vue、Spring Boot、PostgreSQL/PostGIS、Redis、Kafka、MinIO、MediaMTX 及其他第三方软件。第三方组件继续受其各自许可证约束；正式发布前应依据锁定版本清单完成第三方许可证、SBOM、镜像签名和漏洞扫描核验。