# 真实底盘驱动适配器接入说明

本文档定义 Windows 车端 agent 对接真实底盘 SDK、CAN、PLC 或厂商控制器的边界。

## 接入位置

协议层已经固定，真实底盘只需要实现适配器：

- 接口文件：`include/chassis_driver_adapter.hpp`
- 厂商模板：`include/vendor_chassis_driver_template.hpp`
- 调用入口：`include/chassis_handler.hpp`

`ChassisHandler` 默认使用安全空实现。没有注入真实适配器时：

- readiness 返回未就绪。
- 动作原语请求会被拒绝。
- 紧急制动返回无法确认执行。

这样可以避免未接硬件时误报“底盘已就绪”。

## 必须实现的方法

真实适配器需要实现 `ChassisDriverAdapter` 的三个方法：

```cpp
ChassisReadinessResponse get_readiness(const nlohmann::json& req);
ChassisJobResult execute_motion_primitive(const MotionPrimitiveRequest& req);
StandardResponse emergency_brake(const nlohmann::json& req);
```

## readiness 要检查什么

`get_readiness` 必须从真实底盘读取并回填：

- 车端代理服务是否在线：`agent_ready`
- 厂商驱动、CAN、PLC 或控制器是否在线：`chassis_driver_online`
- 运动控制是否允许执行动作：`motion_control_ready`
- 急停是否释放：`estop_released`
- 当前车辆是否安全可移动：`vehicle_safe_to_move`
- 底盘遥测是否可用：`telemetry_available`
- 检查时间戳：`checked_timestamp_us`

任一安全条件不满足时，不能返回可执行状态。

## 动作执行必须做什么

`execute_motion_primitive` 必须按这个顺序处理：

1. 校验 `vehicle_id`、`request_id`、动作类型和动作参数。
2. 获取任务互斥锁，同一时刻只允许一个底盘动作。
3. 再次检查急停、使能、低速标定模式、驱动在线和运动区域安全状态。
4. 把 `MotionPrimitiveRequest` 转成真实底盘控制器命令。
5. 执行动作，并持续监控急停、断连、超时、驱动故障和人工中断。
6. 动作结束后停车或刹停。
7. 保存底盘遥测、命令日志、故障日志和执行摘要。
8. 返回 `ChassisJobResult`。

动作执行失败时必须返回 `success=false`，并写明 `error_code` 和 `message`。

## 支持的动作原语

当前协议支持：

- `STRAIGHT_LINE`
- `ARC`
- `IN_PLACE_ROTATION`
- `STEERING_SWEEP`
- `LATERAL_TRANSLATION`
- `DIAGONAL_MOTION`
- `MODULE_ALIGNMENT`
- `COORDINATED_STEERING`

真实车辆不支持的动作必须返回 `UNSUPPORTED_CAPABILITY`，不能静默忽略。

## 结果字段要求

`ChassisJobResult` 必须填写：

- `success`
- `error_code`
- `message`
- `job_id`
- `data_quality_passed`
- `suitable_for_commit`
- `recommended_parameter_version`
- `estimated_straight_line_bias`
- `validation_summary`
- `artifacts`

底盘动作执行完成但算法结果不建议提交时，可以返回：

```text
success=true
data_quality_passed=true
suitable_for_commit=false
```

没有真实算法结果时，不能返回 `suitable_for_commit=true`。

## 产物落盘

真实适配器或现场采集程序应至少保存：

- 底盘遥测 CSV
- 执行器命令 CSV
- 外部真值轨迹 CSV
- 动作执行诊断 JSON

CSV 字段协议见：

```text
src/site_deployment/workshop_chassis_calibration_real/chassis_csv_contract.md
```

这些文件应通过 `artifacts` 返回，并由车间电脑侧生成或合并到 `dataset_index.yaml`。

## 主程序接入方式

现场接入时，建议复制 `VendorChassisDriverTemplate`，实现为厂商专用类，然后在 `main.cpp` 中注入：

```cpp
#include "my_vendor_chassis_driver.hpp"

vaw::MyVendorChassisDriver driver;
vaw::ChassisHandler chassis_handler(&driver);
```

不要在 TCP server、gateway server 或 frame codec 中直接调用厂商 SDK。
