CollisionAvoidance/docs/mock_server.md

# Mock 服务设计与使用说明

## 1. 概述

Mock 服务用于模拟机场场面的移动物体（航空器和车辆），提供位置更新和响应控制指令的功能。服务包含两个主要部分：

- HTTP API 服务：提供位置查询和车辆控制接口
- 位置更新模拟：定期更新各个移动物体的位置

## 2. 移动物体配置

### 2.1 航空器配置

```python
{
    "flightNo": "AC001",  # 航班号
    "latitude": 36.362647780875804,  # 纬度
    "longitude": 120.088303,  # 经度
    "direction": 1,  # 1表示向北
    "speed": 50.0  # 滑行速度 50km/h
}
```

### 2.2 车辆配置

```python
{
    "vehicleNo": "QN001",  # 无人车1（西路口）
    "latitude": WEST_INTERSECTION["latitude"],  # 纬度
    "longitude": WEST_INTERSECTION["longitude"],  # 经度
    "direction": 1,  # 1表示向东，-1表示向西
    "speed": 36.0  # 行驶速度 36km/h
}
```

## 3. 运动模式

### 3.1 航空器运动

- 沿跑道南北方向移动
- 到达边界时自动调头
- 保持恒定速度 50km/h

### 3.2 无人车运动

- QN001：在西路口东西向往返，范围 50 米
- QN002：在东路口东西方向往返，范围 100-150 米
- TQ001：先东西移动，到达指定位置后转向南北移动，然后返回

## 4. HTTP API 接口

### 4.1 位置查询接口

```http
GET /api/position
```

返回所有移动物体的当前位置信息：

```json
{
    "aircraft": [
        {
            "flightNo": "AC001",
            "latitude": 36.362647780875804,
            "longitude": 120.088303,
            "heading": 0.0,
            "speed": 13.89,
            "timestamp": 1733741411167
        }
    ],
    "vehicles": [
        {
            "vehicleNo": "QN001",
            "latitude": 36.362448155990975,
            "longitude": 120.08844920958369,
            "heading": 90.0,
            "speed": 10.0,
            "timestamp": 1733741411168
        }
    ]
}
```

### 4.2 车辆控制接口

```http
POST /api/vehicle/command
Content-Type: application/json
```

请求格式：

```json
{
    "vehicleId": "QN001",
    "type": "SIGNAL",           // SIGNAL, ALERT, WARNING, RESUME
    "reason": "TRAFFIC_LIGHT",  // TRAFFIC_LIGHT, AIRCRAFT_CROSSING, SPECIAL_VEHICLE, AIRCRAFT_PUSH, RESUME_TRAFFIC
    "timestamp": 1733741411167,
    "signalState": "RED",       // 可选，仅当 type 为 SIGNAL 时需要
    "targetPosition": {         // 可选
        "x": 100.0,
        "y": 200.0
    },
    "speed": 0.0,              // 可选
    "distance": 0.0            // 可选
}
```

响应格式：

```json
{
    "status": "ok",            // ok 或 error
    "message": "Command executed successfully"
}
```

## 5. 指令优先级

车辆控制指令按以下优先级处理：

1. ALERT (5)：告警指令，最高优先级
   - 用于紧急情况，如碰撞风险
   - 可以覆盖所有其他指令
   - 收到后车辆立即停止

2. SIGNAL (4)：红绿灯指令，次高优先级
   - 用于红绿灯控制
   - 可以覆盖预警、绿灯和恢复指令
   - 红灯时车辆停止，绿灯时可能恢复（取决于是否有更高优先级指令）

3. WARNING (3)：预警指令，中等优先级
   - 用于提前预警可能的风险
   - 可以覆盖绿灯和恢复指令
   - 收到后车辆减速或停止

4. GREEN (2)：绿灯状态
   - 系统内部状态，不是外部指令
   - 可以覆盖恢复指令
   - 只有在没有更高优先级指令时才生效

5. RESUME (1)：恢复指令，最低优先级
   - 用于恢复正常行驶
   - 不能覆盖其他指令
   - 只有在没有任何其他指令时才生效

### 5.1 优先级规则

1. 高优先级指令可以覆盖低优先级指令
2. 相同优先级的新指令可以覆盖旧指令
3. 低优先级指令不能覆盖高优先级指令
4. 恢复行驶需要满足两个条件：
   - 收到 RESUME 指令
   - 没有任何更高优先级的指令

### 5.2 状态转换

1. 收到告警指令 (ALERT)：
   - 立即停止
   - 忽略所有低优先级指令
   - 只能通过 RESUME 指令恢复（且无其他高优先级指令）

2. 收到红绿灯指令 (SIGNAL)：
   - 红灯：停止
   - 绿灯：如果没有更高优先级指令（ALERT）则恢复行驶

3. 收到预警指令 (WARNING)：
   - 减速或停止
   - 可被告警或红灯指令覆盖
   - 可通过绿灯或恢复指令解除（如无更高优先级指令）

4. 遇到绿灯 (GREEN)：
   - 如果没有 ALERT、SIGNAL 或 WARNING 指令，则恢复行驶
   - 否则保持当前状态

5. 收到恢复指令 (RESUME)：
   - 检查是否有任何更高优先级指令
   - 如果没有，则恢复正常行驶速度
   - 如果有，则保持当前状态

### 5.3 使用示例

1. 告警指令覆盖其他指令：

```json
{
    "vehicleId": "QN001",
    "type": "ALERT",
    "reason": "COLLISION_RISK",
    "timestamp": 1733741411167
}
```

2. 红灯指令（但不会覆盖告警）：

```json
{
    "vehicleId": "QN001",
    "type": "SIGNAL",
    "reason": "TRAFFIC_LIGHT",
    "signalState": "RED",
    "timestamp": 1733741411167
}
```

3. 预警指令（可被告警和红灯覆盖）：

```json
{
    "vehicleId": "QN001",
    "type": "WARNING",
    "reason": "APPROACHING_INTERSECTION",
    "timestamp": 1733741411167
}
```

4. 恢复指令（需要无更高优先级指令）：

```json
{
    "vehicleId": "QN001",
    "type": "RESUME",
    "reason": "RESUME_TRAFFIC",
    "timestamp": 1733741411167
}
```

## 6. 使用示例

### 6.1 发送红绿灯指令

```bash
curl -X POST http://localhost:8081/api/vehicle/command \
  -H "Content-Type: application/json" \
  -d '{
    "vehicleId": "QN001",
    "type": "SIGNAL",
    "reason": "TRAFFIC_LIGHT",
    "timestamp": 1733741411167,
    "signalState": "RED"
  }'
```

### 6.2 发送碰撞预警指令

```bash
curl -X POST http://localhost:8081/api/vehicle/command \
  -H "Content-Type: application/json" \
  -d '{
    "vehicleId": "QN001",
    "type": "WARNING",
    "reason": "AIRCRAFT_CROSSING",
    "timestamp": 1733741411167,
    "distance": 25.5
  }'
```

### 6.3 发送恢复指令

```bash
curl -X POST http://localhost:8081/api/vehicle/command \
  -H "Content-Type: application/json" \
  -d '{
    "vehicleId": "QN001",
    "type": "RESUME",
    "reason": "RESUME_TRAFFIC",
    "timestamp": 1733741411167
  }'
```

## 7. 启动服务

```bash
# 安装依赖
pip install flask

# 启动服务
python tools/mock_server.py
```

服务默认监听在：

- HTTP 服务：<http://localhost:8081>

## 8. 注意事项

1. 位置更新
   - 位置更新频率：1秒一次
   - 坐标系统：WGS84
   - 速度单位：km/h（内部计算使用 m/s）

2. 车辆控制
   - 车辆收到停止指令后会立即停止位置更新
   - 只有收到 RESUME 指令且没有更高优先级的指令时才会恢复运动
   - 每个指令都必须包含时间戳

3. 错误处理
   - 无效的车辆ID：返回 404 错误
   - 无效的指令格式：返回 400 错误
   - 服务器内部错误：返回 500 错误