# 停机引导远程控制协议

## 版本信息

| 项目 | 内容 |
| --- | --- |
| 文档版本 | V1.1 |
| 更新日期 | 2026-09-09 |
| 适用范围 | ParkingSpaceGuideView 远程发现、控制和状态订阅 |
| 说明 | 控制端协议。引导结果字段见《停机引导对接协议》。 |

远程协议名称为 `ParkingSpaceGuideRemote`，版本 `1.1`。

## 1. 协议概述

`ParkingSpaceGuideApp` 提供远程服务。`ParkingSpaceGuideView` 通过 UDP 发现服务端，通过 ZeroMQ REQ/REP 发送控制命令，通过 ZeroMQ PUB/SUB 接收实时引导结果。

状态数据与《停机引导对接协议》中的 `ParkingSpaceGuideResult` 相同。

默认参数：

| 参数 | 默认值 | 传输方式 | 用途 |
| --- | ---: | --- | --- |
| discoveryPort | 5555 | UDP | 控制端广播搜索，服务端单播响应。 |
| controlPort | 15655 | ZeroMQ REQ/REP | 选择机型、开始/停止、维护模式、轮挡时间、历史回放。 |
| publishPort | 15656 | ZeroMQ PUB/SUB | 发布完整引导状态。 |
| topic | parking_guide | ZeroMQ topic | 状态订阅主题。 |

## 2. UDP 发现

请求：

```json
{"cmd":"discover","service":"ParkingSpaceGuide","protocol":"ParkingSpaceGuideRemote"}
```

响应：

```json
{
  "ok": true,
  "code": 0,
  "cmd": "discover",
  "protocol": "ParkingSpaceGuideRemote",
  "version": "1.1",
  "service": "ParkingSpaceGuide",
  "deviceName": "ParkingSpaceGuideApp",
  "deviceId": "设备唯一标识",
  "controlPort": 15655,
  "publishPort": 15656,
  "topic": "parking_guide",
  "activated": false,
  "workMode": "normal",
  "timestamp": 1783339200000
}
```

须校验 `ok`、`cmd`、`protocol`、`service`，并确认端口和主题有效。

## 3. ZeroMQ 控制

请求和应答均为单个紧凑 JSON。请求包含 `cmd`、`protocol`（固定 `ParkingSpaceGuideRemote`）。

| cmd | 请求字段 | 说明 |
| --- | --- | --- |
| select_model | `modelType` | 选择机型，须为当前配置中的可选机型。此处 `modelType` 为选择值，不是检测结果。 |
| start | `modelType`，可空 | 开始引导。空表示不选机型、不校验。 |
| stop | 无 | 停止引导。 |
| set_maintenance | `enabled` | `true` 进入维护模式，`false` 退出。 |
| chock_on / chock_off | 无 | 记录上/下轮挡时间。 |
| get_panel_config | 无 | 获取机型表和当前运行状态。 |
| list_sessions | `limit` | 列出历史会话，默认 50 条。 |
| get_session_samples | `sessionUuid` | 获取会话引导明细，按时间排序，用于还原该次引导过程。 |
| get_status | 无 | 获取当前完整 `ParkingSpaceGuideResult`。 |
| get_info | 无 | 获取服务信息，字段同发现响应。 |
| ping | 无 | 心跳。 |

成功：`ok=true`，`code=0`。失败：

```json
{
  "ok": false,
  "code": -3,
  "cmd": "start",
  "message": "服务端拒绝启动停机引导，请检查设备或安全状态",
  "protocol": "ParkingSpaceGuideRemote",
  "version": "1.1"
}
```

| code | 含义 |
| ---: | --- |
| 0 | 成功 |
| -1 | 请求不是有效 JSON |
| -2 | 参数错误 |
| -3 | 服务端拒绝执行 |
| -4 | 不支持的命令 |
| -5 | 协议名称不匹配 |

开始（`modelType` 须为当前配置中的机型名称，下面 `C919` 仅为示例）：

```json
{"cmd":"start","protocol":"ParkingSpaceGuideRemote","modelType":"C919"}
```

不选机型开始：

```json
{"cmd":"start","protocol":"ParkingSpaceGuideRemote","modelType":""}
```

开始成功时返回 `activated=true`、`workMode`。停止成功时 `activated=false`。

`get_status` 的 `status` 为《停机引导对接协议》定义的完整结果对象。

`get_panel_config` 的 `panel`：`models` 为当前配置的可选机型，不是协议写死的清单。`C919` 仅为示例。

```json
{
  "models": [
    { "name": "A320", "verifiable": true },
    { "name": "B737", "verifiable": true },
    { "name": "C919", "verifiable": false }
  ],
  "workMode": "normal",
  "activated": false
}
```

`verifiable=true` 表示选择名称包含 `A320` 或 `B737`，按检测家族匹配，例如 `A320-200` 对应检测 `A320`。其余配置机型为 `false`。

`list_sessions` 返回 `sessions` 数组。字段与《停机引导对接协议》第 7 节对齐，另含 `sessionUuid`、`startTime`、`endTime`。`sessionUuid` 仅用于回放关联，不是结果协议字段。`startTime`、`endTime` 及轮挡时间为设备本地 `yyyy-MM-dd HH:mm:ss`；未记录或进行中的时间为空。

`get_session_samples` 返回 `samples` 数组，按 `timestamp` 升序。元素为当时完整 `ParkingSpaceGuideResult`，字段与《停机引导对接协议》第 7 节一致，不含点云和图像。

历史数据来自本机 MariaDB 三张表，表间关系见《停机引导对接协议》第 11 节。`list_sessions` 读 `guide_session`，`get_session_samples` 按 `sessionUuid` 读该会话的 `guide_detail`。`guide_event` 只在记录库中，本协议不提供事件查询。

## 4. ZeroMQ 状态订阅

发布为双帧消息：第一帧为主题 `parking_guide`，第二帧为完整 `ParkingSpaceGuideResult` JSON。客户端须按完整主题匹配。