syntax = "proto3";

package agv.calibration.transport;

// =========================================================
// 文件作用：WiFi6/TCP 传输契约
// 使用范围：
// 1) Ubuntu 车间工控机与 Windows 车端代理之间的网络边界
// 2) 仿真车端 agent 与真实车端 agent 需要共同遵守的帧号和通道约定
// 3) 业务消息仍由 chassis/control/sensor/external_localization proto 定义
// 说明：
// 1) WiFi6 是承载网络，当前工程传输层使用 TCP 长/短连接
// 2) 当前仿真实现 payload 使用 proto 字段名风格的 JSON
// 3) 现场可切换为 protobuf binary，但必须保持本文件中的通道和帧号不变
// =========================================================

// =========================================================
// WiFi6 逻辑通道
// =========================================================
enum Wifi6Channel {
  WIFI6_CHANNEL_UNSPECIFIED = 0;
  WIFI6_CHANNEL_CHASSIS = 1;        // 底盘标定动作和急停
  WIFI6_CHANNEL_CONTROL = 2;        // 运控参数评估、轨迹跟踪
  WIFI6_CHANNEL_SENSOR = 3;         // 车端传感器原始数据
  WIFI6_CHANNEL_EXTERNAL_POSE = 4;  // 外部真值位姿输入到车端
}

// =========================================================
// 默认端口
// 说明：
// 1) WiFi6 边界默认只暴露一个车端 gateway 端口
// 2) channel 只是协议里的逻辑通道，不应该被理解成“一类功能一个物理端口”
// 3) 9001-9004 仅保留给仿真 router 背后的内部域服务或旧版兼容使用
// =========================================================
enum Wifi6DefaultPort {
  WIFI6_DEFAULT_PORT_UNSPECIFIED = 0;
  WIFI6_DEFAULT_PORT_VEHICLE_GATEWAY = 9000;
  WIFI6_LEGACY_INTERNAL_PORT_CHASSIS = 9001;
  WIFI6_LEGACY_INTERNAL_PORT_CONTROL = 9002;
  WIFI6_LEGACY_INTERNAL_PORT_SENSOR = 9003;
  WIFI6_LEGACY_INTERNAL_PORT_EXTERNAL_POSE = 9004;
}

// =========================================================
// TCP 载荷编码方式
// =========================================================
enum Wifi6PayloadEncoding {
  WIFI6_PAYLOAD_ENCODING_UNSPECIFIED = 0;
  WIFI6_PAYLOAD_ENCODING_JSON_PROTO_FIELD_NAMES = 1; // 当前仿真实现：JSON key 使用 proto 字段名
  WIFI6_PAYLOAD_ENCODING_PROTOBUF_BINARY = 2;        // 现场高性能实现可选
}

// =========================================================
// TCP 连接方向
// =========================================================
enum Wifi6FrameDirection {
  WIFI6_FRAME_DIRECTION_UNSPECIFIED = 0;
  WIFI6_FRAME_DIRECTION_WORKSHOP_TO_VEHICLE = 1;
  WIFI6_FRAME_DIRECTION_VEHICLE_TO_WORKSHOP = 2;
}

// =========================================================
// TCP 帧号
// 帧头格式固定为：
//   uint32 little-endian msg_type
//   uint32 little-endian payload_len
//   payload_len bytes payload
// 注意：
// 1) 这个 8 字节帧头不是 protobuf 序列化结果，而是传输层二进制头
// 2) payload 的业务结构由本字段注释中对应的 proto 消息定义
// 3) 逻辑 channel 由 msg_type 映射得到；同一个 gateway 端口根据 msg_type 做路由
// =========================================================
enum Wifi6FrameType {
  WIFI6_FRAME_TYPE_UNSPECIFIED = 0;

  // 底盘域：chassis_calibration.proto / AgvCalibChassisService
  WIFI6_FRAME_CHASSIS_GET_READINESS_REQ = 1;     // AgentReadinessRequest
  WIFI6_FRAME_CHASSIS_GET_READINESS_RSP = 2;     // ChassisReadinessResponse
  WIFI6_FRAME_CHASSIS_MOTION_PRIMITIVE_REQ = 3;  // MotionPrimitiveRequest
  WIFI6_FRAME_CHASSIS_MOTION_PRIMITIVE_RSP = 4;  // ChassisJobResult
  WIFI6_FRAME_CHASSIS_EMERGENCY_BRAKE_REQ = 5;   // Empty 或 EmergencyBrake 请求
  WIFI6_FRAME_CHASSIS_EMERGENCY_BRAKE_RSP = 6;   // StandardResponse

  // 运控域：control_calibration.proto / AgvCalibControlService
  WIFI6_FRAME_CONTROL_GET_READINESS_REQ = 11;  // AgentReadinessRequest
  WIFI6_FRAME_CONTROL_GET_READINESS_RSP = 12;  // ControlReadinessResponse
  WIFI6_FRAME_CONTROL_EVALUATION_REQ = 13;     // ControllerEvaluationRequest
  WIFI6_FRAME_CONTROL_EVALUATION_RSP = 14;     // ControlJobResult

  // 传感器域：sensor_calibration.proto / AgvCalibSensorService
  WIFI6_FRAME_SENSOR_GET_READINESS_REQ = 21;    // AgentReadinessRequest
  WIFI6_FRAME_SENSOR_GET_READINESS_RSP = 22;    // SensorReadinessResponse
  WIFI6_FRAME_SENSOR_GET_LATEST_FRAME_REQ = 23; // StreamVehicleSensorDataRequest 的轻量轮询形态
  WIFI6_FRAME_SENSOR_GET_LATEST_FRAME_RSP = 24; // VehicleSensorFrame
  WIFI6_FRAME_SENSOR_LIST_SENSORS_REQ = 25;     // Empty 或能力查询请求
  WIFI6_FRAME_SENSOR_LIST_SENSORS_RSP = 26;     // Sensor 列表响应

  // 外部真值位姿域：external_localization.proto / AgvCalibExternalPoseFeedService
  WIFI6_FRAME_EXTERNAL_POSE_PUSH_REQ = 31; // ExternalLocalizationTelemetry
  WIFI6_FRAME_EXTERNAL_POSE_PUSH_RSP = 32; // StandardResponse
}

// =========================================================
// TCP 帧头的 protobuf 表达
// 说明：
// 1) 这个 message 仅用于文档、测试、代码生成时表达契约
// 2) 实际线上帧头仍是上面注释中定义的 8 字节小端二进制结构
// =========================================================
message Wifi6TcpFrameHeader {
  Wifi6FrameType msg_type = 1; // 对应 8 字节帧头中的 uint32 msg_type
  uint32 payload_len = 2;      // 对应 8 字节帧头中的 uint32 payload_len
}

// =========================================================
// 逻辑通道端点
// =========================================================
message Wifi6ChannelEndpoint {
  Wifi6Channel channel = 1;
  Wifi6DefaultPort default_port = 2;
  Wifi6FrameDirection request_direction = 3;
  string canonical_proto_file = 4; // 例如 chassis_calibration.proto
  string canonical_service = 5;    // 例如 AgvCalibChassisService
}

// =========================================================
// 请求 / 响应帧映射
// =========================================================
message Wifi6FrameMapping {
  Wifi6Channel channel = 1;
  Wifi6FrameType request_type = 2;
  Wifi6FrameType response_type = 3;
  Wifi6PayloadEncoding payload_encoding = 4;
  string request_message = 5;  // proto 消息名
  string response_message = 6; // proto 消息名
  string rpc_name = 7;         // 对齐的 RPC 名称；轻量轮询可为空
}

// =========================================================
// 当前工程默认契约版本
// =========================================================
message Wifi6TransportContract {
  string contract_version = 1; // 当前为 "wifi6_tcp_v1"
  Wifi6PayloadEncoding default_payload_encoding = 2;
  repeated Wifi6ChannelEndpoint endpoints = 3;
  repeated Wifi6FrameMapping frame_mappings = 4;
}
