syntax = "proto3";

package agv.calibration.vehicle.profile;

import "calibration_common.proto";

// ├── msg/
// │   ├── ChassisType.msg
// │   ├── SensorType.msg
// │   ├── CameraMountType.msg
// │   ├── ControlAxisType.msg
// │   ├── ControllerAlgorithmType.msg
// │   ├── CalibrationAbilityType.msg
// │   ├── CalibrationModuleType.msg
// │   ├── WorkflowStageType.msg
// │   ├── VehicleBaseInfo.msg
// │   ├── MechanicalArmProfile.msg
// │   ├── SensorProfile.msg
// │   ├── ControllerProfile.msg
// │   ├── ControllerSelection.msg
// │   ├── CalibrationCapability.msg
// │   ├── VehicleProfile.msg
// │   ├── RegisterOrUpdateVehicleProfileRequest.msg
// │   ├── VehicleProfileQuery.msg
// │   ├── VehicleProfileResponse.msg
// │   ├── EvaluateVehicleCalibrationApplicabilityRequest.msg
// │   ├── ApplicabilityIssue.msg
// │   └── VehicleCalibrationApplicabilityResponse.msg
// ├── srv/
// │   ├── RegisterOrUpdateVehicleProfile.srv
// │   ├── GetVehicleProfile.srv
// │   └── EvaluateVehicleCalibrationApplicability.srv
// └── action/
//     └── （当前无需新增 action）

// =========================================================
// 文件作用：车辆画像与能力描述协议
// 使用范围：
// 1) 车间在开始整车标定前，先描述“要标定的到底是什么车”
// 2) 供车间编排器根据车辆画像自动生成执行计划
// 3) 供各专项服务判断当前车辆是否支持对应标定任务
// =========================================================

// =========================================================
// 服务：车辆画像服务
// 运行位置：Ubuntu 车间电脑
// 调用方：车间编排器、配置界面、专项服务
// =========================================================
service VehicleProfileService {
  // 心跳保活
  rpc Heartbeat(.agv.calibration.common.HeartbeatRequest)
      returns (.agv.calibration.common.HeartbeatResponse);

  // 注册 / 更新一份车辆画像
  rpc RegisterOrUpdateVehicleProfile(RegisterOrUpdateVehicleProfileRequest)
      returns (.agv.calibration.common.StandardResponse);

  // 查询车辆画像
  rpc GetVehicleProfile(VehicleProfileQuery)
      returns (VehicleProfileResponse);

  // 评估当前车辆画像支持哪些标定能力
  rpc EvaluateVehicleCalibrationApplicability(
      EvaluateVehicleCalibrationApplicabilityRequest)
      returns (VehicleCalibrationApplicabilityResponse);
}

// =========================================================
// 底盘类型
// 作用：描述车辆底盘运动学形式
// =========================================================
enum ChassisType {
  CHASSIS_TYPE_UNSPECIFIED = 0; // 未指定
  ACKERMANN = 1;                // 阿克曼
  DIFFERENTIAL = 2;             // 差速
  SINGLE_STEER_WHEEL = 3;       // 单舵轮
  MULTI_STEER_WHEEL = 4;        // 多舵轮
}

// =========================================================
// 传感器类型
// 作用：描述车辆上挂载的传感器种类
// =========================================================
enum SensorType {
  SENSOR_TYPE_UNSPECIFIED = 0; // 未指定
  DOWNWARD_CAMERA = 1;         // 下视相机
  FRONT_CAMERA = 2;            // 前视相机
  ARM_CAMERA = 3;              // 机械臂相机
  LIDAR_3D = 4;                // 3D 激光雷达
  LIDAR_2D = 5;                // 2D 激光雷达
  IMU = 6;                     // IMU
}

// =========================================================
// 相机安装形式
// 作用：描述相机与车体 / 机械臂的安装关系
// =========================================================
enum CameraMountType {
  CAMERA_MOUNT_TYPE_UNSPECIFIED = 0; // 未指定
  FIXED_ON_BASE = 1;                 // 固定在车体上
  DOWNWARD_MOUNTED = 2;              // 下视安装
  FRONT_MOUNTED = 3;                 // 前视安装
  EYE_IN_HAND = 4;                   // 眼在手上
  EYE_TO_HAND = 5;                   // 眼在手外
}

// =========================================================
// 控制轴类型
// 作用：将控制器分成横向控制器与纵向控制器
// =========================================================
enum ControlAxisType {
  CONTROL_AXIS_UNSPECIFIED = 0; // 未指定
  LATERAL_CONTROL = 1;          // 横向控制
  LONGITUDINAL_CONTROL = 2;     // 纵向控制
}

// =========================================================
// 控制算法类型
// 作用：描述车辆当前支持的控制算法
// =========================================================
enum ControllerAlgorithmType {
  CONTROLLER_ALGORITHM_UNSPECIFIED = 0; // 未指定
  PID = 1;                              // PID
  MPC = 2;                              // MPC
  LQR = 3;                              // LQR
  PURE_PURSUIT = 4;                     // Pure Pursuit
}

// =========================================================
// 标定能力类型
// 作用：用于编排器判断某个专项是否适用于当前车辆
// =========================================================
enum CalibrationAbilityType {
  CALIBRATION_ABILITY_UNSPECIFIED = 0;    // 未指定
  EXTERNAL_LOCALIZATION_CALIBRATION = 1;  // 外部定位 / 真值参考接入
  CHASSIS_CALIBRATION = 2;                // 底盘标定
  CONTROL_CALIBRATION = 3;                // 运控参数标定
  SENSOR_CALIBRATION = 4;                 // 传感器标定
  HAND_EYE_CALIBRATION = 5;               // 手眼标定
}

// =========================================================
// 标定模块类型
// 作用：供总控编排、执行事件、报告汇总时标识任务属于哪个模块
// 说明：
// 1) 该枚举会被 workshop_orchestration.proto 直接引用
// 2) 这里不仅包含传统“标定模块”，也补充了预检、联合验收、归档等总控阶段
// =========================================================
enum CalibrationModuleType {
  CALIBRATION_MODULE_UNSPECIFIED = 0; // 未指定
  EXTERNAL_LOCALIZATION_MODULE = 1;   // 外部定位 / 真值参考模块
  CHASSIS_MODULE = 2;                 // 底盘标定模块
  CONTROL_MODULE = 3;                 // 运控标定模块
  SENSOR_INTRINSIC_MODULE = 4;        // 传感器内参标定模块
  SENSOR_EXTRINSIC_MODULE = 5;        // 传感器外参标定模块
  HAND_EYE_MODULE = 6;                // 手眼标定模块
  WORKSHOP_PRECHECK_MODULE = 7;       // 车间预检模块
  JOINT_ACCEPTANCE_MODULE = 8;        // 整车联合验收模块
  PARAMETER_COMMIT_MODULE = 9;        // 参数固化模块
  REPORT_ARCHIVE_MODULE = 10;         // 报告与归档模块
}

// =========================================================
// 工作流阶段类型
// 作用：用于描述自动化标定车间完整流程中的阶段
// 说明：
// 1) 该枚举比 CalibrationModuleType 更偏“流程阶段”
// 2) 可供后续编排器构建执行计划时直接使用
// =========================================================
enum WorkflowStageType {
  WORKFLOW_STAGE_UNSPECIFIED = 0;             // 未指定
  PROFILE_VALIDATION_STAGE = 1;               // 车辆画像校验阶段
  EXTERNAL_REFERENCE_READY_CHECK_STAGE = 2;   // 真值参考接入与确认阶段
  WORKSHOP_PRECHECK_STAGE = 3;                // 整车预检阶段
  CHASSIS_CALIBRATION_STAGE = 4;              // 底盘标定阶段
  CONTROL_CALIBRATION_STAGE = 5;              // 运控参数调优阶段
  SENSOR_INTRINSIC_CALIBRATION_STAGE = 6;     // 传感器内参标定阶段
  SENSOR_EXTRINSIC_CALIBRATION_STAGE = 7;     // 传感器外参标定阶段
  HAND_EYE_CALIBRATION_STAGE = 8;             // 手眼标定阶段
  JOINT_ACCEPTANCE_STAGE = 9;                 // 整车联合验收阶段
  PARAMETER_COMMIT_STAGE = 10;                // 参数固化阶段
  REPORT_ARCHIVE_STAGE = 11;                  // 报告归档阶段
}

// =========================================================
// 车辆基础信息
// 作用：表达车辆身份信息
// =========================================================
message VehicleBaseInfo {
  string vehicle_id = 1;      // 车辆唯一 ID
  string vehicle_name = 2;    // 车辆显示名
  string model_name = 3;      // 车型 / 型号
  string serial_number = 4;   // 出厂序列号
  string manufacturer = 5;    // 厂商
  string description = 6;     // 备注说明
}

// =========================================================
// 机械臂画像
// 作用：描述车辆是否带机械臂以及机械臂的基本信息
// =========================================================
message MechanicalArmProfile {
  bool has_mechanical_arm = 1; // 是否带机械臂
  string arm_id = 2;           // 机械臂 ID
  string arm_model = 3;        // 机械臂型号
  uint32 dof = 4;              // 自由度
  string arm_base_frame = 5;   // 机械臂基座坐标系
  string tool_frame = 6;       // 末端工具坐标系
}

// =========================================================
// 传感器画像
// 作用：描述单个传感器的安装与参与标定属性
// 说明：
// 1) enabled 表示这台车物理上是否启用了该传感器
// 2) selected_for_this_session 表示本轮标定是否纳入执行计划
// 3) needs_intrinsic_calibration / needs_extrinsic_calibration 表示本轮是否需要做对应标定
// =========================================================
message SensorProfile {
  string sensor_id = 1;                 // 传感器 ID
  SensorType sensor_type = 2;           // 传感器类型
  string sensor_name = 3;               // 传感器显示名
  string frame_id = 4;                  // 传感器 frame_id
  CameraMountType camera_mount_type = 5;// 相机安装形式；非相机可忽略
  bool enabled = 6;                     // 当前是否启用
  bool needs_intrinsic_calibration = 7; // 本轮是否需要做内参标定
  bool needs_extrinsic_calibration = 8; // 本轮是否需要做外参标定
  string device_hint = 9;               // 设备名 / topic / IP / 端口等提示信息
  bool selected_for_this_session = 10;  // 本轮是否纳入执行计划
  bool supports_intrinsic_calibration = 11; // 该传感器是否支持内参标定
  bool supports_extrinsic_calibration = 12; // 该传感器是否支持外参标定
}

// =========================================================
// 控制器画像
// 作用：描述某一控制轴支持的算法集合
// 说明：
// 1) 该结构偏静态能力描述
// 2) 表达“这个控制轴支持哪些算法、默认算法是什么”
// =========================================================
message ControllerProfile {
  ControlAxisType control_axis = 1;                        // 控制轴类型
  repeated ControllerAlgorithmType supported_algorithms = 2; // 支持的算法列表
  ControllerAlgorithmType default_algorithm = 3;           // 默认算法
}

// =========================================================
// 控制器选择项
// 作用：表达“本轮标定到底要启用哪个控制轴、哪个算法、是否需要调优”
// 说明：
// 1) 该结构偏会话/配方侧选择
// 2) 用于解决“横向用 MPC，纵向用 PID”这类组合问题
// =========================================================
message ControllerSelection {
  ControlAxisType control_axis = 1;             // 控制轴类型
  ControllerAlgorithmType algorithm_type = 2;   // 选中的算法类型
  bool enabled = 3;                             // 本轮是否启用该控制器
  bool need_tuning = 4;                         // 本轮是否需要对该控制器调优
  bool is_default = 5;                          // 是否为当前默认控制器
}

// =========================================================
// 标定能力项
// 作用：表达当前车辆是否支持某项标定
// =========================================================
message CalibrationCapability {
  CalibrationAbilityType ability_type = 1; // 标定能力类型
  bool supported = 2;                      // 是否支持
  string message = 3;                      // 说明文字
}

// =========================================================
// 车辆画像总包
// 作用：统一表达待标定车辆的全部静态配置
// 发送方：配置界面 / 车间系统
// 接收方：车间编排器 / 各专项服务
// =========================================================
message VehicleProfile {
  VehicleBaseInfo base_info = 1;                           // 车辆基础信息
  ChassisType chassis_type = 2;                            // 底盘类型
  MechanicalArmProfile arm_profile = 3;                    // 机械臂画像
  repeated SensorProfile sensors = 4;                      // 所有传感器画像
  repeated ControllerProfile controllers = 5;              // 控制器能力画像
  .agv.calibration.common.FileReference urdf_file = 6;     // 车辆 URDF 文件引用
  string base_link_frame = 7;                              // 车辆 base_link 名称
  repeated CalibrationCapability capabilities = 8;         // 标定能力清单
  repeated .agv.calibration.common.KeyValuePair metadata = 9; // 扩展元数据

  repeated ControllerSelection controller_selections = 10; // 本轮控制器选择配置
  repeated WorkflowStageType enabled_workflow_stages = 11; // 本轮启用的流程阶段
  string profile_version = 12;                             // 车辆画像版本号
  .agv.calibration.common.FileDigest profile_digest = 13;  // 车辆画像摘要
}

// =========================================================
// 注册 / 更新车辆画像请求
// 作用：向系统写入一份车辆画像
// =========================================================
message RegisterOrUpdateVehicleProfileRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  VehicleProfile profile = 2;                       // 车辆画像
}

// =========================================================
// 车辆画像查询请求
// 作用：按 vehicle_id 查询车辆画像
// =========================================================
message VehicleProfileQuery {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string vehicle_id = 2;                            // 车辆 ID
}

// =========================================================
// 车辆画像查询响应
// 作用：返回完整车辆画像
// =========================================================
message VehicleProfileResponse {
  bool success = 1;                                  // 是否成功
  .agv.calibration.common.ErrorCode error_code = 2; // 错误码
  string message = 3;                                // 说明
  VehicleProfile profile = 4;                        // 车辆画像
}

// =========================================================
// 标定适用性评估请求
// 作用：根据车辆画像分析能否执行各项标定
// =========================================================
message EvaluateVehicleCalibrationApplicabilityRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  VehicleProfile profile_snapshot = 2;              // 车辆画像快照
}

// =========================================================
// 适用性问题
// 作用：描述不支持 / 风险 / 缺失项
// =========================================================
message ApplicabilityIssue {
  CalibrationAbilityType ability_type = 1; // 对应能力
  bool blocking = 2;                       // 是否为阻塞问题
  string message = 3;                      // 问题说明
}

// =========================================================
// 标定适用性评估响应
// 作用：返回支持项与阻塞项，供编排器生成计划
// =========================================================
message VehicleCalibrationApplicabilityResponse {
  bool success = 1;                                  // 是否成功
  .agv.calibration.common.ErrorCode error_code = 2; // 错误码
  string message = 3;                                // 说明
  repeated CalibrationCapability capabilities = 4;   // 支持能力列表
  repeated ApplicabilityIssue issues = 5;            // 问题列表
  bool overall_supported = 6;                        // 是否总体可开展标定
  repeated WorkflowStageType recommended_workflow_stages = 7; // 推荐执行阶段
}
