# 停机引导对接协议

## 版本信息

| 项目 | 内容 |
| --- | --- |
| 文档版本 | V1.0 |
| 更新日期 | 2026-07-10 |
| 适用范围 | UDP 组播状态包、HTTP 当前状态查询 |
| 说明 | 初版，对接数据内容以本文字段定义为准。 |

## 1. 协议概述

停机引导系统支持通过组播主动发送检测结果，也支持作为 HTTP 服务端，由现场系统按需查询当前停机状态。现场系统获取数据后，可解析当前停机位、目标编号、机型、到停止线距离、机身偏转角等信息。

协议特点：

- 传输方式：组播，基于 UDP 数据报
- 查询方式：HTTP，停机引导系统作为服务端，现场系统作为客户端
- 数据格式：JSON
- 字符编码：UTF-8
- 组播数据方向：停机引导系统发送，现场系统接收
- HTTP 数据方向：现场系统请求，停机引导系统响应
- 组播应答机制：无应答
- HTTP 应答机制：请求-响应
- 组播重发机制：无重发
- 组播发送时机：每次检测结果更新时发送 1 包数据

## 2. 组播网络参数

组播网络参数由停机引导系统配置。

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| enabled | true | 是否启用组播发送。 |
| address | 239.255.0.1 | 组播地址。 |
| port | 8800 | 组播端口。 |
| targetId | T001 | 目标编号，由软件配置或现场系统约定。 |
| parkId | P01 | 当前停机位编号，由软件配置。 |

配置兜底规则：

- 组播地址为空时使用 `239.255.0.1`
- 端口非法时使用 `8800`
- `targetId` 为空时使用 `T001`
- `parkId` 为空时使用 `P01`

## 3. HTTP 查询对接

HTTP 查询用于现场系统主动获取当前停机状态。停机引导系统作为 HTTP 服务端，返回最近一次检测状态；如果系统刚启动且尚未产生检测结果，则返回失败或无结果数据示例中的状态包。

HTTP 服务参数由停机引导系统配置，不放在参数配置界面。

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| enabled | true | 是否启用 HTTP 状态服务。 |
| address | 0.0.0.0 | HTTP 服务监听地址；`0.0.0.0` 表示监听本机所有网卡。 |
| port | 8801 | HTTP 服务端口。 |
| maxQueued | 16 | 等待处理的最大连接队列数。 |
| maxThreads | 4 | 最大处理线程数。 |

请求方式：

| 项目 | 内容 |
| --- | --- |
| URL | `http://<停机引导设备IP>:8801/api/parking/status` |
| Method | `GET` |
| Request Body | 无 |
| Response Content-Type | `application/json; charset=utf-8` |

兼容路径：

- `/`
- `/status`
- `/api/status`
- `/api/parking/status`

响应数据：

- HTTP 状态码 `200`：返回当前停机状态 JSON，数据内容与 UDP 组播状态包一致，字段与第 4 至第 7 节定义一致。
- HTTP 状态码 `404`：请求路径不存在。
- HTTP 状态码 `405`：请求方法不支持。

现场系统建议按 `timestamp` 判断数据是否更新，避免重复处理同一包状态。

## 4. JSON 数据格式

每包组播数据为一个 JSON 对象。实际发送时为紧凑 JSON，不包含格式化换行。

HTTP 查询接口返回的数据内容与 UDP 组播数据一致，字段、含义、单位和取值规则相同，仅传输方式不同。

本软件每次只检测一个飞机停机位，因此结果字段直接放在顶层对象中，不包含结果数组。

## 5. 成功数据示例

```json
{
  "protocol": "ParkingSpaceGuideResult",
  "version": "1.0",
  "success": true,
  "hasResult": true,
  "targetId": "T001",
  "parkId": "P01",
  "modelType": "A320",
  "guideStateCode": 8,
  "distanceToStop": 500.0,
  "bodyYawAngle": 0.0,
  "lateralOffset": 0.0,
  "aircraftSpeed": 0.4,
  "hasException": false,
  "guideText": "STOP",
  "message": "正常",
  "errorCode": 0,
  "timestamp": 1783339200000
}
```

## 6. 失败或无结果数据示例

检测失败、无有效目标、视野受阻等情况下，系统仍可发送状态包。此时 `success=false`，`hasResult=false`。

```json
{
  "protocol": "ParkingSpaceGuideResult",
  "version": "1.0",
  "success": false,
  "hasResult": false,
  "targetId": "T001",
  "parkId": "P01",
  "modelType": "未知",
  "guideStateCode": 0,
  "distanceToStop": 0.0,
  "bodyYawAngle": 0.0,
  "lateralOffset": 0.0,
  "aircraftSpeed": 0.0,
  "hasException": true,
  "guideText": "",
  "message": "无有效结果",
  "errorCode": -1,
  "timestamp": 1783339200000
}
```

## 7. 字段定义

| 字段 | 类型 | 单位 | 来源 | 说明 |
| --- | --- | --- | --- | --- |
| protocol | string | - | 软件固定值 | 协议名称，固定为 `ParkingSpaceGuideResult`。 |
| version | string | - | 软件固定值 | 协议版本，当前为 `1.0`。 |
| success | bool | - | 软件根据检测结果生成 | `errorCode=0` 且存在有效结果时为 `true`。 |
| hasResult | bool | - | 软件根据检测结果生成 | 本包是否包含有效结果。 |
| targetId | string | - | 软件界面组播参数配置 | 目标编号，默认 `T001`。 |
| parkId | string | - | 软件界面组播参数配置 | 当前停机位编号，默认 `P01`。 |
| modelType | string | - | 算法识别结果 | 机型；算法未识别成功时为 `未知`。 |
| guideStateCode | number | - | 算法检测结果或软件状态 | 引导状态序号；取值见“引导状态枚举”，无有效状态时为 `0`。 |
| distanceToStop | number | 毫米 | 算法检测结果 | 到停止线距离。正负方向按现场标定坐标定义执行。 |
| bodyYawAngle | number | 度 | 算法检测结果 | 机身偏转角。正负方向按现场标定坐标定义执行。 |
| lateralOffset | number | 毫米 | 算法检测结果 | 相对引导中心线的横向偏移。 |
| aircraftSpeed | number | 米/秒 | 算法检测结果 | 飞机接近速度。 |
| hasException | bool | - | 软件根据 `errorCode` 和 `guideStateCode` 生成 | 是否有异常；`errorCode != 0` 或 `guideStateCode` 属于异常情况时为 `true`。 |
| guideText | string | - | 算法检测结果 | 引导状态或显示文本。 |
| message | string | - | 算法结果或软件状态 | 本次数据说明或异常原因。 |
| errorCode | number | - | 算法返回值或软件状态 | 错误码。`0` 表示正常，非 `0` 表示异常或无有效结果。 |
| timestamp | number | 毫秒 | 软件发送时系统时间 | Unix 毫秒时间戳。 |

## 8. 引导状态枚举

`guideStateCode` 取值来源于 `App/ParkingSpaceGuide/Demand/副本T1-42_LED显示式样开发交底-0707.xlsx` 中“序号”列。

| 序号 | 流程/功能 | 显示式样说明 |
| --- | --- | --- |
| 1 | 泊位引导启动 | WAIT |
| 2 | 捕获 | 浮动垂直运行箭头+飞机类型 |
| 3 | 跟踪 | 黄色中心线指示器；偏离中心线时显示闪烁红色转向箭头 |
| 4 | 接近率 | 数字显示距离+米 |
| 5 | 对准中心线 | 距离显示；不显示方向箭头 |
| 6 | 慢速 | SLOW |
| 7 | 方位引导 | 黄色位置箭头+闪烁红色转向箭头 |
| 8 | 到达停止位置 | STOP |
| 9 | 泊位引导完成 | OK |
| 10 | 越位 | TOOFAR |
| 11 | 提前停止 | STOPOK |
| 12 | 等待 | WAIT |
| 13 | 异常慢速-恶劣天气 | SLOW+飞机类型；禁用浮动箭头 |
| 14 | 异常慢速-泊位引导中飞机丢失 | SLOW |
| 15 | 飞机验证失败 | 先WAIT并进行第二次验证；若仍失败，显示STOP+IDFAIL |
| 16 | 机位受阻 | WAIT+GATEBLOCK |
| 17 | 视野受阻 | VIEWBLOCKED |
| 18 | SBU停止 | STOPSBU |
| 19 | 速度过快 | STOPTOOFAST |
| 20 | 紧急停止 | STOP |
| 21 | 挡轮挡 | CHOCKON |
| 22 | 系统错误 | ERROR+错误代码 |
| 23 | 系统故障 | 黑屏 |
| 24 | 电源故障 | 完全黑屏 |

当前协议中，`guideStateCode` 为 `10` 至 `24` 时按异常情况处理，并使 `hasException=true`。

## 9. 对接说明

现场系统如果只需要核心结果，建议优先解析以下字段：

- `targetId`
- `parkId`
- `modelType`
- `guideStateCode`
- `distanceToStop`
- `bodyYawAngle`
- `lateralOffset`
- `aircraftSpeed`
- `hasException`
- `guideText`
- `errorCode`
- `timestamp`

状态判断建议：

- `success=true` 且 `hasResult=true`：本包包含有效引导结果。
- `success=false`：本包为异常、无目标或无有效结果状态包。
- `errorCode=0`：系统正常输出。
- `errorCode != 0`：接收端应结合 `message` 和 `guideText` 做异常显示或记录。
- `hasException=true`：本包存在异常，对应 `errorCode != 0` 或引导状态枚举中的异常情况。

注意事项：

- 组播数据不保证到达和顺序，接收端应以最新 `timestamp` 数据为准。
- 接收端应允许 JSON 增加字段，避免因协议扩展导致解析失败。
- 数值单位以本协议字段定义为准。
- 文本状态建议按原字符串解析。