# 自动化标定车间协议协同工作说明

> **核心定位**：面向自动化标定车间的分层协议设计，用 8 个 `.proto` 把“车间总控、车辆画像、真值参考、底盘标定、传感器标定、运控调优、参数归档、WiFi6 传输契约”串成一条可执行、可追溯、可扩展的自动化流程。

协议格式：Protocol Buffers  
目标平台：Ubuntu / Linux / Windows  
当前状态：Proto 冻结候选版

---

## 目录

- [1. 文档目的](#1-文档目的)
- [2. 系统边界与角色分工](#2-系统边界与角色分工)
- [3. 八个 Proto 文件的职责划分](#3-八个-proto-文件的职责划分)
- [4. 八个 Proto 的依赖关系](#4-八个-proto-的依赖关系)
- [5. 自动化标定车间完整流程](#5-自动化标定车间完整流程)
- [6. 八个 Proto 在主流程中的协同方式](#6-八个-proto-在主流程中的协同方式)
- [7. 当前协议设计已经明确的关键原则](#7-当前协议设计已经明确的关键原则)
- [8. 冻结前建议补齐的小修补项](#8-冻结前建议补齐的小修补项)
- [9. 从 Proto 到 ROS2 的映射建议](#9-从-proto-到-ros2-的映射建议)
- [10. 工程实现建议](#10-工程实现建议)
- [11. 总结](#11-总结)

---

## 1. 文档目的

本文档用于说明当前自动化标定车间中 **8 个核心 `.proto` 文件** 的职责边界、依赖关系、协同流程和工程落地方式。

这套协议不是为了把所有逻辑堆到一个服务里，而是为了把整个系统拆成清晰的几层：

- **车间总控层**：只负责编排、状态推进、审批、回滚、归档
- **专业域服务层**：分别处理真值参考、底盘、传感器、运控调优
- **车端代理层**：只负责动作执行、传感器订阅与数据采集、参数写入、状态回传
- **公共协议层**：统一请求头、错误码、心跳、长任务状态、文件引用、位姿/向量类型

这份 README 的目标是让后续做 ROS2 映射、节点架构设计、C++ 服务实现时，所有人对协议语义有同一个理解。

---

## 2. 系统边界与角色分工

### 2.1 Ubuntu / Linux 车间电脑

负责：

- 读取车辆画像与工位配置
- 创建整车标定会话
- 生成执行计划与阶段顺序
- 调用各专项服务完成数据采集和参数求解
- 做自动验收、审批流、失败回退、结果归档

### 2.2 Windows 车端代理

负责：

- 接收车间电脑下发的动作命令
- 执行底盘动作、轨迹跟踪、停车、走位等任务
- 采集车辆状态、传感器状态与原始数据
- 写入已经求解好的参数
- 回传执行状态与遥测数据

### 2.3 车间基础设施

包括但不限于：

- 外部定位 / 真值参考系统
- 标定板、标靶、地面参考目标
- 安全联锁、急停、区域清场机制
- 车间网络、存储、数据库、日志系统

### 2.4 协议设计原则

- **Linux 负责求解和编排，不负责直接驱动硬件细节**
- **Windows 负责执行和采集，不负责复杂求解与全局决策**
- **车端传感器属于车辆侧，图像、点云、LaserScan、IMU 原始帧经 WiFi6 从车端转发到车间电脑**
- **所有阶段都围绕同一个 `session_id`、`vehicle_id`、`job_id` 协同**
- **所有长任务都统一使用 `JobAccepted / JobStatus / JobResult` 语义**

---

## 3. 八个 Proto 文件的职责划分

### 3.1 calibration_common.proto

**作用：公共基础协议定义。**

它是整个协议体系的地基，所有其他 proto 都依赖它。

当前主要承担：

- `RequestHeader`：统一会话、任务、车辆、请求追踪信息
- `ErrorCode`：统一错误码
- `StandardResponse`：统一短响应
- `JobAccepted / JobQuery / JobStatus`：统一长任务状态表达
- `HeartbeatRequest / HeartbeatResponse`：统一保活机制
- `AgentReadinessRequest / ReadinessIssue`：统一 readiness 检查模式
- `FileDigest / FileReference`：统一文件摘要与文件引用
- `Vector3D / Pose3D`：统一三维向量与位姿表达
- `KeyValuePair`：为后续扩展保留元数据入口

**一句话理解**：它不描述任何专项算法，但所有专项服务都要先站在这块地基上。

---

### 3.2 vehicle_profile.proto

**作用：车辆画像、能力描述、流程启用配置。**

它回答的问题不是“怎么标”，而是：

- 这台车是什么底盘
- 有哪些传感器
- 有没有机械臂
- 当前支持哪些控制器
- 本轮会话到底启用哪些阶段
- 本轮横向 / 纵向分别使用什么控制算法

当前重点内容包括：

- `ChassisType`
- `SensorType`
- `CameraMountType`
- `ControlAxisType`
- `ControllerAlgorithmType`
- `CalibrationModuleType`
- `WorkflowStageType`
- `SensorProfile`
- `ControllerProfile`
- `ControllerSelection`
- `VehicleProfile`

**这一版最关键的升级点**：

- 已明确拆出 **横向控制器** 与 **纵向控制器**
- 已明确加入 **流程阶段类型 `WorkflowStageType`**
- 已支持 **相机是否做内参 / 是否做外参** 的会话级选择

**一句话理解**：它决定“这台车是什么、支持什么、这次打算标什么”。

---

### 3.3 external_localization.proto

**作用：外部定位 / 真值参考接入与验证协议。**

它负责的不是“车上定位算法”，而是车间里的真值参考来源，例如：

- 动捕系统
- 外部相机阵列
- 激光跟踪仪
- 全站仪
- 工位级高精度测量系统

当前协议已经覆盖：

- readiness 查询
- 工作模式切换
- 能力查询
- 参考位姿采集
- 标靶对齐
- 真值参考验证
- 外部定位遥测
- 外部定位结果写入与查询

**这一版最关键的升级点**：

- 已不再只是“能采位姿”
- 已支持 **阶段 0：真值参考接入与确认**
- 已支持验证指标，例如时间同步、覆盖范围、观测质量、跟踪稳定性、丢失比例

**一句话理解**：它给整个自动化车间提供“可信真值输入”。

---

### 3.4 chassis_calibration.proto

**作用：底盘标定执行、遥测回传、参数写入。**

它定义的是 Linux 与车端代理之间，关于底盘动作执行和结果回传的协议，而不是底盘参数求解算法本身。

当前协议已经覆盖：

- readiness 查询
- 工作模式切换
- 底盘能力查询
- 动作原语执行
- 遥测流回传
- 参数写入与查询
- 验证摘要与任务结果

支持的动作原语包括：

- 直线
- 圆弧
- 原地旋转
- 舵角扫动
- 横移
- 斜移
- 模块零位检查
- 模块协同转向

**这一版最关键的升级点**：

- 已覆盖 **阿克曼 / 差速 / 单舵轮 / 多舵轮**
- 已补齐多舵轮细化原语
- 已增加 `ChassisValidationSummary`
- 已增加 `ChassisJobResult`

**一句话理解**：它让 Linux 可以命令车辆完成底盘测试，并拿回足够做求解与验收的数据。

---

### 3.5 control_calibration.proto

**作用：运控参数调优执行与评估协议。**

这里的“运控标定”指的是车辆控制器参数调优，而不是底盘几何参数。

当前协议已经覆盖：

- readiness 查询
- 工作模式切换
- 参数热加载
- 评估任务启动
- 遥测流回传
- 参数固化
- 当前参数查询
- 任务结果与验证摘要

支持的评估任务包括：

- 轨迹跟踪
- 速度阶跃
- 加减速
- 停车精度

**这一版最关键的升级点**：

- 已明确拆分 **横向控制器** 与 **纵向控制器**
- 已将 MPC 参数模型拆为：
  - `LateralMPCParams`
  - `LongitudinalMPCParams`
- 已支持“横向 MPC + 纵向 PID”这类组合
- 已增加 `ControlValidationSummary`
- 已增加 `ControlJobResult`

**一句话理解**：它负责“加载参数、执行测试、回传误差、评估收敛、固化最终控制器参数”。

---

### 3.6 sensor_calibration.proto

**作用：传感器标定任务、采集过程、参数结果与验证摘要。**

覆盖范围包括：

- 下视相机
- 前视相机
- 机械臂相机（眼在手上 / 眼在手外）
- 3D 激光雷达
- 2D 激光雷达
- IMU

当前协议已经覆盖：

- readiness 查询
- 工作模式切换
- 能力查询
- 相机内参任务
- IMU 内参任务
- 传感器到 `base_link` 外参任务
- 手眼标定任务
- 遥测流
- 车端传感器原始数据流 `StreamVehicleSensorData`
- 车间电脑传感器数据接收服务 `AgvCalibWorkshopSensorIngestService`
- 参数写入与查询
- 任务结果与验证摘要

**这一版最关键的升级点**：

- 已支持相机 **只做内参 / 只做外参 / 内外参都做**
- 已将 IMU 内参改为三轴强约束：
  - `Vector3D accel_bias`
  - `Vector3D gyro_bias`
- 已增加 `LASER_SCAN_FILE`，单独表达 2D 激光雷达产物
- 已增加 `VehicleSensorFrame`，用于承载相机图像、3D 点云、2D LaserScan、IMU 原始帧，并支持大图像 / 点云分片传输
- 已增加 `SensorValidationSummary`
- 已增加 `SensorCalibrationJobResult`

**一句话理解**：它负责把“采什么、怎么采、原始数据怎么从车端到车间电脑、产出什么参数、怎么判断是否通过”描述完整。

---

### 3.7 workshop_orchestration.proto

**作用：整车自动化标定总编排协议。**

这是整套系统的总控层，不做具体求解，只做流程推进与状态管理。

当前协议已经覆盖：

- 创建会话
- 查询会话
- 构建执行计划
- 重建执行计划
- 校验执行计划
- 运行车间预检
- 启动 / 暂停 / 恢复 / 取消整场会话
- 事件流推送
- 人工确认
- 审批阶段结果
- 回滚阶段参数
- 获取最终报告

**这一版最关键的升级点**：

- 已不再只是“创建会话 + 获取状态”
- 已支持 **阶段计划**、**预检**、**人工确认**、**审批**、**回滚**、**最终报告**
- 已通过 `WorkflowStageType` 直接对齐自动化车间主流程

**一句话理解**：它是整个自动化标定车间的总导演和状态机主控器。

---

### 3.8 transport_contract.proto

**作用：车间工控机与车端电脑之间的 WiFi6/TCP 传输契约。**

它不替代底盘、运控、传感器、外部真值的业务消息，而是固定网络边界上的通道和帧规则：

- `Wifi6Channel`：底盘、运控、传感器、外部真值位姿四个逻辑通道
- `Wifi6DefaultPort`：WiFi6 边界默认使用统一车端 gateway 端口 9000，9001-9004 只作为仿真内部域端口或旧版兼容
- `Wifi6FrameType`：当前 TCP 帧号 1-32
- `Wifi6TcpFrameHeader`：8 字节小端帧头的契约表达
- `Wifi6PayloadEncoding`：当前 JSON 字段名编码与后续 protobuf binary 编码预留

**一句话理解**：它把“哪些数据通过 WiFi6 怎么走”固定下来，避免 Windows 车端和 Ubuntu 工控机只靠代码常量私下约定。

---

## 4. 八个 Proto 的依赖关系

依赖关系可以概括如下：

| Proto 文件 | 依赖 | 核心作用 |
|:--|:--|:--|
| `calibration_common.proto` | 无 | 公共消息、错误码、长任务、文件、位姿、readiness |
| `vehicle_profile.proto` | `calibration_common.proto` | 车辆画像、能力声明、控制器选择、流程阶段配置 |
| `external_localization.proto` | `calibration_common.proto` | 真值参考接入、外部定位验证、结果写入 |
| `chassis_calibration.proto` | `calibration_common.proto`、`vehicle_profile.proto` | 底盘动作执行、遥测、验证、参数写入 |
| `control_calibration.proto` | `calibration_common.proto`、`vehicle_profile.proto` | 运控调优执行、遥测、验证、参数写入 |
| `sensor_calibration.proto` | `calibration_common.proto`、`vehicle_profile.proto` | 传感器任务、采集、参数、验证 |
| `workshop_orchestration.proto` | `calibration_common.proto`、`vehicle_profile.proto` | 整场会话编排、计划、审批、回滚、报告 |
| `transport_contract.proto` | 无 | WiFi6/TCP 通道、端口、帧头、帧号、payload 编码 |

总体依赖方向是：

```mermaid
flowchart LR
    A[calibration_common.proto] --> B[vehicle_profile.proto]
    A --> C[external_localization.proto]
    A --> D[chassis_calibration.proto]
    A --> E[control_calibration.proto]
    A --> F[sensor_calibration.proto]
    A --> G[workshop_orchestration.proto]
    H[transport_contract.proto]
    B --> D
    B --> E
    B --> F
    B --> G
```

---

## 5. 自动化标定车间完整流程

### 5.1 车间级前置条件

这一部分不属于“每台车都重复执行的主流程”，而是车间基础设施准备：

- 外部定位系统安装与调试完成
- 工位网络、时钟同步、数据库、文件存储就绪
- 标定板 / 标靶 / 地面参考目标 / 安全设施就绪
- Windows 车端代理和 Linux 侧各服务部署完成

### 5.2 单车级自动化标定主流程

```mermaid
flowchart TB
    A[车辆入场] --> B[创建 Session]
    B --> C[加载车辆画像与历史参数]
    C --> D[生成执行计划]
    D --> E[阶段0 真值参考接入与确认]
    E --> F[阶段1 整车预检]
    F --> G[阶段2 底盘标定]
    G --> H[阶段3 运控参数调优]
    H --> I[阶段4 传感器标定]
    I --> J[阶段5 整车联合验收]
    J --> K[阶段6 参数固化与归档]
    K --> L[车辆出场]
```

### 5.3 各阶段要点

#### 阶段 0：真值参考接入与确认

由 `external_localization.proto` 负责：

- 查询 readiness
- 切换工作模式
- 做参考位姿采集
- 执行真值源验证
- 给出验证摘要

这一步的本质不是“重新搭建外部定位系统”，而是：

> 确认车间里已经搭好的外部定位系统，当前这次会话能不能作为可信真值源使用。

#### 阶段 1：整车预检

由 `workshop_orchestration.proto` 统一编排：

- 服务在线检查
- 资源锁检查
- 工位安全检查
- 车辆 readiness 检查
- 传感器 / 底盘 / 运控 / 外部定位 readiness 检查

#### 阶段 2：底盘标定

由 `chassis_calibration.proto` 承担执行链路，Linux 做求解：

- 根据底盘类型选择动作原语
- 执行动作
- 采集遥测
- 求解底盘参数
- 做自动验收

#### 阶段 3：运控参数调优

由 `control_calibration.proto` 承担执行链路，Linux 做评估和迭代：

- 根据 `ControllerSelection` 决定横向 / 纵向控制器组合
- 加载一版参数
- 运行轨迹跟踪 / 速度阶跃 / 加减速 / 停车测试
- 回传遥测
- 计算误差与收敛指标
- 判断是否继续迭代或固化参数

#### 阶段 4：传感器标定

由 `sensor_calibration.proto` 承担采集与结果表达：

- 根据 `SensorProfile` 决定本轮要标哪些传感器
- 相机可只做内参、只做外参、或内外参都做
- 机械臂相机需区分 `EYE_IN_HAND` / `EYE_TO_HAND`
- 求解内参与外参
- 做自动验收

#### 阶段 5：整车联合验收

由 `workshop_orchestration.proto` 负责总控，联合各专项结果进行判断：

- 底盘参数是否有效
- 运控参数是否有效
- 传感器参数是否有效
- 真值参考是否可靠
- 若失败，回退到对应阶段重跑

#### 阶段 6：参数固化与归档

- 写入底盘参数
- 写入控制参数
- 写入传感器参数
- 记录文件摘要、版本号、时间戳
- 生成最终报告
- 归档所有产物与日志

---

## 6. 八个 Proto 在主流程中的协同方式

### 6.1 协同主图

```mermaid
flowchart LR
    A[vehicle_profile.proto\n车辆画像] --> B[workshop_orchestration.proto\n生成执行计划]
    B --> C[external_localization.proto\n真值参考接入]
    B --> D[chassis_calibration.proto\n底盘动作执行]
    B --> E[control_calibration.proto\n控制测试执行]
    B --> F[sensor_calibration.proto\n传感器采集执行]

    C --> B
    D --> B
    E --> B
    F --> B

    G[calibration_common.proto\n公共消息/状态/错误码] --> A
    G --> B
    G --> C
    G --> D
    G --> E
    G --> F
```

### 6.2 典型协同链路

一场完整会话通常按下面这个顺序协同：

1. `vehicle_profile.proto` 生成车辆画像
2. `workshop_orchestration.proto` 创建会话并生成阶段计划
3. `external_localization.proto` 完成真值参考接入与验证
4. `workshop_orchestration.proto` 运行车间预检
5. `chassis_calibration.proto` 执行底盘动作与回传遥测
6. `control_calibration.proto` 执行控制测试与回传遥测
7. `sensor_calibration.proto` 执行采集与提交参数结果
8. `workshop_orchestration.proto` 汇总结果，审批、回滚、归档

---

## 7. 当前协议设计已经明确的关键原则

### 7.1 总控只编排，不求解

`workshop_orchestration.proto` 不应该塞进底盘求解、相机求解、控制优化算法细节。

### 7.2 车端只执行，不决策

Windows 代理只负责：

- 接命令
- 执行动作
- 采集数据
- 写入参数
- 回传状态

不负责全局调度和复杂求解。

### 7.3 车辆画像先行

没有完整 `VehicleProfile`，就不应该进入任何专项标定任务。

### 7.4 流程阶段和模块类型分开表达

- `WorkflowStageType` 负责表达流程阶段
- `CalibrationModuleType` 负责表达模块归属

这样总控既能表达“当前在哪个阶段”，又能表达“这个阶段属于哪个模块”。

### 7.5 控制器必须区分横向与纵向

运控参数调优中，不能再把所有控制器混在一起。当前协议已经明确区分：

- `LATERAL_CONTROL`
- `LONGITUDINAL_CONTROL`

### 7.6 相机必须支持内参 / 外参可独立配置

当前协议已经支持：

- 只做相机内参
- 只做相机外参
- 内参与外参同时做

### 7.7 结果不能只给成功 / 失败

当前各专项都已经增加了：

- `ValidationSummary`
- `JobResult`

这意味着后续自动验收、报告、回滚都可以基于质量指标，而不是只看一个布尔值。

---

## 8. 冻结前建议补齐的小修补项

当前 8 个 proto 的主结构已经可以冻结，但为了减少后续返工，建议在冻结前补 4 类小修补。

### 8.1 给计划 / 结果 / 报告补统一 `metadata`

建议优先补到：

- `StagePlan`
- `StageResultSummary`
- `WorkshopReport`
- 各类 `ValidationSummary`
- 各类 `JobResult`

统一形式：

```proto
repeated .agv.calibration.common.KeyValuePair metadata = N;
```

这样后面想扩展指标、展示信息、附加标签时，不用再改结构。

### 8.2 给 external_localization.proto 补 `localization_source_id` / `workcell_zone_id`

这样未来扩展到多工位、多外部定位源时，不需要再改协议主结构。

### 8.3 给 sensor_calibration.proto 补统一 `reference_target`

建议增加一个通用参考目标消息，例如：

```proto
message CalibrationReferenceTarget {
  string reference_target_id = 1;
  string reference_target_type = 2;
  string description = 3;
}
```

然后让相机内参、传感器外参、手眼标定任务都使用统一的参考目标表达。

### 8.4 把角度单位策略写死

建议统一约定：

- **状态量 / 结果量 / 误差量 / 位姿量统一使用 rad**
- **人工输入更直观的命令量 / 限幅量可使用 deg**
- **字段名必须带单位后缀**，例如 `_rad`、`_deg`

---

## 9. 从 Proto 到 ROS2 的映射建议

这一步不是立即实现代码，而是给后续 ROS2 转换定规则。

### 9.1 msg

适合映射为 ROS2 `msg` 的内容：

- 公共结构体
- 遥测消息
- 参数结果消息
- 位姿 / 向量 / 摘要结构

例如：

- `RequestHeader`
- `JobStatus`
- `Pose3D`
- `ChassisTelemetry`
- `ControlTelemetry`
- `SensorCalibrationTelemetry`
- `VehicleSensorFrame`

### 9.2 srv

适合映射为 ROS2 `srv` 的内容：

- 短同步调用
- 模式切换
- 能力查询
- readiness 查询
- 当前生效参数查询

例如：

- `SetChassisWorkMode`
- `GetControlReadiness`
- `GetSensorCalibrationCapability`

### 9.3 action

适合映射为 ROS2 `action` 的内容：

- 底盘动作原语执行
- 外部定位验证任务
- 控制评估任务
- 传感器标定任务
- 整场车间会话执行

因为这些任务天然具备：

- 启动
- 持续反馈
- 查询进度
- 取消
- 完成结果

### 9.4 topic

适合映射为 ROS2 `topic` 的内容：

- 各类遥测流
- 各类事件流
- 外部定位连续位姿流
- 标定过程状态广播

---

## 10. 工程实现建议

### 10.1 目录建议

```text
proto/
├── calibration_common.proto
├── vehicle_profile.proto
├── external_localization.proto
├── chassis_calibration.proto
├── control_calibration.proto
├── sensor_calibration.proto
├── workshop_orchestration.proto
└── transport_contract.proto

services/
├── workshop_orchestrator/
├── vehicle_profile_manager/
├── external_localization_service/
├── chassis_calibration_service/
├── control_calibration_service/
├── sensor_calibration_service/
└── vehicle_agent_windows/

algorithms/
├── external_reference_solver/
├── chassis_solver/
├── control_tuner/
└── sensor_solver/

reports/
configs/
logs/
```

### 10.2 实现优先级建议

建议按下面顺序推进：

1. 先冻结 8 个 proto
2. 再设计 ROS2 的 msg / srv / action 对应关系
3. 再画节点架构图和 topic / service / action 拓扑
4. 再实现总控状态机
5. 再逐个接入专项服务和车端代理

### 10.3 最容易踩坑的地方

- 把总控写成求解器
- 把 Windows 代理写得过重
- 不先做车辆画像，直接开始下发任务
- 相机内外参逻辑混在一起
- 横向 / 纵向控制器不分开处理
- 角度单位在不同层乱用
- 报告只记录成功 / 失败，不记录质量指标和版本号

---

## 11. 总结

当前这套 8 个 proto 已经不再是“概念方案”，而是一套接近可冻结的自动化标定车间协议主干。

它们共同支撑的不是单个算法模块，而是完整的一条自动化流程：

**车辆画像 → 会话创建 → 真值参考接入 → 车间预检 → 底盘标定 → 运控调优 → 传感器标定 → 整车联合验收 → 参数固化 → 结果归档**

其中：

- `calibration_common.proto` 提供统一地基
- `vehicle_profile.proto` 决定“这台车是谁、支持什么、这次做什么”
- `external_localization.proto` 提供可信真值参考
- `chassis_calibration.proto` 负责底盘动作执行与参数验证
- `control_calibration.proto` 负责横纵向控制器调优执行
- `sensor_calibration.proto` 负责多传感器采集、求解与参数表达
- `workshop_orchestration.proto` 负责总流程编排、审批、回滚与归档
- `transport_contract.proto` 固定 WiFi6/TCP 通道、端口、帧头、帧号和 payload 编码

只要把冻结前的小修补项补齐，这套协议就可以正式进入下一阶段：

**ROS2 接口映射、节点架构设计、C++ 服务实现。**
