# 铁路无人机智能巡检系统全链路运行节点可视化分析设计

## 1. 文档信息

| 项目 | 内容 |
| --- | --- |
| 文档名称 | 全链路运行节点可视化分析设计 |
| 适用系统 | 铁路无人机智能巡检系统 |
| 文档版本 | V1.0 |
| 设计范围 | 全链路运行工作台、12 个运行节点、节点专属操作界面、实时事件与运行回放 |
| 目标读者 | 产品、前端、后端、算法、测试、实施与运维人员 |

## 2. 建设目标

全链路运行工作台用于统一呈现从任务准备到样本回流的完整业务过程。页面不只显示阶段名称和总体进度，还要让每个节点具备独立、可操作、可追踪的可视化界面，使用户能够回答以下问题：

- 当前运行到哪一步，是否正常，已经耗时多久。
- 当前节点接收了什么输入，执行了哪些处理，产生了什么输出。
- 任务参数、航线状态、采集数据、质量指标、模型结果、规则结论、告警和工单之间如何关联。
- 节点发生异常时，失败对象、失败原因、影响范围和可恢复动作是什么。
- 运行结束后，能否按时间、实体和空间位置复盘全过程。

设计遵循以下原则：

- 一节点一界面：12 个节点均有专属组件，不以通用键值列表代替业务界面。
- 过程可观察：运行中持续显示子步骤、进度、耗时、吞吐量和最新处理对象。
- 结果可解释：任何告警均能反查资源、预处理、模型结果和规则命中依据。
- 空间可定位：涉及线路、航线、资源、隐患、告警和工单的节点均与 GIS 联动。
- 操作可控制：根据节点能力提供取消、重试、查看、筛选、定位和业务确认操作。
- 状态可恢复：刷新或 SSE 断线后，以运行快照和历史事件重建当前界面。
- 信息可核验：页面字段来自业务实体或事件载荷，不使用无来源的占位数据。

## 3. 设计范围与阶段边界

全链路由 12 个标准节点组成，节点顺序和编码保持稳定。

```mermaid
flowchart LR
    A[运行初始化] --> B[巡检任务创建]
    B --> C[航线任务下发]
    C --> D[多源数据接入]
    D --> E[数据预处理]
    E --> F[AI 推理分析]
    F --> G[GIS 规则判定]
    G --> H[告警生成]
    H --> I[工单派发]
    I --> J[工单闭环]
    J --> K[样本回流]
    K --> L[完成汇总]
```

| 序号 | 节点编码 | 节点名称 | 核心可视对象 | 主要操作 |
| --- | --- | --- | --- | --- |
| 1 | `run.initializing` | 运行初始化 | 运行参数、场景、线路范围、依赖检查 | 取消运行、查看参数 |
| 2 | `task.created` | 巡检任务创建 | 任务参数、执行要求、任务入库结果 | 查看任务、复制编号 |
| 3 | `uav.dispatching` | 航线任务下发 | 航线、无人机、下发回执、飞行进度 | 查看回执、定位无人机、重试下发 |
| 4 | `resource.ingesting` | 多源数据接入 | 图像、视频、红外、TIF、点云资源 | 预览资源、筛选类型、重试接入 |
| 5 | `preprocess.running` | 数据预处理 | 处理流水线、质量检查、标准化产物 | 查看步骤、查看质量报告、重试处理 |
| 6 | `ai.inferencing` | AI 推理分析 | 模型任务、推理进度、识别结果、置信度 | 查看证据、筛选模型、定位结果 |
| 7 | `rule.evaluating` | GIS 规则判定 | 规则输入、阈值、空间命中、抑制原因 | 查看规则、切换图层、定位命中 |
| 8 | `alarm.generating` | 告警生成 | 告警等级、证据链、空间分布、生成状态 | 查看告警、查看证据、定位告警 |
| 9 | `workorder.dispatching` | 工单派发 | 工单、责任人、派发通道、回执、时限 | 查看工单、重新派发、人工改派 |
| 10 | `workorder.closing` | 工单闭环 | 处置进度、反馈材料、复核结果、告警同步 | 查看处置、确认复核、退回处理 |
| 11 | `sample.feedback` | 样本回流 | 候选样本、入池原因、标注队列、模型关联 | 查看样本、调整优先级、排除样本 |
| 12 | `run.completed` | 完成汇总 | 全链路指标、阶段耗时、异常、业务产物 | 查看详情、导出记录、重新运行 |

## 4. 用户角色与关注重点

| 角色 | 主要关注内容 | 允许操作 |
| --- | --- | --- |
| 调度人员 | 任务参数、航线下发、无人机在线状态、采集进度 | 启动、取消、重新下发、查看回执 |
| 分析人员 | 数据质量、预处理结果、模型状态、识别证据 | 查看资源、重试处理、筛选结果、定位隐患 |
| 业务复核人员 | 规则依据、告警等级、证据链、误报原因 | 复核告警、查看规则、提出退回 |
| 工务处置人员 | 工单任务、位置、时限、处置反馈 | 接单、处理、提交反馈 |
| 复核关闭人员 | 处置材料、复核意见、告警状态 | 通过关闭、退回重办 |
| 系统管理员 | 服务健康、事件完整性、失败原因、运行日志 | 重试节点、查看技术详情、导出日志 |

前端应按权限隐藏或禁用操作按钮，但展示数据的业务含义和状态规则保持一致。

## 5. 全链路运行工作台总体设计

### 5.1 页面信息架构

页面采用“全局状态、阶段导航、节点工作区、关联证据”四层结构。

1. 全局运行栏
   - 运行编号、运行状态、总进度、当前节点、开始时间、累计耗时、连接状态。
   - 主要操作包括取消运行、重新运行、打开历史记录。
   - 运行中固定在页面顶部，避免滚动后丢失全局状态。

2. 阶段导航
   - 横向展示 12 个节点，可横向滚动，不因屏幕宽度压缩节点文字。
   - 节点显示序号、名称、状态、节点耗时和产物数量。
   - 点击已开始节点可查看该节点最新快照；点击未开始节点只显示输入依赖和等待原因。

3. 节点工作区
   - 左侧为 GIS 与媒体主视图，占主要宽度。
   - 右侧为当前节点专属操作面板，展示参数、子步骤、指标和操作。
   - 节点切换时保留地图视角、筛选条件和选中的业务实体。

4. 关联证据区
   - 采用页签承载事件、资源、AI 结果、规则命中、告警工单和样本回流。
   - 选择地图对象、列表行或证据项时，其他区域同步高亮同一实体。

### 5.2 页面布局规则

| 区域 | 桌面端建议 | 窄屏建议 | 说明 |
| --- | --- | --- | --- |
| 全局运行栏 | 单行，最小高度 72px | 两行换行 | 主状态和控制按钮始终可见 |
| 阶段导航 | 12 节点横向滚动 | 横向滚动 | 不采用自动换行，保持执行顺序 |
| 主视图区 | 60% - 68% | 独占一行 | GIS、影像、热力图或点云视图 |
| 节点操作区 | 32% - 40%，最小 380px | 独占一行 | 内部独立滚动，避免整页跳动 |
| 关联证据区 | 全宽，建议高度 280px - 360px | 全宽 | 表格虚拟滚动，支持筛选 |

### 5.3 全局状态模型

运行状态：

| 状态 | 含义 | 页面表现 | 可用操作 |
| --- | --- | --- | --- |
| `idle` | 尚未启动 | 时间轴置灰 | 启动 |
| `running` | 正在执行 | 当前节点蓝色进度状态 | 取消、查看详情 |
| `completed` | 全部完成 | 全局绿色完成状态 | 查看、导出、重新运行 |
| `failed` | 节点失败且运行终止 | 失败节点红色，固定显示原因 | 重试节点、导出日志 |
| `cancelled` | 用户或系统取消 | 当前节点黄色取消状态 | 查看、重新运行 |

节点状态：

| 状态 | 含义 | 状态更新规则 |
| --- | --- | --- |
| `pending` | 等待前置节点 | 快照初始化生成 |
| `running` | 已开始处理 | 收到节点 `running` 事件 |
| `completed` | 处理成功 | 收到节点 `completed` 事件 |
| `failed` | 处理失败 | 收到节点 `failed` 事件 |
| `retrying` | 正在重试 | 重试接口受理后进入 |
| `skipped` | 按规则跳过 | 收到节点 `skipped` 事件，并显示原因 |
| `cancelled` | 随运行取消 | 收到取消事件或运行取消快照 |

### 5.4 节点切换与运行跟随

- 默认开启“跟随运行”，当前节点变化时自动切换专属面板。
- 用户主动查看历史节点后，暂停自动切换，并在顶部显示“当前运行已推进到某节点”。
- 点击“回到当前节点”恢复跟随运行。
- 历史节点展示事件发生时的节点快照，不能被后续节点的最新数据覆盖。
- 节点面板需要区分“运行态数据”和“历史态快照”，历史态禁用会改变运行结果的操作。

## 6. 通用交互与联动设计

### 6.1 实体联动

系统使用以下实体标识建立跨区域联动：

| 实体 | 主键字段 | 可关联对象 |
| --- | --- | --- |
| 运行实例 | `run_id` | 所有节点和事件 |
| 巡检任务 | `task_id` | 航线、资源、分析任务、告警 |
| 航线任务 | `mission_id` | 无人机、轨迹、采集资源 |
| 数据资源 | `resource_id` | 预处理记录、AI 结果、证据 |
| 分析任务 | `analysis_job_id` | 模型执行、AI 结果 |
| AI 结果 | `ai_result_id` | 规则命中、告警、样本 |
| 告警 | `alarm_id` | 工单、规则、证据、样本 |
| 工单 | `workorder_id` | 告警、处置记录、复核记录 |
| 样本 | `sample_id` | AI 结果、标注任务、模型版本 |

选择任意实体后，GIS、详情面板和底部页签应同步定位。页面 URL 可使用 `runId`、`step`、`entityType`、`entityId` 保存当前查看上下文。

### 6.2 全局事件流

事件流每条记录至少显示：

- 发生时间和与运行开始时间的相对耗时。
- 节点名称、事件标题、状态和简要说明。
- 关联实体类型和实体编号。
- 关键指标变化，例如接入资源数、模型结果数、告警数。
- 失败事件的错误码、失败对象和建议操作。

筛选条件包括全部、当前节点、异常、数据、模型、规则、告警、工单。事件较多时默认显示最新 200 条，向上滚动按页加载历史记录。

### 6.3 GIS 联动图层

| 图层 | 首次出现节点 | 后续状态变化 |
| --- | --- | --- |
| 铁路中心线与里程标 | 运行初始化 | 全程保留 |
| 巡检任务范围 | 巡检任务创建 | 全程保留 |
| 无人机航线 | 航线任务下发 | 随飞行进度更新 |
| 无人机当前位置 | 航线任务下发 | 接收位置或里程事件更新 |
| 资源采集点 | 多源数据接入 | 预处理失败时标记质量异常 |
| AI 识别点/面 | AI 推理分析 | 规则判定后增加命中样式 |
| 规则缓冲区/重点区 | GIS 规则判定 | 支持显示、隐藏和透明度调节 |
| 告警点 | 告警生成 | 按等级和状态更新 |
| 工单点 | 工单派发 | 按派发、处理中、闭环更新 |

地图图层面板提供显示开关、图例、对象数量和“缩放至图层”操作。地图点位聚合时，点击聚合对象打开分组列表，不直接放大到不可读层级。

## 7. 节点专属可视化设计

### 7.1 运行初始化

#### 展示目标

确认本次运行采用的线路、场景、能力和依赖均已锁定，为后续节点提供可追溯的运行基线。

#### 界面构成

- 运行摘要：运行编号、发起人、启动方式、开始时间、节点总数、配置版本。
- 任务范围：线路编号、线路名称、起止里程、行政区域、坐标系。
- 场景能力：本次启用的隐患场景、数据类型、模型组和规则集。
- 依赖检查：数据库、对象存储、消息服务、视觉服务、点云服务、GIS 服务状态。
- 地图初始化：铁路中心线、里程标、任务范围边界和重点区域。

#### 关键字段

| 字段 | 展示形式 | 必填 |
| --- | --- | --- |
| `run_id` | 可复制文本 | 是 |
| `triggered_by` | 人员/系统标识 | 是 |
| `line_id`、`line_name` | 线路信息 | 是 |
| `mileage_start`、`mileage_end` | 里程范围条 | 是 |
| `coordinate_system` | 标签，默认 WGS84 | 是 |
| `scene_set` | 场景标签组 | 是 |
| `model_groups` | 模型能力列表 | 是 |
| `rule_set_version` | 规则版本 | 是 |
| `dependency_checks` | 健康检查列表 | 是 |

#### 操作与异常

- “查看运行参数”打开只读参数抽屉。
- “取消运行”需要二次确认，成功后停止后续节点。
- 依赖检查失败时明确显示失败服务、检查时间、错误信息和重检入口。
- 非关键依赖降级时显示黄色提示，并在运行摘要中记录降级项。

#### 完成条件

运行实例已创建，所有必需参数已锁定，关键依赖检查通过，地图基础图层加载完成。

### 7.2 巡检任务创建

#### 展示目标

完整展示任务业务参数、执行要求和入库结果，确认后续航线下发所依据的任务定义。

#### 界面构成

- 基本信息：任务编号、任务名称、任务类型、来源、优先级、状态。
- 空间范围：线路、行别、起止里程、巡检长度、重点设施和禁飞区域。
- 执行参数：计划开始时间、时间窗口、飞行高度、速度、重叠率、返航阈值。
- 采集要求：可见光、视频、红外、TIF、点云等类型及质量要求。
- 识别要求：启用场景、模型组、规则集、告警级别策略。
- 创建结果：任务写库状态、事件发布时间、下游订阅确认情况。

#### 关键字段

| 分组 | 字段 |
| --- | --- |
| 任务 | `task_id`、`task_name`、`task_type`、`priority`、`status`、`source` |
| 时间 | `planned_start_time`、`planned_end_time`、`created_at` |
| 线路 | `line_id`、`direction`、`mileage_start`、`mileage_end`、`distance_km` |
| 飞行 | `flight_height_m`、`flight_speed_mps`、`battery_return_threshold` |
| 采集 | `capture_modes`、`image_overlap`、`sampling_interval` |
| 算法 | `scene_set`、`model_groups`、`rule_set_version` |

#### 交互行为

- 点击任务范围，在 GIS 中缩放到巡检区段。
- 点击场景标签，展开该场景的数据要求、模型和规则说明。
- 复制任务编号后，提示复制成功。
- 当前节点失败时，可查看字段校验错误或数据库错误；具备权限的用户可从本节点重试。

#### 节点事件载荷

`visual_payload.type` 为 `task_detail`，至少包含 `task`、`flight_requirements`、`capture_requirements`、`scene_set`、`persistence_status`。

#### 完成条件

任务实体写入成功，返回稳定的 `task_id`，任务创建事件发布成功，航线节点能够读取任务参数。

### 7.3 航线任务下发

#### 展示目标

展示航线计划从平台提交、厂商受理、无人机确认到执行完成的全过程，避免只显示最终“已下发”。

#### 界面构成

- 航线地图：起飞点、降落点、航点、任务范围、禁飞区、返航线。
- 无人机信息：无人机编号、机型、载荷、在线状态、电量、RTK/PPK 状态、链路质量。
- 下发步骤：参数校验、任务提交、平台受理、设备确认、起飞、巡航、返航、完成。
- 回执时间线：请求时间、外部任务编号、响应码、响应说明、回调时间。
- 飞行状态：航线总长、已飞里程、当前里程、预计剩余时间、采集点完成率。

#### 下发状态机

```mermaid
stateDiagram-v2
    [*] --> 待下发
    待下发 --> 下发中
    下发中 --> 已受理
    下发中 --> 下发失败
    已受理 --> 待起飞
    待起飞 --> 飞行中
    飞行中 --> 返航中
    飞行中 --> 执行异常
    返航中 --> 已完成
    下发失败 --> 重试中
    重试中 --> 已受理
    执行异常 --> 返航中
```

#### 关键字段

`mission_id`、`external_mission_id`、`route_id`、`uav_id`、`vendor`、`dispatch_status`、`route_progress`、`current_mileage`、`battery_percent`、`link_quality`、`rtk_status`、`retry_count`、`last_callback_at`、`callback_code`、`callback_message`。

#### 操作与异常

- “查看下发回执”展示请求摘要和厂商响应，不展示敏感认证信息。
- “定位无人机”将 GIS 视角移动到当前位置。
- 下发失败时提供“重新下发”；操作必须携带幂等键，避免厂商平台生成重复任务。
- 长时间无回调时显示“回执超时”，允许主动查询外部任务状态。
- 飞行中仅允许取消或返航类控制，不允许修改已锁定航线参数。

#### 节点事件载荷

`visual_payload.type` 为 `uav_dispatch`，包含 `mission`、`uav`、`waypoints`、`dispatch_steps`、`latest_receipt`、`position`。

#### 完成条件

外部任务已完成或回调确认完成，航线进度达到 100%，关键采集点状态完整。

### 7.4 多源数据接入

#### 展示目标

按资源类型实时展示接入对象、数量、大小、采集位置、传输状态和存储结果，能够快速识别缺失、重复和损坏数据。

#### 界面构成

- 类型统计：可见光图片、视频、红外、TIF、点云的计划数、已接入数、失败数、总大小。
- 接入队列：每个资源显示名称、类型、大小、采集时间、上传进度、校验状态和存储状态。
- 媒体预览：图片缩略图、视频关键帧、红外热力图、TIF 快速预览、点云包围盒摘要。
- 空间分布：GIS 上显示采集点，颜色区分资源类型，异常资源使用警告样式。
- 数据完整性：文件哈希、重复检查、时间连续性、坐标有效性、任务归属检查。

#### 资源列表字段

| 字段 | 说明 |
| --- | --- |
| `resource_id` | 系统资源编号 |
| `resource_name` | 原始文件名或流名称 |
| `resource_type` | `image`、`video`、`thermal`、`tif`、`pointcloud` |
| `capture_time` | 采集时间 |
| `size_bytes` | 文件大小 |
| `upload_progress` | 传输进度 |
| `ingest_status` | 排队、上传中、校验中、已完成、失败、重复 |
| `checksum_status` | 哈希校验结果 |
| `coordinate`、`mileage` | 空间位置 |
| `storage_url` | 对象存储地址，页面脱敏展示 |
| `quality_status` | 待检查、合格、异常 |

#### 交互行为

- 按资源类型、接入状态、质量状态和时间范围筛选。
- 点击资源行，在预览区打开资源，并在地图定位采集位置。
- 点击地图采集点，反向筛选对应资源。
- 单个资源失败时允许重试；批量失败时支持按失败原因批量重试。
- 重复资源默认不重复入库，页面显示原资源编号和判重依据。

#### 节点事件载荷

`visual_payload.type` 为 `resource_ingestion`，包含 `resource_stats`、`resources`、`ingest_rate_mbps`、`received_bytes`、`expected_bytes`、`markers`。

#### 完成条件

必需资源已接入并完成校验，资源与任务、航线、采集位置建立关联；非必需资源缺失需记录缺失原因。

### 7.5 数据预处理

#### 展示目标

将不同数据类型的处理过程拆解为可见流水线，展示每个处理器的输入、输出、质量指标、耗时和异常，而非只显示“预处理完成”。

#### 界面构成

- 流水线视图：资源解析、时间同步、坐标转换、去噪校正、质量检查、标准化输出。
- 类型分支：图像/视频、红外、TIF、点云分别显示专属处理步骤。
- 处理队列：当前处理资源、已完成数、失败数、平均耗时、队列积压。
- 质量面板：清晰度、曝光、模糊度、帧丢失、温度矩阵完整性、点云密度、坐标有效性。
- 产物面板：标准化文件地址、预览、坐标系、尺寸、帧数、点数和质量报告。

#### 处理流水线

```mermaid
flowchart TD
    A[原始资源] --> B[格式识别与解码]
    B --> C[时间戳与任务关联]
    C --> D[坐标转换与里程映射]
    D --> E{资源类型}
    E -->|图像/视频| F[抽帧、畸变校正、去噪、尺寸归一]
    E -->|红外| G[温度矩阵解析、坏点修复、温标校正]
    E -->|TIF| H[投影解析、重采样、栅格裁剪]
    E -->|点云| I[滤波、配准、地面分割、降采样]
    F --> J[质量检查]
    G --> J
    H --> J
    I --> J
    J --> K[标准化资源与质量报告]
```

#### 子步骤字段

`processor_id`、`processor_name`、`resource_type`、`status`、`input_count`、`output_count`、`started_at`、`elapsed_ms`、`quality_metrics`、`error_code`、`error_message`、`retryable`。

#### 操作与异常

- 点击处理器查看处理参数、输入资源、输出产物和日志摘要。
- 质量指标低于阈值时，流程节点显示警告并列出受影响资源。
- 可重试失败支持单处理器重试；重试时沿用同一任务并生成新的处理尝试编号。
- 不可重试失败明确提示重新采集或人工修复建议。
- 处理完成后，允许在原始与处理后资源之间切换对比。

#### 节点事件载荷

`visual_payload.type` 为 `preprocess_pipeline`，包含 `pipelines`、`processors`、`queue_metrics`、`quality_summary`、`outputs`。

#### 完成条件

必需资源均生成标准化产物，质量检查有明确结论，后续 AI 服务所需格式、坐标和元数据完整。

### 7.6 AI 推理分析

#### 展示目标

展示多模型并行处理状态、模型版本、资源分配、结果证据和置信度，使算法执行过程和输出均可检查。

#### 界面构成

- 模型矩阵：视觉检测、分割、变化检测、红外分析、点云分析等模型的排队、运行和完成状态。
- 推理进度：每个模型的输入数、已处理数、吞吐量、平均耗时、设备和显存占用摘要。
- 结果画布：图像检测框/掩膜、红外热点、TIF 差异区域、点云聚类或剖面结果。
- 结果列表：场景、类别、置信度、模型版本、资源、里程和空间坐标。
- 置信度分析：区间分布、低置信度数量、按场景结果统计。

#### 模型任务字段

| 字段 | 说明 |
| --- | --- |
| `analysis_job_id` | 分析任务编号 |
| `model_group`、`model_name` | 模型分组与名称 |
| `model_version` | 实际使用版本 |
| `runtime`、`device` | ONNX Runtime/TensorRT 与执行设备 |
| `status` | 排队、加载、推理中、后处理、完成、失败 |
| `input_count`、`processed_count` | 输入和已处理数量 |
| `result_count` | 结果数量 |
| `avg_confidence` | 平均置信度 |
| `throughput`、`elapsed_ms` | 性能指标 |

#### 交互行为

- 点击模型行筛选该模型产生的结果和地图点位。
- 点击识别结果，在媒体画布中显示证据，同时定位到 GIS。
- 结果列表支持按场景、类别、置信度、模型版本和资源筛选。
- 对低置信度结果可标记“进入人工复核”，但不在当前节点直接修改模型原始输出。
- 模型失败时显示失败服务、错误码、受影响资源和是否可降级；允许重试单个模型任务。

#### 节点事件载荷

`visual_payload.type` 为 `inference_workspace`，包含 `analysis_job`、`models`、`results`、`confidence_buckets`、`performance`、`markers`。

#### 完成条件

所有必需模型完成推理或形成明确降级结论，AI 结果已持久化并可关联到原始资源和模型版本。

### 7.7 GIS 规则判定

#### 展示目标

将 AI 结果转换为可解释的业务判断，清晰展示空间关系、阈值比较、规则版本、命中结果及抑制原因。

#### 界面构成

- GIS 规则图层：线路缓冲区、防护区、接触网 ROI、重点防洪点、豁免区和基线区域。
- 规则执行列表：规则名称、版本、输入值、运算符、阈值、结论、耗时。
- 命中详情：AI 结果、空间计算结果、业务条件、最终风险等级。
- 抑制详情：基线命中、豁免区、重复告警、置信度不足或时间窗口抑制。
- 统计摘要：候选结果数、规则命中数、抑制数、无效数、各规则耗时。

#### 规则判定字段

`rule_id`、`rule_name`、`rule_version`、`ai_result_id`、`input_values`、`operator`、`threshold`、`spatial_relation`、`decision`、`severity`、`suppression_reason`、`elapsed_ms`。

#### 交互行为

- 点击规则，在 GIS 中只显示该规则涉及的图层和候选对象。
- 点击命中记录，打开“输入 -> 计算 -> 决策”证据链。
- 支持在地图中调整规则图层的显示和透明度，不能在运行中直接修改规则阈值。
- 抑制记录必须可见，避免用户误认为 AI 结果丢失。
- 规则服务失败时，可按规则重试；空间数据缺失时显示缺失图层和影响对象。

#### 节点事件载荷

`visual_payload.type` 为 `rule_evaluation`，包含 `rules`、`rule_hits`、`suppressed_items`、`spatial_layers`、`markers`、`statistics`。

#### 完成条件

所有候选 AI 结果均有规则判定记录，命中与抑制结论可解释，可生成告警的结果已标记等级。

### 7.8 告警生成

#### 展示目标

展示规则结论转化为告警的过程，并建立完整的告警证据链、分级结果和空间定位。

#### 界面构成

- 告警漏斗：AI 候选结果、规则命中、被抑制、有效告警、待派单。
- 告警等级分布：严重、高、中、低四级数量和占比。
- 告警列表：告警编号、场景、类别、等级、状态、里程、时间和置信度。
- 证据链：原始资源、预处理产物、AI 结果、规则命中、告警实体。
- GIS 分布：按等级着色，选中告警后显示里程、距离和影响范围。

#### 关键字段

`alarm_id`、`scene`、`category`、`severity`、`confidence`、`status`、`location`、`mileage`、`rule_hit_ids`、`evidence_items`、`generated_at`、`deduplication_key`。

#### 交互行为

- 点击告警打开详情抽屉，支持按证据链逐项查看。
- 点击“地图定位”同步选中 GIS 点位并缩放。
- 支持按等级、状态、场景和时间筛选。
- 重复告警聚合显示，并保留聚合前的原始记录。
- 告警生成失败时显示失败候选、字段校验结果和重试入口。

#### 节点事件载荷

`visual_payload.type` 为 `alarm_generation`，包含 `funnel`、`severity_counts`、`alarms`、`evidence_summary`、`markers`。

#### 完成条件

每条有效规则命中均生成告警或形成明确的去重/抑制记录，告警证据链和空间位置完整。

### 7.9 工单派发

#### 展示目标

展示告警到工单的转换、责任分配、外部系统投递和回执过程，明确每张工单是否真正到达处置人员。

#### 界面构成

- 派发流程：告警待派发、工单创建、责任匹配、消息发送、外部受理、待处理。
- 工单列表：工单编号、关联告警、专业、责任人、班组、优先级、时限和状态。
- 派发回执：派发通道、外部工单编号、响应码、响应信息、回执时间。
- 责任匹配：按线路、里程、专业、班组和值班计划展示匹配依据。
- GIS 状态：告警点增加工单标识，颜色体现待受理、处理中和派发失败。

#### 派发状态机

```mermaid
stateDiagram-v2
    [*] --> 待创建
    待创建 --> 已创建
    已创建 --> 派发中
    派发中 --> 已送达
    派发中 --> 派发失败
    已送达 --> 已受理
    派发失败 --> 重新派发
    重新派发 --> 已送达
    已受理 --> 处理中
```

#### 关键字段

`workorder_id`、`alarm_id`、`external_workorder_id`、`professional_type`、`assignee`、`team`、`priority`、`deadline`、`dispatch_channel`、`dispatch_status`、`receipt_code`、`receipt_message`、`retry_count`。

#### 操作与异常

- “查看工单”打开工单详情和关联告警证据。
- 派发失败时支持重新派发；具备权限时可人工改派责任人。
- 改派需要填写原因，并生成审计事件。
- 外部系统已创建但本地超时时，先主动查询外部状态，再决定是否重试，避免重复工单。

#### 节点事件载荷

`visual_payload.type` 为 `workorder_dispatch`，包含 `dispatch_flow`、`workorders`、`assignment_summary`、`receipts`、`markers`。

#### 完成条件

所有需要处置的告警均建立工单或记录无需派单原因，工单责任人与时限明确，外部派发有回执。

### 7.10 工单闭环

#### 展示目标

可视化展示工单从受理、现场处置、反馈、复核到关闭的完整过程，并确认告警状态同步更新。

#### 界面构成

- 闭环总览：工单总数、待受理、处理中、待复核、已闭环、退回数量。
- 工单泳道：按状态列展示工单卡片，状态变化时在泳道间移动。
- 处置时间线：受理、到场、处理、提交、复核、关闭的时间和操作人。
- 处置材料：现场照片、说明、结果类型、附件和定位信息。
- 复核信息：复核人、结论、意见、告警同步状态和样本回流标记。

#### 闭环状态机

```mermaid
stateDiagram-v2
    [*] --> 待受理
    待受理 --> 处理中
    处理中 --> 待复核
    待复核 --> 已闭环
    待复核 --> 已退回
    已退回 --> 处理中
    已闭环 --> [*]
```

#### 关键字段

`workorder_id`、`status`、`assignee`、`accepted_at`、`arrived_at`、`handled_at`、`reviewed_at`、`closed_at`、`close_result`、`comment`、`attachments`、`review_result`、`alarm_sync_status`。

#### 交互行为

- 点击泳道卡片查看处置材料和告警证据。
- 有权限的复核人员可执行“复核通过”或“退回重办”。
- 复核操作必须填写意见；退回时必须选择原因。
- 告警同步失败时，工单可显示已闭环，但需单独标记“告警状态同步失败”并提供重试。
- GIS 点位随工单状态变化，闭环后保留点位但改为完成状态。

#### 节点事件载荷

`visual_payload.type` 为 `workorder_closure`，包含 `status_counts`、`swimlanes`、`workorders`、`operation_records`、`alarm_sync_results`、`markers`。

#### 完成条件

计划闭环工单已完成复核，工单与告警状态一致；未闭环工单有明确状态、负责人和剩余时限。

### 7.11 样本回流

#### 展示目标

展示运行结果如何进入算法数据闭环，明确候选样本来源、入池原因、标注优先级和关联模型版本。

#### 界面构成

- 样本漏斗：AI 结果、候选样本、自动排除、待标注、已入池。
- 入池原因：低置信度、误报、漏报补录、规则争议、复核确认、场景稀缺。
- 样本队列：样本编号、场景、来源资源、告警/工单、原因、优先级和状态。
- 模型关联：产生结果的模型版本、目标模型组、预计进入的数据集版本。
- 质量检查：隐私脱敏、证据完整性、标签冲突、重复样本和数据许可状态。

#### 关键字段

`sample_id`、`source_type`、`source_entity_id`、`resource_id`、`ai_result_id`、`alarm_id`、`workorder_id`、`feedback_reason`、`priority`、`labeling_status`、`target_model_group`、`source_model_version`、`dataset_version`、`quality_status`。

#### 交互行为

- 点击样本查看原始资源、模型输出、规则结果和复核结论。
- 具备权限时可调整标注优先级或排除不应回流的样本，操作需记录原因。
- 重复样本展示聚类依据和保留样本。
- 质量检查失败时明确显示阻断项，不进入正式数据集。

#### 节点事件载荷

`visual_payload.type` 为 `sample_feedback`，包含 `funnel`、`samples`、`reason_counts`、`model_groups`、`quality_summary`。

#### 完成条件

候选样本均有入池或排除结论，样本可追溯到资源、AI 结果、告警、工单和模型版本。

### 7.12 完成汇总

#### 展示目标

从业务结果、技术执行、空间态势和异常情况四个维度总结本次运行，并支持后续复盘与导出。

#### 界面构成

- 业务指标：任务数、资源数、AI 结果数、规则命中数、有效告警数、工单数、闭环数、回流样本数。
- 阶段耗时：12 个节点的开始时间、结束时间、耗时、重试次数和状态。
- 质量指标：资源完整率、预处理通过率、模型成功率、告警转工单率、工单闭环率。
- 空间结果：最终 GIS 图层，支持按告警等级和工单状态筛选。
- 异常摘要：失败、警告、降级、重试和未完成事项。
- 产物索引：任务、资源、分析任务、告警、工单、样本的编号与查看入口。

#### 关键指标计算

| 指标 | 计算方式 |
| --- | --- |
| 数据接入完成率 | 成功接入资源数 / 计划资源数 |
| 数据质量通过率 | 质量合格资源数 / 已完成预处理资源数 |
| 模型执行成功率 | 成功模型任务数 / 应执行模型任务数 |
| 规则有效命中率 | 有效规则命中数 / AI 候选结果数 |
| 告警派单率 | 已生成工单告警数 / 需派单告警数 |
| 工单闭环率 | 已闭环工单数 / 工单总数 |
| 全链路成功 | 所有必需节点完成且无阻断异常 |

#### 交互行为

- 点击任意指标跳转至对应节点和关联实体列表。
- 点击阶段耗时条查看该节点的事件和性能指标。
- 导出运行记录时包含参数、节点状态、指标、异常和业务实体索引。
- “重新运行”默认复用本次参数，但创建新的运行编号，并在确认页显示可修改项。

#### 节点事件载荷

`visual_payload.type` 为 `run_summary`，包含 `business_metrics`、`quality_metrics`、`step_durations`、`exceptions`、`entity_index`、`markers`。

#### 完成条件

运行状态进入终态，12 个节点均有明确状态，汇总指标与业务实体查询结果一致。

## 8. 前端组件设计

建议将现有全链路区域拆分为容器组件、通用组件和节点专属组件。

```text
frontend/src/components/full-chain-run/
  FullChainRunConsole.vue
  RunHeader.vue
  RunStageNavigator.vue
  RunWorkspace.vue
  RunGisMap.vue
  RunEntityInspector.vue
  RunEventStream.vue
  RunEvidenceTabs.vue
  common/
    StepStatus.vue
    MetricItem.vue
    EntityLink.vue
    ErrorPanel.vue
    EvidenceChain.vue
    OperationRecord.vue
  steps/
    RunInitializationPanel.vue
    InspectionTaskPanel.vue
    UavDispatchPanel.vue
    ResourceIngestionPanel.vue
    PreprocessPipelinePanel.vue
    InferenceWorkspacePanel.vue
    RuleEvaluationPanel.vue
    AlarmGenerationPanel.vue
    WorkorderDispatchPanel.vue
    WorkorderClosurePanel.vue
    SampleFeedbackPanel.vue
    RunSummaryPanel.vue
```

组件职责：

- `FullChainRunConsole` 负责运行实例加载、整体布局和全局错误边界。
- `RunStageNavigator` 负责节点状态、节点选择和跟随运行。
- `RunWorkspace` 根据 `step_key` 加载专属组件，不在模板中堆叠大量条件分支。
- `RunGisMap` 维护图层和选中实体，不包含节点业务判断。
- 节点组件只接收标准化节点快照，并通过事件触发查看、定位、重试等操作。
- `RunEvidenceTabs` 维护跨节点实体列表，支持从专属面板跳转到关联证据。

### 8.1 节点组件注册表

```ts
const stepComponentMap = {
  "run.initializing": RunInitializationPanel,
  "task.created": InspectionTaskPanel,
  "uav.dispatching": UavDispatchPanel,
  "resource.ingesting": ResourceIngestionPanel,
  "preprocess.running": PreprocessPipelinePanel,
  "ai.inferencing": InferenceWorkspacePanel,
  "rule.evaluating": RuleEvaluationPanel,
  "alarm.generating": AlarmGenerationPanel,
  "workorder.dispatching": WorkorderDispatchPanel,
  "workorder.closing": WorkorderClosurePanel,
  "sample.feedback": SampleFeedbackPanel,
  "run.completed": RunSummaryPanel
};
```

### 8.2 前端状态分层

| 状态层 | 内容 | 更新来源 |
| --- | --- | --- |
| 运行状态 | 运行编号、总体状态、总进度、当前节点 | 快照、SSE |
| 节点状态 | 12 个节点状态、耗时、最近事件 | 快照、SSE |
| 节点快照 | 每个节点最后一次完整可视化载荷 | SSE 合并、快照恢复 |
| 实体索引 | 任务、资源、结果、告警、工单、样本 | 节点事件、业务查询 |
| GIS 状态 | 图层、对象、选中实体、视角 | 事件与用户操作 |
| UI 状态 | 当前节点、页签、筛选、跟随运行 | 用户操作 |

不得仅使用“最后一条事件”作为当前节点的全部数据源。前端需要按 `step_key` 保存节点聚合快照，否则子步骤事件会覆盖此前已经展示的节点数据。

## 9. 事件与可视化载荷设计

### 9.1 通用事件结构

```json
{
  "event_id": "dre-001",
  "run_id": "run-001",
  "sequence": 18,
  "step_key": "preprocess.running",
  "step_name": "数据预处理",
  "event_type": "processor.completed",
  "status": "running",
  "step_progress": 64,
  "run_progress": 35,
  "title": "空间坐标归一完成",
  "message": "采集点、航线和线路里程已建立关联",
  "entity_type": "resource",
  "entity_id": "res-001",
  "attempt": 1,
  "metrics": {},
  "visual_payload": {
    "type": "preprocess_pipeline",
    "schema_version": "1.0",
    "patch_mode": "merge"
  },
  "created_at": "2026-07-21T16:20:08+08:00"
}
```

新增字段说明：

| 字段 | 用途 |
| --- | --- |
| `sequence` | 保证断线恢复和乱序事件重排 |
| `event_type` | 区分节点开始、子步骤进度、实体更新和节点完成 |
| `step_progress` | 当前节点内部进度，范围 0 - 100 |
| `run_progress` | 全链路总体进度，范围 0 - 100 |
| `attempt` | 节点或子任务重试次数 |
| `schema_version` | 可视化载荷兼容版本 |
| `patch_mode` | `replace` 或 `merge`，明确前端聚合方式 |

### 9.2 节点载荷类型

| 节点 | `visual_payload.type` | 主要载荷 |
| --- | --- | --- |
| 运行初始化 | `run_initialization` | 参数、能力、依赖检查、基础图层 |
| 巡检任务创建 | `task_detail` | 任务、飞行要求、采集要求、场景集 |
| 航线任务下发 | `uav_dispatch` | 航线、无人机、回执、飞行进度 |
| 多源数据接入 | `resource_ingestion` | 类型统计、资源列表、传输指标、采集点 |
| 数据预处理 | `preprocess_pipeline` | 流水线、处理器、质量指标、输出产物 |
| AI 推理分析 | `inference_workspace` | 模型任务、结果、置信度、性能 |
| GIS 规则判定 | `rule_evaluation` | 规则、命中、抑制、空间图层 |
| 告警生成 | `alarm_generation` | 漏斗、等级、告警、证据 |
| 工单派发 | `workorder_dispatch` | 派发流程、工单、责任匹配、回执 |
| 工单闭环 | `workorder_closure` | 泳道、处置记录、复核、状态同步 |
| 样本回流 | `sample_feedback` | 漏斗、样本、原因、模型关联 |
| 完成汇总 | `run_summary` | 业务指标、质量指标、耗时、异常 |

### 9.3 快照恢复

运行快照除总体状态外，应返回 `step_snapshots`：

```json
{
  "run_id": "run-001",
  "status": "running",
  "progress": 55,
  "current_step": "ai.inferencing",
  "last_sequence": 18,
  "steps": [],
  "step_snapshots": {
    "task.created": {},
    "uav.dispatching": {},
    "resource.ingesting": {},
    "preprocess.running": {},
    "ai.inferencing": {}
  },
  "entity_index": {},
  "gis_layers": {}
}
```

恢复顺序：加载快照、渲染节点快照、从 `last_sequence` 后补拉历史事件、建立 SSE、继续接收新事件。事件按 `event_id` 去重，按 `sequence` 排序。

## 10. 接口设计补充

现有运行创建、快照、事件订阅、历史事件和取消接口继续作为基础能力。为支持节点专属界面和可操作性，增加以下接口。

| 方法 | 接口 | 用途 |
| --- | --- | --- |
| `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` | 获取 AI 结果证据 |
| `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` | 样本入池、排除或调整优先级 |

重试接口请求包含 `reason`、`operator`、`expected_attempt` 和 `idempotency_key`。服务端校验节点是否允许重试，并返回新的尝试编号。

## 11. 错误、降级与恢复设计

### 11.1 错误分级

| 级别 | 含义 | 处理方式 |
| --- | --- | --- |
| 阻断错误 | 无法继续后续节点 | 运行失败，显示重试入口 |
| 节点错误 | 部分对象失败但可继续 | 节点警告完成，列出失败对象 |
| 数据质量警告 | 数据可用但质量不理想 | 继续执行并传递质量标识 |
| 外部回执超时 | 外部状态不确定 | 主动查询，不立即重复提交 |
| 展示错误 | 业务已完成但可视化载荷异常 | 回退到节点快照，记录前端错误 |

### 11.2 错误面板内容

- 错误标题、错误码、发生时间、节点和关联实体。
- 用户可理解的原因说明，技术堆栈仅在管理员详情中展示。
- 影响范围：失败资源数、受影响模型、未生成告警或未派发工单。
- 可执行动作：重试、跳过、取消、查看日志、重新采集。
- 操作结果：请求是否受理、新尝试编号和恢复进度。

### 11.3 SSE 连接状态

页面全局栏显示实时连接状态：已连接、重连中、已断开。断线时不清空页面；先尝试自动重连，重连后使用快照和序列号补齐事件。长时间无法恢复时提示用户刷新状态，但保留现有节点快照。

## 12. 视觉与交互规范

- 维持现有工作台的深蓝主色和白色内容面，不引入与业务状态冲突的装饰色。
- 运行中使用蓝色，成功使用绿色，警告/待处理使用橙色，失败/严重使用红色，未开始使用灰色。
- 告警等级颜色与运行状态颜色通过图标和文字同时区分，避免只依赖颜色。
- 卡片圆角不超过 8px；节点内部优先使用分组、表格和流程，不堆叠卡片。
- 图标按钮使用统一图标库，并提供悬停提示和无障碍名称。
- 关键编号使用等宽字体，支持复制；长地址采用中间省略并保留完整悬停提示。
- 列表、地图和详情面板的选中状态保持一致，选中实体不得因新事件到达而丢失。
- 动画只用于表示真实进度和状态变化；用户开启减少动态效果时关闭移动和闪烁。
- 节点标题、按钮和状态文字在 1366px、1920px 及窄屏下均不可被截断或覆盖。

## 13. 测试与验收设计

### 13.1 节点功能测试

每个节点至少覆盖以下测试：

- `pending`、`running`、`completed`、`failed`、`retrying`、`skipped` 状态渲染。
- 首次事件、连续进度事件、节点完成事件的快照合并。
- 专属字段完整展示，缺失可选字段时界面不报错。
- 列表选择、GIS 定位、证据查看和跨页签联动。
- 失败对象显示、重试操作、重复点击防护和权限控制。
- 历史节点查看时不被当前节点事件覆盖。

### 13.2 全链路集成测试

- 启动后 12 个节点按定义顺序推进，阶段导航与后台状态一致。
- 每个节点至少产生一次可观察变化和一个完整节点快照。
- 巡检任务参数能够传递到航线下发，航线和资源建立关联。
- 资源能够关联预处理记录、AI 结果、规则命中、告警、工单和样本。
- GIS 在对应节点依次增加航线、资源、AI、规则、告警和工单图层。
- 快照统计与业务查询结果一致，完成汇总可反向进入对应节点。
- 工单闭环后，告警状态、地图样式和样本回流信息同步更新。

### 13.3 异常与恢复测试

- SSE 在各节点断开后能够自动恢复，事件不丢失、不重复。
- 页面刷新后恢复当前节点、历史节点快照、选中实体和图层数据。
- 航线下发超时不会产生重复外部任务。
- 数据接入单资源失败可单独重试，不重复处理成功资源。
- 单模型失败可按策略重试或降级，其他模型结果不丢失。
- 工单派发超时先查询外部状态，再决定是否重试。
- 重试后的事件通过 `attempt` 区分，并保留此前失败记录。

### 13.4 性能验收

| 场景 | 验收要求 |
| --- | --- |
| 事件接收 | 新事件到界面更新的可见延迟不高于 1 秒 |
| 资源列表 | 1 万条资源使用分页或虚拟列表，滚动无明显卡顿 |
| GIS 点位 | 1 万点自动聚合，地图交互保持可用 |
| 事件历史 | 首屏只加载最近事件，历史事件分页加载 |
| 页面恢复 | 常规运行快照在 3 秒内完成主体界面恢复 |
| 长时间运行 | 连续运行 2 小时，浏览器内存无持续无界增长 |

### 13.5 业务验收标准

- 12 个节点均有专属界面，节点间不能仅通过标题和通用键值列表区分。
- 巡检任务节点完整展示任务、线路、飞行、采集和算法参数。
- 航线任务下发节点完整展示下发步骤、平台回执、无人机状态和飞行进度。
- 多源数据接入节点展示实际接入资源、传输进度、存储与质量状态。
- 数据预处理节点展示分类型处理流水线、处理器状态、质量指标和产物。
- AI、规则、告警节点形成可追溯证据链，并支持 GIS 定位。
- 工单派发和闭环节点展示状态流转、操作记录、负责人、时限和反馈材料。
- 样本回流节点可追溯样本来源、入池原因和模型版本。
- 完成汇总中的指标均可跳转到对应节点和实体明细。
- 失败、取消、重试、断线和页面刷新场景均能显示明确状态并恢复数据。

## 14. 实施优先级

### 第一阶段：节点框架与状态聚合

- 拆分运行工作台和 12 个节点组件。
- 建立按 `step_key` 保存的节点快照，改造“只读取最后一条事件”的状态方式。
- 完成阶段导航、历史节点查看、跟随运行和通用错误面板。

### 第二阶段：任务、航线、数据和预处理

- 实现巡检任务参数面板。
- 实现航线下发回执、飞行进度和 GIS 航线联动。
- 实现多源资源列表、预览、传输进度和采集点。
- 实现分类型预处理流水线和质量报告。

### 第三阶段：AI、规则和告警证据链

- 实现模型矩阵、结果画布、置信度筛选和结果定位。
- 实现规则图层、阈值判定、命中与抑制详情。
- 实现告警漏斗、等级分布和完整证据链。

### 第四阶段：工单闭环与样本回流

- 实现工单派发流程、回执和改派操作。
- 实现闭环泳道、处置材料、复核及告警状态同步。
- 实现样本候选、质量检查、入池决策和模型关联。

### 第五阶段：恢复、性能与验收

- 增加节点快照、事件序列、断线恢复和节点重试接口。
- 完成大数据量列表、GIS 点位聚合和长时间运行优化。
- 按节点功能、全链路、异常恢复和性能标准完成验收。

## 15. 设计结论

全链路运行工作台应从“阶段进度展示”升级为“节点业务操作与证据工作台”。核心改造点是建立 12 个节点专属组件、按节点聚合的运行快照、可解释的跨实体证据链和可恢复的事件模型。完成后，任务参数、航线回执、资源接入、预处理流水线、模型推理、规则判定、告警、工单和样本回流均可在同一运行上下文中被查看、操作和复盘。
