syntax = "proto3";

package cmvr.api;

import "cmvr/api/common.proto";
import "cmvr/api/agv_utils.proto";

// 查询 AGV 运行状态命令。
message AgvRuntimeStateCommand {
  // 请求体。
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
  }
  // 反馈体。
  message Feedback {
    // 通用反馈头。包含成功标志、错误信息和反馈时间戳。
    CommandHeader.Feedback header = 1;
    // AGV 当前运行状态快照。
    cmvr.msgs.AgvRuntimeState state = 2;
  }
}

// 查询 AGV 当前导航任务状态命令。
message AgvNavigationStatusCommand {
  // 请求体。
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
  }
  // 反馈体。
  message Feedback {
    // 通用反馈头。包含成功标志、错误信息和反馈时间戳。
    CommandHeader.Feedback header = 1;
    // 当前导航任务状态。
    cmvr.msgs.AgvNavigationStatus status = 2;
  }
}

// 导航到指定地图位姿命令。
message AgvNavigateToPoseCommand {
  // 请求体。
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
    // 目标位姿。x/y 单位：米，theta 单位：弧度。
    cmvr.msgs.AgvPose2d pose = 2;
    // 通用运动约束和执行选项；默认同步阻塞至任务终态并确认停车。
    cmvr.msgs.AgvMotionOptions options = 3;
    // AGV 适配器扩展参数，用于传递厂商特有选项。
    cmvr.msgs.AgvAdapterParams adapter_params = 4;
  }
  // 反馈体。
  message Feedback {
    // 通用反馈头。包含成功标志、错误信息和反馈时间戳。
    CommandHeader.Feedback header = 1;
  }
}

// 导航到指定站点命令。
message AgvNavigateToStationCommand {
  // 请求体。
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
    // 目标站点 id。
    string station_id = 2;
    // 通用运动约束和执行选项；默认同步阻塞至任务终态并确认停车。
    cmvr.msgs.AgvMotionOptions options = 3;
    // AGV 适配器扩展参数，用于传递厂商特有选项。
    cmvr.msgs.AgvAdapterParams adapter_params = 4;
  }
  // 反馈体。
  message Feedback {
    // 通用反馈头。包含成功标志、错误信息和反馈时间戳。
    CommandHeader.Feedback header = 1;
  }
}

// 按显式站点路径导航命令。
message AgvFollowPathCommand {
  // 请求体。
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
    // 路径段列表。每段包含起点站点 id 和终点站点 id。
    repeated cmvr.msgs.AgvPathSegment path = 2;
    // 通用执行选项；默认同步阻塞至整条路径终态并确认停车。
    cmvr.msgs.AgvMotionOptions options = 3;
  }
  // 反馈体。
  message Feedback {
    // 通用反馈头。包含成功标志、错误信息和反馈时间戳。
    CommandHeader.Feedback header = 1;
  }
}


// 按指定速度执行固定距离平移命令。
message AgvTranslateCommand {
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
    // 固定距离平移参数。
    cmvr.msgs.AgvTranslation translation = 2;
  }

  message Feedback {
    // 仅表示控制器是否接受命令，不表示平移已经完成。
    CommandHeader.Feedback header = 1;
  }
}


// 下发底盘速度命令。
message AgvSetVelocityCommand {
  // 请求体。
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
    // 目标车体速度。vx/vy 单位：米/秒，wz 单位：弧度/秒。
    cmvr.msgs.AgvVelocity velocity = 2;
  }
  // 反馈体。
  message Feedback {
    // 通用反馈头。包含成功标志、错误信息和反馈时间戳。
    CommandHeader.Feedback header = 1;
  }
}

// 查询可用地图列表命令。
message AgvListMapsCommand {
  // 请求体。
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
  }
  // 反馈体。
  message Feedback {
    // 通用反馈头。包含成功标志、错误信息和反馈时间戳。
    CommandHeader.Feedback header = 1;
    // 地图名称列表。
    repeated string maps = 2;
  }
}

// 查询当前地图站点列表命令。
message AgvListStationsCommand {
  // 请求体。
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
  }
  // 反馈体。
  message Feedback {
    // 通用反馈头。包含成功标志、错误信息和反馈时间戳。
    CommandHeader.Feedback header = 1;
    // 当前地图中的站点列表。
    repeated cmvr.msgs.AgvStation stations = 2;
  }
}

// 地图上传、下载、切换等通用地图命令。
message AgvMapCommand {
  // 请求体。
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
    // 地图名称。切换/下载时表示目标地图，上传时表示写入的地图名称。
    string map_name = 2;
    // 地图内容。上传地图时使用；下载或切换地图时可为空。
    string content = 3;
  }
  // 反馈体。
  message Feedback {
    // 通用反馈头。包含成功标志、错误信息和反馈时间戳。
    CommandHeader.Feedback header = 1;
    // 地图内容。下载地图时返回；其他命令通常为空。
    string content = 2;
  }
}

// 开始建图/扫图命令。
message AgvStartMappingCommand {
  // 请求体。
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
    // 请求建图维度：2D、3D 或二者都要。未指定时由适配器选择最合适模式。
    cmvr.msgs.AgvMapDimension dimension = 2;
    // 目标地图名称。为空表示由 AGV 或适配器创建/选择默认地图名。
    string map_name = 3;
    // 是否请求实时建图更新。true 表示希望实时推送；false 表示允许离线/批处理。
    bool real_time = 4;
  }
  // 反馈体。
  message Feedback {
    // 通用反馈头。包含成功标志、错误信息和反馈时间戳。
    CommandHeader.Feedback header = 1;
    // 建图会话 id。该值由服务端生成，作为调试和日志关联标识。
    string session_id = 2;
  }
}

// 地图流命令。用于获取当前地图、最近地图、全量快照和后续增量更新。
message AgvMapStreamCommand {
  // 请求体。
  message Request {
    // 通用请求头。header.device_id 指定目标 AGV 设备。
    CommandHeader.Request header = 1;
    // 请求地图维度：2D、3D 或二者都要。该字段不是厂商格式选择器。
    cmvr.msgs.AgvMapDimension dimension = 2;
    // 地图名称。为空表示当前加载地图；若无当前地图，适配器应尝试使用最近保存/创建的地图。
    string map_name = 3;
    // 断点续传令牌。为空表示上位机没有缓存，服务端应先发送全量快照。
    string resume_token = 4;
    // 是否请求全量快照。首次请求通常应为 true。
    bool snapshot = 5;
    // 是否在快照之后保持流并发送增量更新。若适配器不支持增量，可继续发送全量并标记 update_type。
    bool incremental = 6;
    // 单条流消息建议最大载荷大小，单位：字节。小于等于 0 表示使用服务端默认值。
    int32 max_chunk_bytes = 7;
  }
  // 反馈体。
  message Feedback {
    // 通用反馈头。包含成功标志、错误信息和反馈时间戳。
    CommandHeader.Feedback header = 1;
    // 统一地图更新。payload 只会是 map_2d 或 map_3d，不暴露厂商原始格式。
    cmvr.msgs.AgvUnifiedMapUpdate update = 2;
  }
}