syntax = "proto3";

package cmvr.api;

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

// AGV 通用服务。该服务只暴露控制器无关的能力，
// 厂商协议、地图文件格式和控制器特有参数由具体 AGV 适配器内部处理。
service AgvService {
  // 获取 AGV 当前运行状态快照。
  rpc getRuntimeState(AgvRuntimeStateCommand.Request) returns (AgvRuntimeStateCommand.Feedback);

  // 获取当前导航任务状态。
  rpc getNavigationStatus(AgvNavigationStatusCommand.Request) returns (AgvNavigationStatusCommand.Feedback);

  // 执行急停或等效安全停止动作。
  rpc emergencyStop(CommandHeader.Request) returns (CommandHeader.Feedback);

  // 清除可恢复故障或告警。
  rpc clearFault(CommandHeader.Request) returns (CommandHeader.Feedback);

  // 导航到指定地图位姿。目标位姿 x/y 单位为米，theta 单位为弧度。
  rpc navigateToPose(AgvNavigateToPoseCommand.Request) returns (AgvNavigateToPoseCommand.Feedback);

  // 导航到指定地图站点。
  rpc navigateToStation(AgvNavigateToStationCommand.Request) returns (AgvNavigateToStationCommand.Feedback);

  // 按显式站点路径执行导航。
  rpc followPath(AgvFollowPathCommand.Request) returns (AgvFollowPathCommand.Feedback);

  // 暂停当前导航任务。
  rpc pauseNavigation(CommandHeader.Request) returns (CommandHeader.Feedback);

  // 恢复已暂停的导航任务。
  rpc resumeNavigation(CommandHeader.Request) returns (CommandHeader.Feedback);

  // 取消当前导航任务。
  rpc cancelNavigation(CommandHeader.Request) returns (CommandHeader.Feedback);

  // 下发底盘速度控制指令。vx/vy 单位为米/秒，wz 单位为弧度/秒。
  rpc setVelocity(AgvSetVelocityCommand.Request) returns (AgvSetVelocityCommand.Feedback);

  // 停止底盘速度控制。该接口不等价于取消导航任务。
  rpc stopVelocityControl(CommandHeader.Request) returns (CommandHeader.Feedback);

  // 查询 AGV 控制器可用地图名称列表。
  rpc listMaps(AgvListMapsCommand.Request) returns (AgvListMapsCommand.Feedback);

  // 查询当前地图中的站点列表。
  rpc listStations(AgvListStationsCommand.Request) returns (AgvListStationsCommand.Feedback);

  // 切换当前使用地图。
  rpc switchMap(AgvMapCommand.Request) returns (AgvMapCommand.Feedback);

  // 上传地图内容到 AGV 控制器。地图内容字段由适配器解释。
  rpc uploadMap(AgvMapCommand.Request) returns (AgvMapCommand.Feedback);

  // 下载指定地图内容。
  rpc downloadMap(AgvMapCommand.Request) returns (AgvMapCommand.Feedback);

  // 开始建图/扫图会话。请求只选择 2D、3D 或二者都要，
  // 控制器特有地图格式由 AGV 适配器内部转换。
  rpc startMapping(AgvStartMappingCommand.Request) returns (AgvStartMappingCommand.Feedback);

  // 以服务端流方式发送统一地图。resume_token 为空时应先发送全量快照；
  // 后续是否发送增量由 AGV 适配器能力决定，并通过 update_type 标记。
  rpc streamMap(AgvMapStreamCommand.Request) returns (stream AgvMapStreamCommand.Feedback);

  // 停止当前建图/扫图会话。
  rpc stopMapping(CommandHeader.Request) returns (CommandHeader.Feedback);


  // 按指定速度平移固定距离。成功返回仅表示控制器已接受命令。
  rpc translate(AgvTranslateCommand.Request) returns (AgvTranslateCommand.Feedback);
}