# Mock 服务设计与使用说明

## 1. 概述

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

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

## 2. 移动物体配置

### 2.1 航空器配置

```python
{
    "flightNo": "AC001",  # 航班号
    "latitude": 36.362647780875804,  # 纬度
    "longitude": 120.088303,  # 经度
    "direction": {  # 使用方向向量
        "lat": initial_target_lat,
        "lon": initial_target_lon
    },
    "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
}
```

### 2.3 关键坐标点

- T1 (120.0868853, 36.35496367): 无人车1起点
- T2 (120.08502054, 36.35448347): 冲突点1，西路口
- T3 (120.08341044, 36.35406879): 特勤车终点
- T4 (120.08558121, 36.35305878): 无人车1终点/无人车2起点/特勤车起点
- T5 (120.08400957, 36.35265197)
- T6 (120.08649105, 36.35074527): 冲突点2，东路口
- T7 (120.08562915, 36.35052372): 航空器1终点
- T8 (120.08676664, 36.35004529): 无人车2终点
- T9 (120.08520616, 36.34964473)
- T10 (120.08710569, 36.34917893)
- T11 (120.0873865, 36.3509885): 航空器1终点
- T12 (120.08603613, 36.35190217): QN002新起点（距T6路口150米）

## 3. 运动模式

### 3.1 航空器运动

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

### 3.2 无人车运动

- QN001：
  1. T1 -> T2（西路口）
  2. T2 -> T4
  3. 到达T4后返回T1

- QN002：
  1. T12 -> T8
  2. 到达T8后返回T12

- TQ001（特勤车）：
  1. T4 -> T2（西路口）
  2. T2 -> T3
  3. 到达T3后返回T4

### 3.3 配置参数

- 距离阈值：
  - 300米：DIST_300M
  - 200米：DIST_200M
  - 150米：DIST_150M
  - 100米：DIST_100M
  - 50米：DIST_50M

- 时间配置：
  - 返回等待时间：10秒
  - 位置更新间隔：1秒
  - 红绿灯切换间隔：10秒

- 速度配置：
  - 默认车辆速度：18.0 km/h
  - 紧急制动减速度：80%/更新
  - 正常制动减速度：20%/更新

## 4. HTTP API 接口

### 4.1 航空器位置查询接口

```http
GET /api/getCurrentFlightPositions
```

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

```json
[
    {
        "flightNo": "AC001",
        "latitude": 36.362647780875804,
        "longitude": 120.088303,
        "direction": {
            "lat": 0.707,
            "lon": 0.707
        },
        "speed": 36.0,
        "time": 1733741411167
    }
]
```

### 4.2 车辆位置查询接口

```http
GET /api/getCurrentVehiclePositions
```

返回所有车辆的当前位置信息：

```json
[
    {
        "vehicleNo": "QN001",
        "latitude": 36.362448155990975,
        "longitude": 120.08844920958369,
        "direction": -1,
        "speed": 18.0,
        "time": 1733741411168,
        "phase": 0
    }
]
```

### 4.3 红绿灯状态查询接口

```http
GET /api/getTrafficLightSignals
```

返回所有红绿灯的当前状态：

```json
[
    {
        "id": "TL001",
        "state": 1,
        "timestamp": 1733741411167,
        "intersection": "INT001",
        "position": {
            "latitude": 36.35448347,
            "longitude": 120.08502054
        }
    }
]
```

### 4.4 车辆控制接口

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

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

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

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

### 5.1 优先级规则

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

### 5.2 状态转换

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

2. 收到红灯指令 (RED)：
   - 红灯：停止
   - 绿灯：如果没有更高优先级指令（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 错误