Ren/airport-qingdao-vue3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
airport-qingdao-vue3/frontend_platform_http_api_integration.md

11 KiB
Raw Permalink Blame History

前端接入文档：新增平台 HTTP 接口

1. 背景

本次后端新增了一组 HTTP 接口，供前端在现有 WebSocket 交互之外，补充以下能力：

  • 同步“当前关心的对象及其类型”
  • 运行时修改部分碰撞检测相关参数

2. 通用约定

  • 所有接口均为 POST
  • 所有请求和响应均为 application/json
  • 当前接口无鉴权、无 token、无签名校验
  • 当前后端未补 CORS
    • 如果前端是浏览器并且跨域访问，后续可能还需要后端补 CORS
  • 配置修改仅在内存中生效
    • 服务重启后恢复默认配置
  • VehicleRegistry 是“增量更新”
    • 本次未传入的历史对象不会被清空

建议前端统一配置接口基础地址，例如：

const API_BASE = 'http://<后端IP>:8080';

3. 接口一：对象注册同步

3.1 接口地址

POST /api/VehicleRegistry

3.2 用途

前端将“当前关心的对象及其类型”增量同步给后端。

该接口会直接影响：

  • 哪些对象参与碰撞检测
  • 哪些车辆可能被系统下发控制命令

3.3 请求头

Content-Type: application/json

3.4 请求体

[
  { "vehicleID": "QN001", "vehicleType": "WUREN" },
  { "vehicleID": "TQ001", "vehicleType": "TEQIN" },
  { "vehicleID": "AC001", "vehicleType": "HANGKONG" }
]

3.5 字段说明

字段 类型 必填 说明
vehicleID string 是 对象唯一标识，不能为空
vehicleType string 是 对象类型，只允许固定枚举值

3.6 vehicleType 可选值

  • WUREN
  • TEQIN
  • HANGKONG
  • PUTONG
  • JIUYUAN

3.7 业务语义

WUREN

  • 加入“可控车辆集合”
  • 加入“受管车辆集合”

TEQIN

  • 加入“受管车辆集合”
  • 不属于“可控车辆集合”

HANGKONG

  • 加入“已选中航空器集合”
  • 用于参与航空器相关碰撞/安全区计算

PUTONG

  • 仅记录类型
  • 不进入可控/受管/已选航空器集合

JIUYUAN

  • 仅记录类型
  • 不进入可控/受管/已选航空器集合

3.8 成功响应

{
  "status": "success",
  "updatedAt": 1742280000000,
  "updated": 3,
  "controllableCount": 1,
  "typesCount": {
    "WUREN": 1,
    "TEQIN": 1,
    "HANGKONG": 1
  },
  "controllableVehicleIDs": ["QN001"]
}

3.9 响应字段说明

字段 类型 说明
status string 固定为 success
updatedAt number 毫秒时间戳
updated number 本次成功处理的条目数
controllableCount number 当前系统内全部 WUREN 总数
typesCount object 本次请求内各类型数量统计
controllableVehicleIDs string[] 当前系统内全部可控车辆 ID 列表，即所有 WUREN

3.10 错误响应示例

请求体不是数组

{
  "status": "error",
  "message": "Body must be an array"
}

参数非法

{
  "status": "error",
  "message": "Invalid request",
  "errors": [
    "item must be an object",
    "missing vehicleID",
    "missing vehicleType",
    "vehicleID must be string",
    "vehicleType must be string",
    "vehicleID must be non-empty",
    "invalid vehicleType=xxx"
  ]
}

非法 JSON

{
  "status": "error",
  "message": "Invalid JSON",
  "detail": "..."
}

3.11 前端调用示例

await fetch(`${API_BASE}/api/VehicleRegistry`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify([
    { vehicleID: 'QN001', vehicleType: 'WUREN' },
    { vehicleID: 'TQ001', vehicleType: 'TEQIN' },
    { vehicleID: 'AC001', vehicleType: 'HANGKONG' }
  ])
});

3.12 接入建议

  • 页面首次拿到关注对象列表后调用一次
  • 当前关注对象发生变化时再次调用
  • 请求体必须是数组，即使只有一条数据也必须传数组
  • 后端是“增量更新”，不要假设未传对象会被清空

4. 接口二：跑道区域航空器预警区半径

4.1 接口地址

POST /config/runway/warning_zone_radius/aircraft

4.2 用途

前端运行时修改跑道区域的“航空器预警区半径”。

4.3 请求头

Content-Type: application/json

4.4 请求体

{ "value": 300 }

4.5 字段说明

字段 类型 必填 说明
value number 是 必须是大于 0 的有限数值

4.6 成功响应

{
  "status": "success",
  "area": "runway",
  "field": "warning_zone_radius.aircraft",
  "old": 200.0,
  "new": 300.0
}

4.7 错误响应示例

缺少字段

{
  "status": "error",
  "message": "Missing field: value"
}

值非法

{
  "status": "error",
  "message": "Invalid value: must be a finite number greater than 0"
}

非法 JSON

{
  "status": "error",
  "message": "Invalid JSON",
  "detail": "..."
}

字段类型错误

{
  "status": "error",
  "message": "Invalid field type",
  "detail": "..."
}

4.8 前端调用示例

await fetch(`${API_BASE}/config/runway/warning_zone_radius/aircraft`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ value: 300 })
});

5. 接口三：跑道区域航空器告警区半径

5.1 接口地址

POST /config/runway/alert_zone_radius/aircraft

5.2 用途

前端运行时修改跑道区域的“航空器告警区半径”。

5.3 请求体

{ "value": 200 }

5.4 成功响应

{
  "status": "success",
  "area": "runway",
  "field": "alert_zone_radius.aircraft",
  "old": 150.0,
  "new": 200.0
}

5.5 前端调用示例

await fetch(`${API_BASE}/config/runway/alert_zone_radius/aircraft`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ value: 200 })
});

5.6 说明

该接口的请求规则、错误规则与“预警区半径”接口一致，唯一差异是：

  • 路径不同
  • 成功响应中的 field 固定为 alert_zone_radius.aircraft

6. 接口四：冲突解除距离阈值

6.1 接口地址

POST /config/collision/diverging_release_distance

6.2 用途

前端运行时修改“冲突解除距离阈值”。

6.3 请求体

{ "value": 50 }

6.4 成功响应

{
  "status": "success",
  "area": "collision",
  "field": "collision.diverging_release_distance",
  "old": 40.0,
  "new": 50.0
}

6.5 前端调用示例

await fetch(`${API_BASE}/config/collision/diverging_release_distance`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ value: 50 })
});

6.6 说明

该接口的请求规则、错误规则与前两个配置接口一致，唯一差异是：

  • 路径不同
  • 成功响应中的：
    • area 固定为 collision
    • field 固定为 collision.diverging_release_distance

7. 推荐前端封装

7.1 通用 POST JSON 请求

async function postJson<T>(url: string, body: unknown): Promise<T> {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });

  const data = await response.json();

  if (!response.ok) {
    throw data;
  }

  return data as T;
}

7.2 类型定义

type VehicleType = 'WUREN' | 'TEQIN' | 'HANGKONG' | 'PUTONG' | 'JIUYUAN';

interface VehicleRegistryItem {
  vehicleID: string;
  vehicleType: VehicleType;
}

interface VehicleRegistryResponse {
  status: 'success';
  updatedAt: number;
  updated: number;
  controllableCount: number;
  typesCount: Record<string, number>;
  controllableVehicleIDs: string[];
}

interface ConfigUpdateResponse {
  status: 'success';
  area: string;
  field: string;
  old: number;
  new: number;
}

interface ErrorResponse {
  status: 'error';
  message: string;
  detail?: string;
  errors?: string[];
}

7.3 接口封装示例

export async function syncVehicleRegistry(items: VehicleRegistryItem[]) {
  return postJson<VehicleRegistryResponse>(`${API_BASE}/api/VehicleRegistry`, items);
}

export async function updateRunwayWarningRadius(value: number) {
  return postJson<ConfigUpdateResponse>(
    `${API_BASE}/config/runway/warning_zone_radius/aircraft`,
    { value }
  );
}

export async function updateRunwayAlertRadius(value: number) {
  return postJson<ConfigUpdateResponse>(
    `${API_BASE}/config/runway/alert_zone_radius/aircraft`,
    { value }
  );
}

export async function updateDivergingReleaseDistance(value: number) {
  return postJson<ConfigUpdateResponse>(
    `${API_BASE}/config/collision/diverging_release_distance`,
    { value }
  );
}

8. 前端联调注意事项

8.1 VehicleRegistry

  • 请求体必须是数组
  • vehicleID 不能为空字符串
  • vehicleType 必须严格使用大写枚举值
  • 该接口是“增量更新”，未传对象不会被后端自动删除

8.2 配置接口

  • value 必须是 number
  • 不要传字符串，例如 "300" 是错误的
  • 必须大于 0

8.3 跨域问题

  • 当前后端未配置 CORS
  • 如果前端页面和后端接口不是同域同端口，浏览器可能拦截
  • 如出现跨域报错，需要后端后续补 CORS 配置

8.4 生效方式

  • 这 3 个配置接口修改后立即在当前服务进程内生效
  • 服务重启后恢复默认值，不会持久化

9. 联调建议流程

9.1 第一步：先调对象注册接口

确认前端能成功将当前关注对象同步给后端。

9.2 第二步：再调配置接口

确认预警半径、告警半径、冲突解除距离可运行时修改。

9.3 第三步：观察业务联动

重点观察：

  • 碰撞检测结果是否按新对象范围生效
  • 跑道区域预警/告警范围是否按新阈值变化
  • 冲突解除逻辑后续接入时是否读取当前运行时配置

10. 最小联调示例

async function initPlatformObjects() {
  await syncVehicleRegistry([
    { vehicleID: 'QN001', vehicleType: 'WUREN' },
    { vehicleID: 'TQ001', vehicleType: 'TEQIN' },
    { vehicleID: 'AC001', vehicleType: 'HANGKONG' }
  ]);
}

async function updateRuntimeConfig() {
  await updateRunwayWarningRadius(300);
  await updateRunwayAlertRadius(200);
  await updateDivergingReleaseDistance(50);
}

11. 接口清单汇总

接口 方法 用途
/api/VehicleRegistry POST 同步当前关心对象及类型
/config/runway/warning_zone_radius/aircraft POST 修改跑道区域航空器预警区半径
/config/runway/alert_zone_radius/aircraft POST 修改跑道区域航空器告警区半径
/config/collision/diverging_release_distance POST 修改冲突解除距离阈值