# 车间总控编排模块

这是自动化标定车间的总编排说明文档。这个 README 需要跟着代码一起更新，用来保留当前流程设计、任务粒度和模块职责。

## 目标

总控只负责“编排”和“流程治理”，不直接承载专项标定细节。专项细节分别由独立模块完成：

- 底盘标定
- 运控参数标定
- 传感器内参标定
- 传感器外参标定
- 手眼标定
- 外部定位 / 真值接入

## 当前架构

### 1. 车间总控

`workshop_orchestrator_v2` 负责：

- 创建会话
- 生成执行计划
- 启动整场执行
- 暂停 / 恢复 / 取消
- 人工确认
- 阶段审批
- 报告生成与查询

### 2. WiFi6 链路调度

车间工控机到车端电脑只使用一个统一 WiFi6/TCP 入口，默认是：

```text
wifi6_vehicle_host: 127.0.0.1
wifi6_vehicle_port: 9000
```

总控预检时会在同一个 TCP endpoint 上依次检查四个逻辑通道：

| 逻辑通道 | 帧类型 | 作用 |
|---|---|---|
| 底盘 `CHASSIS` | `1 -> 2` | 检查底盘 agent、急停、运动安全状态 |
| 运控 `CONTROL` | `11 -> 12` | 检查轨迹执行器、车辆反馈、控制输出 |
| 传感器 `SENSOR` | `21 -> 22` | 检查车端传感器采集和数据流状态 |
| 外部真值 `EXTERNAL_POSE` | `31 -> 32` | 检查外部真值位姿能否通过 WiFi6 推入车端 |

这里的“四条链路”是协议里的逻辑通道，不是四个物理端口。仿真环境中如果底盘、运控、传感器、外部真值仍由不同脚本承载，可以启动 `vehicle_wifi6_gateway_sim.py`，由它监听 `9000` 并转发到内部后端端口。

### 3. 任务选择方式

当前设计是“**由 UI 或上层显式选择要执行的阶段**”。

如果 `requested_tasks` 为空，总控会按车辆能力自动生成最小计划；
如果 `requested_tasks` 不为空，总控会优先按用户显式选择的阶段生成计划。

## 当前执行主线

当前主线为：创建会话 -> 生成计划 -> 执行预检 -> 阶段执行 -> 提交/验收 -> 生成报告。

其中阶段执行会按会话配置和车辆画像决定是否加入：

- 外部参考接入
- 底盘标定
- 运控参数标定
- 传感器内参标定
- 传感器外参标定
- 手眼标定

## 当前流程粒度

现在总控层已经支持“按阶段选择”，但细分方法仍由专项协议和专项服务承载。

### 最小联调闭环

当前仓库里可以先验证下面这条最小链路：

1. 启动 `vehicle_profile_manager`
2. 启动 `external_localization_service`
3. 启动 `workshop_orchestrator_v2`
4. 创建会话并自动生成计划
5. 触发 `execute_session`
6. 走完外部真值校核并生成报告

这条链路现在是最小可验证闭环，后续再逐步补 chassis / control / sensor 的服务端实现。


## 按模块拆分后的代码位置

### 模块接口总表

| 模块 | 职责 | 输入 | 输出 | 实现位置 |
|---|---|---|---|---|
| 车间总控 `workshop_orchestrator_v2` | 管会话、生成计划、调度执行、处理人工确认/审批、生成报告 | `VehicleProfile`、`WorkshopSessionConfig`、`RequestedCalibrationTask`、`StagePlan`、`StageResultSummary` | `WorkshopSession`、`WorkshopPrecheckResponse`、`WorkshopReport`、`WorkshopEvent` | `src/core/agv_calib_core/workshop_orchestrator/src/main.cpp`<br>`src/core/agv_calib_core/workshop_orchestrator/src/workshop_orchestrator_v2_node.cpp`<br>`src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/workshop_orchestrator_v2_node.hpp`<br>`src/core/agv_calib_core/workshop_orchestrator/src/plan_builder.cpp` / `include/workshop_orchestrator_v2/plan_builder.hpp`<br>`src/core/agv_calib_core/workshop_orchestrator/src/precheck_runner.cpp` / `include/workshop_orchestrator_v2/precheck_runner.hpp`<br>`src/core/agv_calib_core/workshop_orchestrator/src/report_builder.cpp` / `include/workshop_orchestrator_v2/report_builder.hpp`<br>`src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/types.hpp` |
| 外部定位 / 真值接入 `external_localization_service` | goal 校验、外部参考接入、真值校核、结果回填 | `ExecuteExternalLocalizationTask::Goal`、`WorkshopSession`、`StagePlan` | `StageResultSummary`、`ExecuteExternalLocalizationTask::Result` | `src/core/agv_calib_core/external_localization_service/include/external_localization_service/external_reference_executor.hpp`<br>`src/core/agv_calib_core/external_localization_service/src/external_reference_executor.cpp` |
| 底盘标定客户端 | readiness 检查、底盘动作原语任务下发、结果翻译 | `WorkshopSession`、`StagePlan` | `StageResultSummary`、底盘专项 goal / result | `src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/chassis_gateway_client.hpp`<br>`src/core/agv_calib_core/workshop_orchestrator/src/chassis_gateway_client.cpp` |
| 运控参数标定客户端 | readiness 检查、控制评估任务下发、轨迹组装、结果翻译 | `WorkshopSession`、`StagePlan`、`stage.metadata` 中的轨迹与参数 | `StageResultSummary`、运控专项 goal / result | `src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/control_gateway_client.hpp`<br>`src/core/agv_calib_core/workshop_orchestrator/src/control_gateway_client.cpp` |
| 传感器标定客户端 | readiness 检查、传感器任务路由、结果翻译 | `WorkshopSession`、`StagePlan`、`stage.metadata` 中的传感器信息 | `StageResultSummary`、传感器专项 goal / result | `src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/sensor_gateway_client.hpp`<br>`src/core/agv_calib_core/workshop_orchestrator/src/sensor_gateway_client.cpp` |
| 外部定位客户端 | readiness 检查、外部参考接入任务下发、结果接入总控 | `WorkshopSession`、`StagePlan` | `StageResultSummary`、外部定位专项 goal / result | `src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/external_localization_client.hpp`<br>`src/core/agv_calib_core/workshop_orchestrator/src/external_localization_client.cpp` |

### 1. 车间总控模块 `workshop_orchestrator_v2`

**职责**
- 管会话生命周期：创建、查询、执行、暂停、恢复、报告
- 按车辆画像和会话配置生成阶段计划
- 调度各专项模块执行
- 处理人工确认和审批

**输入**
- `VehicleProfile`
- `WorkshopSessionConfig`
- `RequestedCalibrationTask`
- `StagePlan`
- `StageResultSummary`

**输出**
- `WorkshopSession`
- `WorkshopPrecheckResponse`
- `WorkshopReport`
- `WorkshopEvent`

**实现位置**
- 节点入口：`src/core/agv_calib_core/workshop_orchestrator/src/main.cpp`
- 总控节点：`src/core/agv_calib_core/workshop_orchestrator/src/workshop_orchestrator_v2_node.cpp`
- 总控头文件：`src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/workshop_orchestrator_v2_node.hpp`
- 阶段规划：`src/core/agv_calib_core/workshop_orchestrator/src/plan_builder.cpp` / `include/workshop_orchestrator_v2/plan_builder.hpp`
- 预检逻辑：`src/core/agv_calib_core/workshop_orchestrator/src/precheck_runner.cpp` / `include/workshop_orchestrator_v2/precheck_runner.hpp`
- 报告生成：`src/core/agv_calib_core/workshop_orchestrator/src/report_builder.cpp` / `include/workshop_orchestrator_v2/report_builder.hpp`
- 共享类型：`src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/types.hpp`

### 2. 外部定位 / 真值接入模块 `external_localization_service`

**职责**
- 执行外部真值接入前的 goal 校验
- 执行外部参考接入 / 真值校核任务
- 把专项执行结果映射成总控可用的阶段结果

**输入**
- `ExecuteExternalLocalizationTask::Goal`
- `WorkshopSession`
- `StagePlan`

**输出**
- `StageResultSummary`
- `ExecuteExternalLocalizationTask::Result`

**实现位置**
- 执行器头文件：`src/core/agv_calib_core/external_localization_service/include/external_localization_service/external_reference_executor.hpp`
- 执行器实现：`src/core/agv_calib_core/external_localization_service/src/external_reference_executor.cpp`

### 3. 底盘标定客户端

**职责**
- 向底盘专项服务发起 readiness 检查
- 发送底盘动作原语任务
- 将底盘结果翻译成总控阶段结果

**输入**
- `WorkshopSession`
- `StagePlan`

**输出**
- `StageResultSummary`
- 底盘专项 goal / result

**实现位置**
- 头文件：`src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/chassis_gateway_client.hpp`
- 实现：`src/core/agv_calib_core/workshop_orchestrator/src/chassis_gateway_client.cpp`

### 4. 运控参数标定客户端

**职责**
- 向运控专项服务发起 readiness 检查
- 发送控制评估任务
- 从 `stage.metadata` 解析轨迹点并组装 goal
- 将控制结果翻译成总控阶段结果

**输入**
- `WorkshopSession`
- `StagePlan`
- `stage.metadata` 中的轨迹与参数信息

**输出**
- `StageResultSummary`
- 运控专项 goal / result

**实现位置**
- 头文件：`src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/control_gateway_client.hpp`
- 实现：`src/core/agv_calib_core/workshop_orchestrator/src/control_gateway_client.cpp`

### 5. 传感器标定客户端

**职责**
- 向传感器专项服务发起 readiness 检查
- 处理相机内参、传感器外参、手眼标定等任务入口
- 根据阶段与元数据选择具体传感器标定任务类型
- 将传感器结果翻译成总控阶段结果

**输入**
- `WorkshopSession`
- `StagePlan`
- `stage.metadata` 中的传感器 ID、样本数、板卡 ID、基准坐标系等信息

**输出**
- `StageResultSummary`
- 传感器专项 goal / result

**实现位置**
- 头文件：`src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/sensor_gateway_client.hpp`
- 实现：`src/core/agv_calib_core/workshop_orchestrator/src/sensor_gateway_client.cpp`

### 6. 外部定位客户端

**职责**
- 向外部定位专项服务发起 readiness 检查
- 发送外部参考接入任务
- 将外部定位结果交给总控执行链路

**输入**
- `WorkshopSession`
- `StagePlan`

**输出**
- `StageResultSummary`
- 外部定位专项 goal / result

**实现位置**
- 头文件：`src/core/agv_calib_core/workshop_orchestrator/include/workshop_orchestrator_v2/external_localization_client.hpp`
- 实现：`src/core/agv_calib_core/workshop_orchestrator/src/external_localization_client.cpp`

### 7. 外部定位专项执行骨架

**职责**
- 作为外部定位服务侧的专项执行器骨架
- 封装 goal 校验和结果回填
- 将专项逻辑从总控里剥离出去

**输入**
- `ExecuteExternalLocalizationTask::Goal`
- `ExecuteExternalLocalizationTask::Result`

**输出**
- `StageResultSummary`

**实现位置**
- 头文件：`src/core/agv_calib_core/external_localization_service/include/external_localization_service/external_reference_executor.hpp`
- 实现：`src/core/agv_calib_core/external_localization_service/src/external_reference_executor.cpp`

## 专项任务清单

这部分是给 UI 和后续维护看的，目的是把“总控阶段”下面真正会出现的专项任务说清楚。

### 1. 外部定位 / 真值接入

**对应代码**
- `src/core/agv_calib_core/workshop_orchestrator/src/plan_builder.cpp`
- `src/core/agv_calib_core/workshop_orchestrator/src/external_localization_client.cpp`
- `src/core/agv_calib_core/external_localization_service/src/external_reference_executor.cpp`

**当前任务**
- 外部真值参考接入
- 外部定位 readiness 检查
- 真值校核 / 接入确认

**典型输入**
- 位置参考源 ID
- 工位区域 ID
- 静态/动态采样数量
- 位置标准差、yaw 标准差、跟踪丢失阈值、时间同步阈值

### 2. 底盘标定

**对应代码**
- `src/core/agv_calib_core/workshop_orchestrator/src/plan_builder.cpp`
- `src/core/agv_calib_core/workshop_orchestrator/src/chassis_gateway_client.cpp`

**当前任务**
- 底盘 readiness 检查
- 直线动作原语执行
- 标定后刹停/收尾

**说明**
- 目前总控层默认是“底盘标定”这一阶段
- 具体底盘形态由车辆画像决定，例如阿克曼、差速、单舵轮、多舵轮
- 当前最小流实现里，底盘阶段的动作原语以 `straight_line` 为主

### 3. 运控参数标定

**对应代码**
- `src/core/agv_calib_core/workshop_orchestrator/src/plan_builder.cpp`
- `src/core/agv_calib_core/workshop_orchestrator/src/control_gateway_client.cpp`

**当前任务**
- 运控 readiness 检查
- 控制评估任务下发
- 轨迹点组装与参数注入
- 结果回收与翻译

**说明**
- 总控当前只暴露“运控参数调优”这一阶段
- 具体执行内容由 `stage.metadata` 中的轨迹和控制参数决定
- 代码里已支持按控制轴和算法组织参数，例如横向/纵向、PID/MPC/LQR/Pure Pursuit

### 4. 传感器内参标定

**对应代码**
- `src/core/agv_calib_core/workshop_orchestrator/src/plan_builder.cpp`
- `src/core/agv_calib_core/workshop_orchestrator/src/sensor_gateway_client.cpp`

**当前任务**
- 相机内参标定
- IMU 内参标定

**典型输入**
- 传感器 ID
- 标定板 ID
- 所需图像数
- 静态段数量
- 运动段数量
- 超时时间

### 5. 传感器外参标定

**对应代码**
- `src/core/agv_calib_core/workshop_orchestrator/src/plan_builder.cpp`
- `src/core/agv_calib_core/workshop_orchestrator/src/sensor_gateway_client.cpp`

**当前任务**
- 相机外参标定
- 2D 激光雷达外参标定
- 3D 激光雷达外参标定
- IMU 外参标定

**典型输入**
- 传感器 ID
- base_link / 基准坐标系
- 样本数
- 参考目标
- 超时时间

### 6. 手眼标定

**对应代码**
- `src/core/agv_calib_core/workshop_orchestrator/src/plan_builder.cpp`
- `src/core/agv_calib_core/workshop_orchestrator/src/sensor_gateway_client.cpp`

**当前任务**
- 眼在手上（EYE_IN_HAND）
- 眼在手外（EYE_TO_HAND）

**典型输入**
- 相机 ID
- 机械臂 ID
- 位姿数量
- 参考目标
- 超时时间

## 当前接口

- `/workshop_v2/create_session`
- `/workshop_v2/get_session`
- `/workshop_v2/get_report`
- `/workshop_v2/execute_session` action
- `/workshop_v2/events` topic
- `/workshop_v2/pause_session`
- `/workshop_v2/resume_session`
- `/workshop_v2/acknowledge_manual_step`
- `/workshop_v2/approve_stage_result`

## 维护规则

以后只要代码里的流程、阶段、任务选择方式或模块职责发生变化，就要同步重写这份 README，让它始终反映当前真实实现，而不是历史版本。

## 下一步

1. 继续把各专项执行接到真实 gateway / service
2. 让 UI 的任务选择和总控阶段保持一致
3. 让 README 与实际实现保持同步更新
