# 系统设计说明书实现映射

## 1. 架构落实情况

| 设计说明书要求 | 当前实现位置 |
| --- | --- |
| Java Spring Boot 业务平台 | `platform/backend` |
| Python FastAPI AI 推理服务 | `ai-services/vision-inference` |
| Python FastAPI 点云/TIF 分析服务 | `ai-services/pointcloud-analysis` |
| PostgreSQL + PostGIS | `infra/docker-compose.yml`、`platform/backend/src/main/resources/db/migration` |
| Redis | `infra/docker-compose.yml` |
| Kafka | `infra/docker-compose.yml`、后端 `KafkaTemplate` 事件发布 |
| MinIO/S3 | `infra/docker-compose.yml`、后端 MinIO 配置 |
| Vue3 + TypeScript 前端 | `frontend` |
| Nginx 前端反向代理 | `frontend/nginx.conf` |
| Prometheus 监控 | `infra/prometheus.yml` |
| Docker 化部署 | `infra/docker-compose.yml`、各服务 `Dockerfile` |

## 2. 模块落实情况

| 设计模块 | 当前实现 |
| --- | --- |
| 巡检任务管理 | `PlatformController.createTask`、`PlatformService.createTask` |
| 无人机数据接入 | `/api/v1/inspection/resources/complete` |
| 数据预处理 | AI 服务的资源标准化入口，后续可替换为 OpenCV/GDAL/PCL 处理链 |
| AI 算法引擎 | `vision-inference`、`pointcloud-analysis` |
| GIS 空间规则 | Flyway PostGIS schema + `RuleEngine` 业务规则，空间计算可继续扩展到 `ST_DWithin/ST_Contains` |
| 业务规则引擎 | `platform/backend/.../RuleEngine.java` |
| 告警中心 | `PlatformService.insertAlarmAndMaybeWorkOrder`、`/api/v1/alarms` |
| 工单闭环 | `/api/v1/workorders/callbacks/status` |
| 基线库与豁免区 | `baseline_objects`、`exemption_areas` 表结构和豁免接口 |
| 数据标注与模型迭代 | `sample_feedback_records`、`model_versions`、样本处置接口与样本回流节点 |
| 全链路可视化 | `demo_runs`、`demo_run_events`、节点快照、SSE 事件流、12 个前端节点工作台 |
| 系统运维 | Actuator、Prometheus、Docker Compose |
| 模型可视化管理 | `ModelManagementController`、`ModelManagementService`、`ModelManagementWorkspace.vue` |
| 动态参数方案 | JSON Schema/UI Schema、`ModelParameterValidator`、`ModelParameterPanel.vue` |
| 模型测试编排 | `ModelTestRunner`、独立线程池、SSE 事件、测试快照与验收规则 |
| 大文件测试输入 | MinIO 临时桶、8 MB 分片、幂等续传、SHA-256、到期清理 |
| 多模态结果查看 | 图片目标叠加、分割、红外、变化区域与 Three.js 点云查看器 |
| 模型发布治理 | 发布申请、审批、灰度、生产切换、成对回滚和审计记录 |

## 3. 接口落实情况

| 接口 | 当前实现 |
| --- | --- |
| 创建巡检任务 | `POST /api/v1/inspection/tasks` |
| 无人机任务状态回调 | `POST /api/v1/uav/callbacks/mission-status` |
| 巡检数据上传完成 | `POST /api/v1/inspection/resources/complete` |
| 创建分析任务 | `POST /api/v1/analysis/jobs` |
| AI 推理服务 | `POST /api/v1/inference/detect` |
| 规则判定 | 内部 `RuleEngine.evaluate` |
| 告警查询 | `GET /api/v1/alarms` |
| 工单回调 | `POST /api/v1/workorders/callbacks/status` |
| 豁免区配置 | `POST /api/v1/exemptions` |
| 模型版本 | `GET /api/v1/models` |
| 全链路运行实例 | `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` |
| AI 结果证据 | `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`、`GET /api/v1/models/{model_group_id}/versions` |
| 参数方案 | `/api/v1/models/{model_group_id}/parameter-profiles`、`/api/v1/parameter-profiles/*` |
| 固定回归集 | `GET /api/v1/models/{model_group_id}/sample-sets`、`POST /api/v1/sample-sets/preview` |
| 分片上传 | `/api/v1/test-uploads/{session_id}/chunked-files/*` |
| 模型测试 | `/api/v1/model-tests/*`、SSE、结果、汇总、对比和报告 |
| 结果反馈 | `POST /api/v1/model-test-results/{result_id}/feedback` |
| 发布治理 | `/api/v1/model-releases/*`、`GET /api/v1/model-audit-logs` |

## 4. 部署方式

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

启动后访问：

- 前端：`http://localhost:8088`
- API 统一入口：`http://localhost:8088/api`
- 后端直连：`http://localhost:8080`
- Swagger：`http://localhost:8080/swagger-ui.html`
- MinIO Console：`http://localhost:9001`
- Prometheus：`http://localhost:9090`

## 5. 验证方式

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

验证内容：

- 后端健康检查
- 全链路可视化运行实例
- 阶段事件与运行快照
- 统计接口
- 工单接口
- 前端页面
- 12 个节点快照与事件顺序
- 资源、结果、告警、工单、样本实体索引

完整交互回归：

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

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

离线环境下，如果无法访问 Docker Hub 或 Maven/npm/PyPI 仓库，可先执行静态校验：

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

该脚本验证：

- FastAPI 服务 Python 语法
- 前端 JSON 配置
- Docker Compose 配置合法性

## 5.1 全链路可视化实现

启动全链路运行时，前端创建运行实例并订阅 SSE 事件流。后端为每个阶段维护独立快照、序列号、进度和重试次数；前端实时更新节点导航、GIS 态势、节点操作区、证据区和事件终端，并支持查看历史节点与从失败节点重试。

已实现阶段包括：

- 运行初始化
- 巡检任务创建
- 航线任务下发
- 多源数据接入
- 数据预处理
- AI 推理分析
- GIS 规则判定
- 告警生成
- 工单派发
- 工单闭环
- 样本回流
- 完成汇总

## 5.2 离线镜像要求

完整部署默认使用已验证可用的华为云 SWR Docker Hub 代理 `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io`，并配置了阿里 PyPI、Maven 多源兜底、npmmirror npm 源。需要以下基础镜像可用：

- `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/postgis/postgis:16-3.4`
- `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/redis:7-alpine`
- `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/bitnami/kafka:3.8.1`
- `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/minio/minio:RELEASE.2024-10-13T13-34-11Z`
- `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/python:3.12-slim`
- `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/maven:3-eclipse-temurin-17`
- `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/node:22-alpine`
- `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/nginx:alpine`
- `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/prom/prometheus:v2.55.0`

如果目标环境无法联网，需要先通过 `docker save` / `docker load` 预置上述镜像，或将 Dockerfile/Compose 的基础镜像替换为内网镜像仓库地址。

## 6. 后续真实算法接入点

- 视觉检测/分割：替换 `ai-services/vision-inference/app/engines.py`
- 点云/TIF 分析：替换 `ai-services/pointcloud-analysis/app/main.py`
- 业务规则：扩展 `platform/backend/.../RuleEngine.java`
- PostGIS 空间计算：在 `PlatformService` 中加入 `ST_DWithin`、`ST_Contains`、里程映射函数

## 7. 页面信息架构落实

前端已从集中式单页调整为 `AppShell + SidebarNav + Vue Router` 结构，并按业务域建立 10 个独立页面。全链路运行仍保持 12 节点连续上下文，GIS、任务、资源、分析、告警、工单、样本模型和运维分别承担长期业务对象的管理职责。

新增页面数据接口包括：

- `GET /api/v1/demo/runs`
- `GET /api/v1/inspection/resources`
- `GET /api/v1/analysis/jobs`
- `GET /api/v1/analysis/results`
- `GET /api/v1/samples`
- `GET /api/v1/platform/events`
- `POST /api/v1/inspection/tasks/{task_id}/cancel`
- `POST /api/v1/alarms/{alarm_id}/decision`

导航与页面回归执行：

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

## 8. 模型管理阶段落实

| 实施阶段 | 落实内容 |
| --- | --- |
| 第一阶段 | 模型组、版本、制品、参数定义与不可变参数修订；动态表单、校验、比较和启停 |
| 第二阶段 | 兼容样本检索、固定回归集、临时上传、分片续传、SHA-256、测试任务与独立执行队列 |
| 第三阶段 | 图片、分割、红外、变化检测、点云查看器；指标汇总、横向比较、报告导出和结果回流 |
| 第四阶段 | 发布申请、审批、灰度、生产切换、回滚、审计、对象生命周期和构建期自动测试 |

数据库迁移 `V5` 至 `V7` 保存模型治理实体、测试输入/结果/事件、发布记录、分片清单和固定回归集。生产模型与参数按双快照生效，测试结果绑定模型版本、参数快照、输入哈希与运行时信息。
