# 任务清单接口设计方案 **日期**: 2025-01-10 **版本**: v1.0 **目标**: 为无人车平台Mock服务增加任务清单接口 --- ## 📋 需求背景 由无人车侧的平台（mock）提供一个单独的任务清单接口，可以返回无人车所有的可执行任务。然后，我们的应用请求这个接口，选择某个任务，下发给无人车去执行。 **核心概念**: 任务池/任务库 - 预定义的可执行任务模板清单 --- ## 🎯 接口设计 ### 接口信息 - **方法**: `GET /api/v1/missions/available` - **认证**: Bearer Token (JWT) - **响应**: `application/json; charset=utf-8` - **功能**: 返回无人车平台的所有可执行任务清单 ### 查询参数 | 参数名 | 类型 | 必填 | 描述 | 示例 | |--------|------|------|------|------| | missionType | string | 否 | 任务类型筛选 | PATROL_TRANSPORT, CARGO_TRANSPORT | | priority | integer | 否 | 优先级筛选 | 1-5 | | minBatteryLevel | integer | 否 | 最低电量要求 | 30 | | limit | integer | 否 | 返回数量限制 | 10 | | offset | integer | 否 | 分页偏移量 | 0 | ### 请求头 | Header | 必填 | 示例 | 说明 | |--------|------|------|------| | Authorization | 是 | Bearer eyJhbGciOi... | JWT 鉴权令牌 | | Content-Type | 是 | application/json | 固定为 JSON | | Accept | 否 | application/json | 建议显式声明 | --- ## 📦 数据结构设计 ### 任务对象 (Mission) ```json { "missionId": "MISSION_TEMPLATE_001", "missionName": "T1航站楼巡逻", "missionType": "PATROL_TRANSPORT", "description": "T1航站楼周边区域巡逻任务", "priority": 3, "estimatedDuration": 1800000, "totalMileage": 2500.0, "waypoints": [ { "waypointId": "WP_001", "latitude": 36.354068, "longitude": 120.083410, "waypointType": "START", "name": "T1航站楼东侧", "altitude": 10.5, "estimatedArrivalTime": null }, { "waypointId": "WP_002", "latitude": 36.355123, "longitude": 120.084567, "waypointType": "CHECKPOINT", "name": "巡逻检查点A", "altitude": 11.2, "estimatedArrivalTime": null }, { "waypointId": "WP_003", "latitude": 36.356789, "longitude": 120.085234, "waypointType": "END", "name": "T1航站楼北侧", "altitude": 10.8, "estimatedArrivalTime": null } ], "requirements": { "vehicleType": "UNMANNED", "minBatteryLevel": 30, "requiredSensors": ["GPS", "LIDAR", "CAMERA"], "weatherConditions": "CLEAR | LIGHT_RAIN" }, "metadata": { "createdTime": 1736175000000, "createdBy": "system", "tags": ["patrol", "security", "routine"], "zone": "TERMINAL_1" } } ``` ### 字段说明 #### 基础信息 - `missionId` (string): 任务唯一标识 - `missionName` (string): 任务名称 - `missionType` (string): 任务类型 - `description` (string): 任务描述 - `priority` (integer): 优先级 1-5，数字越大优先级越高 #### 时间和里程 - `estimatedDuration` (integer): 预计执行时长（毫秒） - `totalMileage` (number): 预计总里程（米） #### 路径点 (waypoints) - `waypointId` (string): 路径点ID - `latitude` (number): 纬度 (WGS84) - `longitude` (number): 经度 (WGS84) - `waypointType` (string): 路径点类型 - `START`: 起点 - `CHECKPOINT`: 检查点 - `WAYPOINT`: 普通路径点 - `END`: 终点 - `name` (string): 路径点名称 - `altitude` (number, 可选): 海拔高度（米） - `estimatedArrivalTime` (integer, 可选): 预计到达时间（毫秒，UTC） #### 任务要求 (requirements) - `vehicleType` (string): 车辆类型要求 - `minBatteryLevel` (integer): 最低电量要求 (0-100) - `requiredSensors` (array): 必需的传感器列表 - `weatherConditions` (string): 可执行天气条件 #### 元数据 (metadata) - `createdTime` (integer): 创建时间（毫秒，UTC） - `createdBy` (string): 创建者 - `tags` (array): 标签列表 - `zone` (string): 区域标识 --- ## 📡 响应格式 ### 成功响应 (200 OK) ```json { "code": 200, "message": "success", "timestamp": 1736175610000, "data": { "total": 5, "missions": [ { "missionId": "MISSION_TEMPLATE_001", "missionName": "T1航站楼巡逻", "missionType": "PATROL_TRANSPORT", "description": "T1航站楼周边区域巡逻任务", "priority": 3, "estimatedDuration": 1800000, "totalMileage": 2500.0, "waypoints": [...], "requirements": {...}, "metadata": {...} }, { "missionId": "MISSION_TEMPLATE_002", "missionName": "货物运输-仓库A到登机口B3", "missionType": "CARGO_TRANSPORT", "priority": 4, "estimatedDuration": 900000, "totalMileage": 1200.0, "waypoints": [...], "requirements": {...}, "metadata": {...} } ] } } ``` ### 错误响应 #### 401 未授权 ```json { "code": 401, "message": "Unauthorized: Invalid or expired token", "timestamp": 1736175610000, "data": null } ``` #### 400 参数错误 ```json { "code": 400, "message": "Invalid parameter: missionType must be one of [PATROL_TRANSPORT, CARGO_TRANSPORT, PASSENGER_TRANSPORT]", "timestamp": 1736175610000, "data": null } ``` --- ## 🗂️ 任务类型定义 ### 标准任务类型 | 任务类型 | 代码 | 描述 | |---------|------|------| | 巡逻运输 | PATROL_TRANSPORT | 定期巡逻和安全检查 | | 货物运输 | CARGO_TRANSPORT | 货物运输和配送 | | 客运服务 | PASSENGER_TRANSPORT | 旅客运输服务 | | 应急响应 | EMERGENCY_RESPONSE | 应急事件响应 | | 维护检查 | MAINTENANCE_INSPECTION | 设施维护和检查 | | 清洁作业 | CLEANING_OPERATION | 清洁和环境维护 | --- ## 🔧 实现方案 ### 1. 数据存储结构 在 `mock_unmanned_vehicle.py` 中定义任务池： ```python # 可执行任务清单（任务模板库） AVAILABLE_MISSIONS = [ { "missionId": "MISSION_TEMPLATE_001", "missionName": "T1航站楼巡逻", "missionType": "PATROL_TRANSPORT", "description": "T1航站楼周边区域巡逻任务", "priority": 3, "estimatedDuration": 1800000, "totalMileage": 2500.0, "waypoints": [ { "waypointId": "WP_T1_001", "latitude": 36.354068, "longitude": 120.083410, "waypointType": "START", "name": "T1航站楼东侧", "altitude": 10.5 }, { "waypointId": "WP_T1_002", "latitude": 36.355123, "longitude": 120.084567, "waypointType": "CHECKPOINT", "name": "巡逻检查点A", "altitude": 11.2 }, { "waypointId": "WP_T1_003", "latitude": 36.356789, "longitude": 120.085234, "waypointType": "END", "name": "T1航站楼北侧", "altitude": 10.8 } ], "requirements": { "vehicleType": "UNMANNED", "minBatteryLevel": 30, "requiredSensors": ["GPS", "LIDAR", "CAMERA"], "weatherConditions": "CLEAR | LIGHT_RAIN" }, "metadata": { "createdTime": 1736175000000, "createdBy": "system", "tags": ["patrol", "security", "routine"], "zone": "TERMINAL_1" } }, { "missionId": "MISSION_TEMPLATE_002", "missionName": "货物运输-仓库A到登机口B3", "missionType": "CARGO_TRANSPORT", "description": "从货物仓库A运输至B3登机口", "priority": 4, "estimatedDuration": 900000, "totalMileage": 1200.0, "waypoints": [ { "waypointId": "WP_CARGO_001", "latitude": 36.352000, "longitude": 120.082000, "waypointType": "START", "name": "货物仓库A", "altitude": 9.5 }, { "waypointId": "WP_CARGO_002", "latitude": 36.353500, "longitude": 120.083500, "waypointType": "WAYPOINT", "name": "运输通道中点", "altitude": 10.0 }, { "waypointId": "WP_CARGO_003", "latitude": 36.355000, "longitude": 120.085000, "waypointType": "END", "name": "B3登机口", "altitude": 10.2 } ], "requirements": { "vehicleType": "UNMANNED", "minBatteryLevel": 25, "requiredSensors": ["GPS", "CAMERA"], "weatherConditions": "CLEAR | LIGHT_RAIN | CLOUDY", "maxCargoWeight": 500 }, "metadata": { "createdTime": 1736175100000, "createdBy": "system", "tags": ["cargo", "logistics", "high-priority"], "zone": "CARGO_AREA" } }, { "missionId": "MISSION_TEMPLATE_003", "missionName": "T2航站楼接驳", "missionType": "PASSENGER_TRANSPORT", "description": "T2航站楼旅客接驳服务", "priority": 5, "estimatedDuration": 600000, "totalMileage": 800.0, "waypoints": [ { "waypointId": "WP_T2_001", "latitude": 36.358000, "longitude": 120.086000, "waypointType": "START", "name": "T2到达大厅", "altitude": 11.0 }, { "waypointId": "WP_T2_002", "latitude": 36.359000, "longitude": 120.087000, "waypointType": "END", "name": "T2出发大厅", "altitude": 11.5 } ], "requirements": { "vehicleType": "UNMANNED", "minBatteryLevel": 40, "requiredSensors": ["GPS", "LIDAR", "CAMERA", "ULTRASONIC"], "weatherConditions": "CLEAR | CLOUDY", "maxPassengerCount": 4 }, "metadata": { "createdTime": 1736175200000, "createdBy": "system", "tags": ["passenger", "shuttle", "high-priority"], "zone": "TERMINAL_2" } }, { "missionId": "MISSION_TEMPLATE_004", "missionName": "跑道周边应急巡查", "missionType": "EMERGENCY_RESPONSE", "description": "跑道周边区域应急巡查任务", "priority": 5, "estimatedDuration": 1200000, "totalMileage": 3500.0, "waypoints": [ { "waypointId": "WP_RUNWAY_001", "latitude": 36.360000, "longitude": 120.088000, "waypointType": "START", "name": "跑道17端", "altitude": 8.0 }, { "waypointId": "WP_RUNWAY_002", "latitude": 36.365000, "longitude": 120.090000, "waypointType": "CHECKPOINT", "name": "跑道中段检查点", "altitude": 8.5 }, { "waypointId": "WP_RUNWAY_003", "latitude": 36.370000, "longitude": 120.092000, "waypointType": "END", "name": "跑道35端", "altitude": 9.0 } ], "requirements": { "vehicleType": "UNMANNED", "minBatteryLevel": 50, "requiredSensors": ["GPS", "LIDAR", "CAMERA", "THERMAL"], "weatherConditions": "ANY", "emergencyLightRequired": true }, "metadata": { "createdTime": 1736175300000, "createdBy": "system", "tags": ["emergency", "runway", "critical"], "zone": "RUNWAY_AREA" } }, { "missionId": "MISSION_TEMPLATE_005", "missionName": "停机坪维护巡检", "missionType": "MAINTENANCE_INSPECTION", "description": "停机坪设施维护巡检", "priority": 2, "estimatedDuration": 2400000, "totalMileage": 4200.0, "waypoints": [ { "waypointId": "WP_APRON_001", "latitude": 36.351000, "longitude": 120.081000, "waypointType": "START", "name": "停机坪A1", "altitude": 10.0 }, { "waypointId": "WP_APRON_002", "latitude": 36.352500, "longitude": 120.082500, "waypointType": "CHECKPOINT", "name": "停机坪A5", "altitude": 10.2 }, { "waypointId": "WP_APRON_003", "latitude": 36.354000, "longitude": 120.084000, "waypointType": "CHECKPOINT", "name": "停机坪B2", "altitude": 10.5 }, { "waypointId": "WP_APRON_004", "latitude": 36.355500, "longitude": 120.085500, "waypointType": "END", "name": "停机坪B8", "altitude": 10.8 } ], "requirements": { "vehicleType": "UNMANNED", "minBatteryLevel": 35, "requiredSensors": ["GPS", "CAMERA", "INSPECTION_TOOLS"], "weatherConditions": "CLEAR | CLOUDY" }, "metadata": { "createdTime": 1736175400000, "createdBy": "system", "tags": ["maintenance", "inspection", "routine"], "zone": "APRON_AREA" } } ] # 任务类型枚举 MISSION_TYPES = { "PATROL_TRANSPORT": "巡逻运输", "CARGO_TRANSPORT": "货物运输", "PASSENGER_TRANSPORT": "客运服务", "EMERGENCY_RESPONSE": "应急响应", "MAINTENANCE_INSPECTION": "维护检查", "CLEANING_OPERATION": "清洁作业" } ``` ### 2. 接口处理函数 ```python @app.route('/api/v1/missions/available', methods=['GET', 'OPTIONS']) def get_available_missions(): """ 获取可执行任务清单 查询参数: - missionType: 任务类型筛选 - priority: 优先级筛选 - minBatteryLevel: 最低电量要求 - limit: 返回数量限制 - offset: 分页偏移量 """ # 处理 CORS 预检请求 if request.method == 'OPTIONS': return '', 200 try: # 获取查询参数 mission_type = request.args.get('missionType') priority = request.args.get('priority', type=int) min_battery = request.args.get('minBatteryLevel', type=int) limit = request.args.get('limit', type=int, default=100) offset = request.args.get('offset', type=int, default=0) # 筛选任务 filtered_missions = AVAILABLE_MISSIONS.copy() # 按任务类型筛选 if mission_type: if mission_type not in MISSION_TYPES: return jsonify({ "code": 400, "message": f"Invalid missionType. Must be one of {list(MISSION_TYPES.keys())}", "timestamp": int(time.time() * 1000), "data": None }), 400 filtered_missions = [m for m in filtered_missions if m["missionType"] == mission_type] # 按优先级筛选 if priority is not None: if priority < 1 or priority > 5: return jsonify({ "code": 400, "message": "Invalid priority. Must be between 1 and 5", "timestamp": int(time.time() * 1000), "data": None }), 400 filtered_missions = [m for m in filtered_missions if m["priority"] == priority] # 按电量要求筛选 if min_battery is not None: if min_battery < 0 or min_battery > 100: return jsonify({ "code": 400, "message": "Invalid minBatteryLevel. Must be between 0 and 100", "timestamp": int(time.time() * 1000), "data": None }), 400 filtered_missions = [ m for m in filtered_missions if m["requirements"]["minBatteryLevel"] <= min_battery ] # 分页处理 total = len(filtered_missions) paginated_missions = filtered_missions[offset:offset + limit] # 构造响应 response = { "code": 200, "message": "success", "timestamp": int(time.time() * 1000), "data": { "total": total, "limit": limit, "offset": offset, "missions": paginated_missions } } logging.info(f"返回 {len(paginated_missions)} 个可执行任务 (总数: {total})") return jsonify(response), 200 except Exception as e: logging.error(f"获取任务清单失败: {str(e)}") return jsonify({ "code": 500, "message": f"Internal server error: {str(e)}", "timestamp": int(time.time() * 1000), "data": None }), 500 ``` ### 3. CORS 配置 确保在文件中已有 CORS 配置： ```python @app.after_request def after_request(response): """添加 CORS 头""" response.headers.add('Access-Control-Allow-Origin', '*') response.headers.add('Access-Control-Allow-Headers', 'Content-Type,Authorization,Accept,X-Request-Id') response.headers.add('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE,OPTIONS') return response ``` --- ## 🧪 测试用例 ### 1. 获取所有任务 ```bash curl -X GET "http://localhost:5000/api/v1/missions/available" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \ -H "Accept: application/json" ``` ### 2. 按任务类型筛选 ```bash curl -X GET "http://localhost:5000/api/v1/missions/available?missionType=CARGO_TRANSPORT" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \ -H "Accept: application/json" ``` ### 3. 按优先级筛选 ```bash curl -X GET "http://localhost:5000/api/v1/missions/available?priority=5" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \ -H "Accept: application/json" ``` ### 4. 按电量要求筛选 ```bash curl -X GET "http://localhost:5000/api/v1/missions/available?minBatteryLevel=50" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \ -H "Accept: application/json" ``` ### 5. 分页查询 ```bash curl -X GET "http://localhost:5000/api/v1/missions/available?limit=2&offset=0" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \ -H "Accept: application/json" ``` ### 6. 组合筛选 ```bash curl -X GET "http://localhost:5000/api/v1/missions/available?missionType=PATROL_TRANSPORT&priority=3&limit=10" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \ -H "Accept: application/json" ``` --- ## 📐 实施步骤 ### Phase 1: 基础实现 ✅ 1. 在 `mock_unmanned_vehicle.py` 中添加任务池数据结构（约200行） 2. 实现 `/api/v1/missions/available` 接口（约80行） 3. 添加基本的任务类型和优先级筛选 4. 测试接口基本功能 ### Phase 2: 增强功能 1. 添加更多样化的任务模板（不同区域、不同类型） 2. 实现高级筛选（按区域、按标签、按天气条件等） 3. 添加任务搜索功能（按名称、描述关键字） 4. 优化分页性能 ### Phase 3: 集成与扩展 1. 与任务下发接口集成（下一步需求） 2. 添加任务状态管理（可执行、进行中、已完成） 3. 实现任务动态更新机制 4. 添加任务执行统计和历史记录 --- ## 🔗 与现有系统的集成 ### 与 `/status` 接口的关系 - `/status` 接口：返回车辆当前正在执行的任务状态 - `/missions/available` 接口：返回可供选择的任务清单 ### 数据一致性 任务模板中的字段结构应与 `missionContext` 保持一致： ```python # 当任务被分配给车辆时，从任务模板创建任务实例 def assign_mission_to_vehicle(vehicle_id, mission_template_id): template = get_mission_template(mission_template_id) # 创建任务实例 mission_instance = { "missionId": f"{template['missionId']}_INSTANCE_{timestamp}", "missionType": template["missionType"], "startTime": int(time.time() * 1000), "estimatedEndTime": int(time.time() * 1000) + template["estimatedDuration"], "progress": 0.0, "totalMileage": template["totalMileage"], "waypoints": [ {**wp, "status": "PENDING"} for wp in template["waypoints"] ] } # 更新车辆数据 vehicle_data["mission_id"] = mission_instance["missionId"] vehicle_data["mission_type"] = mission_instance["missionType"] vehicle_data["mission_start_time"] = mission_instance["startTime"] return mission_instance ``` --- ## 📊 后续扩展方向 ### 1. 任务下发接口 ``` POST /api/v1/vehicles/{vehicleId}/missions ``` 用于将选中的任务分配给指定车辆。 ### 2. 任务管理接口 ``` GET /api/v1/missions/{missionId} # 获取任务详情 PUT /api/v1/missions/{missionId} # 更新任务 DELETE /api/v1/missions/{missionId} # 删除任务 POST /api/v1/missions # 创建新任务模板 ``` ### 3. 任务执行控制 ``` POST /api/v1/vehicles/{vehicleId}/missions/{missionId}/pause # 暂停任务 POST /api/v1/vehicles/{vehicleId}/missions/{missionId}/resume # 恢复任务 POST /api/v1/vehicles/{vehicleId}/missions/{missionId}/cancel # 取消任务 ``` ### 4. 任务统计与分析 ``` GET /api/v1/missions/statistics # 任务统计信息 GET /api/v1/missions/history # 任务执行历史 ``` --- ## ✅ 验收标准 1. **接口可访问性** - [ ] 接口正常响应 200 状态码 - [ ] 支持 CORS 跨域请求 - [ ] JWT 认证正常工作 2. **数据完整性** - [ ] 每个任务包含所有必需字段 - [ ] 路径点数据完整且符合规范 - [ ] 任务类型和状态枚举值正确 3. **筛选功能** - [ ] 按任务类型筛选正常 - [ ] 按优先级筛选正常 - [ ] 按电量要求筛选正常 - [ ] 多条件组合筛选正常 4. **分页功能** - [ ] limit 和 offset 参数正常工作 - [ ] total 字段返回正确的总数 - [ ] 边界情况处理正确 5. **错误处理** - [ ] 无效参数返回 400 错误 - [ ] 未授权访问返回 401 错误 - [ ] 服务器错误返回 500 错误 - [ ] 错误消息清晰易懂 6. **性能要求** - [ ] 响应时间 < 500ms - [ ] 支持并发请求 - [ ] 日志记录完整 --- ## 📝 附录 ### A. 坐标系统说明 所有坐标使用 **WGS84 坐标系**： - 纬度范围: -90 ~ 90 - 经度范围: -180 ~ 180 - 青岛胶东国际机场参考中心: (120.0834104, 36.35406879) ### B. 时间格式说明 所有时间戳使用 **毫秒级 UTC 时间**： - 格式: Unix timestamp (milliseconds) - 示例: 1736175610000 - 转换: `int(time.time() * 1000)` ### C. 参考文档 - 通用无人车运行状态API: `doc/requirement/universal_autonomous_vehicle_api_min_required.md` - Mock服务主文件: `tools/mock_unmanned_vehicle.py` - 项目说明文档: `CLAUDE.md` --- **文档结束**