2ndFn

外观

电梯交通量仿真分析4

约 1853 字大约 6 分钟

coding

2025-07-28

4. 接口设计

4.1 RESTful API设计规范

本系统遵循RESTful设计原则，采用JSON作为数据交换格式，使用标准HTTP状态码表示操作结果。所有API均以/api/v1为前缀，确保版本兼容性。

通用响应结构

{
  "status": "SUCCESS|ERROR|VALIDATION_ERROR",
  "code": "HTTP状态码",
  "message": "操作结果描述",
  "data": {
    // 具体业务数据
  },
  "timestamp": "ISO 8601格式的时间戳"
}

错误处理

  • 400 Bad Request: 请求参数验证失败
  • 401 Unauthorized: 未授权访问
  • 404 Not Found: 资源不存在
  • 422 Unprocessable Entity: 业务逻辑验证失败
  • 500 Internal Server Error: 服务器内部错误

4.2 核心API接口设计

4.2.1 仿真执行API

端点: POST /api/v1/simulate

功能: 执行电梯交通仿真，返回关键指标和仿真ID

请求体:

{
  "buildingConfig": {
    "name": "办公大楼A",
    "totalFloors": 30,
    "floorHeight": 4.0,
    "buildingType": "OFFICE",
    "floors": [
      {
        "floorNumber": 1,
        "usage": "LOBBY",
        "population": 0,
        "timePeriods": {
          "MORNING_PEAK": {
            "incomingTrafficRatio": 0.8,
            "outgoingTrafficRatio": 0.0,
            "interfloorTrafficRatio": 0.2,
            "batchProfile": {
              "batchProbability": 0.7,
              "batchSizeDistribution": [
                {"batchSize": 1, "probability": 0.3},
                {"batchSize": 2, "probability": 0.4},
                {"batchSize": 3, "probability": 0.2},
                {"batchSize": 4, "probability": 0.1}
              ],
              "interArrivalMean": 5.0,
              "interArrivalStdDev": 2.0
            }
          }
        }
      }
    ]
  },
  "elevatorGroups": [
    {
      "controlType": "DESTINATION_CONTROL",
      "elevators": [
        {
          "capacity": 16,
          "ratedSpeed": 3.0,
          "acceleration": 1.0,
          "deceleration": 1.0,
          "doorWidth": 1.0,
          "standbyFloor": 1,
          "serviceFloors": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30]
        }
      ]
    }
  ],
  "simulationConfig": {
    "duration": 3600,
    "timeSlice": 5,
    "startTime": "08:00",
    "endTime": "09:00",
    "odMatrixEstimationMethod": "BILS"
  }
}

成功响应示例:

{
  "status": "SUCCESS",
  "code": 200,
  "message": "Simulation started successfully",
  "data": {
    "simulationId": "sim-7d8e9f0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
    "startTime": "2023-08-01T08:00:00Z",
    "estimatedCompletionTime": "2023-08-01T08:00:15Z",
    "keyMetrics": {
      "averageWaitingTime": 23.5,
      "maxWaitingTime": 65.2,
      "averageTravelTime": 45.8,
      "handlingCapacity": 18.3
    }
  },
  "timestamp": "2023-08-01T07:59:45Z"
}

验证错误响应示例:

{
  "status": "VALIDATION_ERROR",
  "code": 400,
  "message": "Invalid simulation configuration",
  "data": {
    "errors": [
      {
        "field": "elevatorGroups[0].elevators[0].serviceFloors",
        "message": "Service floors must include standby floor (1)"
      }
    ]
  },
  "timestamp": "2023-08-01T07:59:45Z"
}

4.2.2 仿真状态查询API

端点: GET /api/v1/simulations/{id}

功能: 查询仿真状态和进度

成功响应示例:

{
  "status": "SUCCESS",
  "code": 200,
  "message": "Simulation status retrieved successfully",
  "data": {
    "simulationId": "sim-7d8e9f0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
    "status": "RUNNING|COMPLETED|FAILED",
    "progress": 75.5,
    "startTime": "2023-08-01T08:00:00Z",
    "endTime": null,
    "duration": 3600,
    "keyMetrics": {
      "averageWaitingTime": 23.5,
      "maxWaitingTime": 65.2,
      "averageTravelTime": 45.8,
      "handlingCapacity": 18.3
    }
  },
  "timestamp": "2023-08-01T08:00:45Z"
}

4.2.3 时间切片数据API

端点: GET /api/v1/simulations/{id}/timeline

功能: 按时间切片获取电梯和乘客数据，用于前端动画展示

查询参数:

  • fromTime: 开始时间(秒)，默认为0
  • toTime: 结束时间(秒)，默认为仿真总时长
  • timeSlice: 时间切片大小(秒)，默认为5

成功响应示例:

{
  "status": "SUCCESS",
  "code": 200,
  "message": "Timeline data retrieved successfully",
  "data": {
    "simulationId": "sim-7d8e9f0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
    "timeSlice": 5,
    "timeline": [
      {
        "time": 0,
        "elevators": [
          {
            "id": "elevator-1",
            "position": 0.0,
            "floor": 1,
            "direction": "STOPPED",
            "doorOpen": false,
            "passengerCount": 0,
            "registeredStops": []
          }
        ],
        "passengerEvents": []
      },
      {
        "time": 5,
        "elevators": [
          {
            "id": "elevator-1",
            "position": 4.0,
            "floor": 2,
            "direction": "UP",
            "doorOpen": false,
            "passengerCount": 3,
            "registeredStops": [5, 8, 10]
          }
        ],
        "passengerEvents": [
          {
            "type": "BOARDING",
            "passengerId": "P-123",
            "elevatorId": "elevator-1",
            "floor": 2,
            "timestamp": 5
          }
        ]
      }
    ]
  },
  "timestamp": "2023-08-01T08:05:30Z"
}

关键实现细节:

  • 时间切片数据按配置的时间间隔(1秒/5秒/30秒)生成
  • 电梯状态包含精确位置(米)、当前楼层、运行方向、门状态等
  • 乘客事件包含上车、下车、等待等关键事件
  • 数据结构优化，便于前端动画渲染

4.2.4 仿真结果API

端点: GET /api/v1/simulations/{id}/results

功能: 获取完整仿真结果，包括所有性能指标

成功响应示例:

{
  "status": "SUCCESS",
  "code": 200,
  "message": "Simulation results retrieved successfully",
  "data": {
    "simulationId": "sim-7d8e9f0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
    "building": {
      "name": "办公大楼A",
      "totalFloors": 30,
      "floorHeight": 4.0,
      "buildingType": "OFFICE"
    },
    "waitingTimeMetrics": {
      "overall": {
        "average": 23.5,
        "max": 65.2,
        "min": 5.3,
        "stdDev": 12.4,
        "percentiles": [5.3, 12.1, 16.7, 20.3, 23.5, 26.8, 31.2, 38.5, 45.6, 65.2]
      },
      "byFloor": {
        "1": {
          "average": 18.2,
          "max": 45.3,
          "min": 5.3,
          "stdDev": 8.7,
          "percentiles": [5.3, 12.1, 14.7, 16.3, 18.2, 20.8, 24.2, 30.5, 36.6, 45.3]
        },
        "2": {
          "average": 25.7,
          "max": 65.2,
          "min": 8.3,
          "stdDev": 14.2,
          "percentiles": [8.3, 15.1, 19.7, 23.3, 25.7, 29.8, 34.2, 41.5, 48.6, 65.2]
        }
      },
      "byTimePeriod": {
        "MORNING_PEAK": {
          "average": 28.3,
          "max": 65.2,
          "min": 7.3,
          "stdDev": 15.2
        },
        "NORMAL": {
          "average": 15.2,
          "max": 35.7,
          "min": 5.3,
          "stdDev": 6.8
        }
      }
    },
    "travelTimeMetrics": {
      "overall": {
        "average": 45.8,
        "max": 98.5,
        "min": 15.2,
        "stdDev": 20.3,
        "percentiles": [15.2, 28.1, 34.7, 40.3, 45.8, 51.8, 58.2, 67.5, 76.6, 98.5]
      }
    },
    "systemPerformance": {
      "handlingCapacity": 18.3,
      "elevatorUtilization": {
        "elevator-1": 78.5,
        "elevator-2": 65.2,
        "elevator-3": 82.7
      },
      "averageStopsPerTrip": 3.2,
      "energyConsumption": 125.7
    }
  },
  "timestamp": "2023-08-01T08:10:15Z"
}

关键指标说明:

  • 等待时间指标:

    • 最坏/平均等待时间及明细(按楼层、时间段)
    • 乘客等待时间分布(百分位数)
    • 高峰时段等待时间分析

  • 运输时间指标:

    • 最坏/平均运输时间及明细
    • 乘客运输时间分布
    • 门到门时间分析

  • 系统性能指标:

    • 5分钟输送能力(%)
    • 电梯利用率
    • 平均停站次数
    • 能耗估算

4.2.5 PDF报告生成API

端点: GET /api/v1/simulations/{id}/report

功能: 生成PDF格式的仿真报告

查询参数:

  • reportType: 报告类型(BASIC, DETAILED, COMPARATIVE)，默认为DETAILED
  • includeCharts: 是否包含图表(true/false)，默认为true

成功响应:

  • HTTP 200 OK
  • Content-Type: application/pdf
  • 响应体为PDF文件二进制数据

报告内容结构:

  1. 执行摘要:

    • 仿真基本信息
    • 关键性能指标概览
    • 主要发现

  2. 详细性能分析:

    • 等待时间分布图表
    • 运输时间分布图表
    • 电梯利用率热力图
    • 5分钟输送能力分析

  3. 控制策略对比(仅当比较多种策略时):

    • 不同控制方式的性能对比
    • 统计显著性分析
    • 推荐策略

  4. 优化建议:

    • 电梯配置优化建议
    • 控制策略改进建议
    • 建筑布局优化建议

4.2.6 OD矩阵估计API

端点: POST /api/v1/od-matrix/estimate

功能: 估计电梯行程的OD矩阵

请求体:

{
  "elevatorTrips": [
    {
      "tripId": "trip-1",
      "elevatorId": "elevator-1",
      "startTime": "2023-08-01T08:00:00Z",
      "endTime": "2023-08-01T08:01:30Z",
      "stops": [
        {"floor": 1, "arrivalTime": "2023-08-01T08:00:00Z", "departureTime": "2023-08-01T08:00:10Z", "boardingCount": 5, "alightingCount": 0},
        {"floor": 5, "arrivalTime": "2023-08-01T08:00:20Z", "departureTime": "2023-08-01T08:00:30Z", "boardingCount": 2, "alightingCount": 3},
        {"floor": 10, "arrivalTime": "2023-08-01T08:00:45Z", "departureTime": "2023-08-01T08:00:55Z", "boardingCount": 0, "alightingCount": 4}
      ]
    }
  ],
  "building": {
    "totalFloors": 30
  },
  "estimationMethod": "BILS",
  "withRandomization": true
}

成功响应示例:

{
  "status": "SUCCESS",
  "code": 200,
  "message": "OD matrix estimated successfully",
  "data": {
    "odMatrix": [
      {"origin": 1, "destination": 5, "passengerCount": 3, "probability": 0.15},
      {"origin": 1, "destination": 10, "passengerCount": 2, "probability": 0.10},
      {"origin": 5, "destination": 10, "passengerCount": 1, "probability": 0.05},
      {"origin": 5, "destination": 1, "passengerCount": 3, "probability": 0.15}
    ],
    "validation": {
      "isValid": true,
      "issues": []
    },
    "computationTime": 152,
    "isRoundedSolution": false
  },
  "timestamp": "2023-08-01T08:15:30Z"
}

关键实现细节:

  • 实现PDF中描述的LP、BILS、CP三种OD矩阵估计方法
  • 支持随机化搜索以提高统计质量
  • 提供详细的验证结果，确保OD矩阵满足流量守恒原则
  • 返回计算时间和解的类型信息

4.3 API安全设计

4.3.1 认证与授权

  • 使用JWT(JSON Web Token)进行身份验证
  • 基于角色的访问控制(RBAC):
    • ADMIN: 可执行所有操作
    • ENGINEER: 可执行仿真和查看结果
    • VIEWER: 仅可查看结果

4.3.2 速率限制

  • 免费用户: 10请求/分钟
  • 专业用户: 100请求/分钟
  • 企业用户: 无限制

4.3.3 数据验证

  • 所有输入参数进行严格验证
  • 业务规则验证(如电梯服务楼层必须包含基准层)
  • 防止无效的仿真配置

4.3.4 审计日志

  • 记录所有API调用
  • 包含用户、时间、操作和结果
  • 用于安全审计和问题排查

4.4 API性能优化

4.4.1 缓存策略

  • 仿真结果缓存: 24小时
  • OD矩阵估计结果缓存: 1小时
  • 使用Redis作为缓存层

4.4.2 异步处理

  • 长时间仿真任务使用异步处理
  • 客户端通过Websocket接收进度更新
  • 提供任务取消功能

4.4.3 数据压缩

  • 大型响应数据使用GZIP压缩
  • 时间切片数据使用二进制格式选项
  • 提供数据采样选项

4.4.4 分页与过滤

  • 大型结果集支持分页
  • 时间切片数据支持时间范围过滤
  • 结果指标支持按楼层、时间段过滤