# 运控参数标定算法模板合同

本文档固定运控参数标定算法与车间系统之间的输入、输出和交接边界。具体 PID、MPC、LQR、Pure Pursuit 求解算法由算法工程师实现；本仓库只提供模板、数据输入合同和车间电脑侧交接流程。

## 运行边界

运控标定在真实车间中的边界如下：

- 车间电脑负责创建会话、下发运控评估任务、采集数据、运行标定算法和生成参数交接包。
- 车端 Windows agent 只负责执行评估动作、回传执行结果和遥测。
- 外部真值定位来自车间四角 LiDAR + 车端标定球系统，写入 `truth_trajectory.csv`。
- 参数写入车辆这一步当前只生成交接包，不直接调用车端写参接口。

## 算法输入

运控算法应读取 `dataset_index.yaml` 转换出的 `data_input.*` 参数，或直接读取 `dataset_index.yaml` 中的文件索引。

必需输入：

- `data_input.control_evaluation_data_files`
- `data_input.reference_signal_files`
- `data_input.chassis_response_files`
- `data_input.truth_trajectory_files`

对应现场 CSV 协议见：

```bash
src/site_deployment/workshop_control_calibration_real/control_csv_contract.md
```

真实采集入口：

```bash
src/site_deployment/workshop_control_calibration_real/capture_control_session.py
```

合成数据 smoke 入口：

```bash
src/site_deployment/workshop_control_calibration_real/replay_control_smoke.py
```

## C++ 模板入口

ROS 侧模板入口：

- `src/core/agv_calib_core/control_calibration_service/include/control_calibration_service/control_calibration_algorithms.hpp`
- `src/core/agv_calib_core/control_calibration_service/src/control_calibration_algorithm_template.cpp`
- `src/core/agv_calib_core/control_calibration_service/src/pid_control_calibration_algorithm.cpp`
- `src/core/agv_calib_core/control_calibration_service/src/mpc_control_calibration_algorithm.cpp`
- `src/core/agv_calib_core/control_calibration_service/src/lqr_control_calibration_algorithm.cpp`
- `src/core/agv_calib_core/control_calibration_service/src/pure_pursuit_control_calibration_algorithm.cpp`

算法实现应主要修改具体算法文件，不应改 node 层通信代码。

## 算法输出

算法输出文件建议固定为：

```bash
<session_dir>/control/estimated_params.yaml
```

模板见：

```bash
src/site_deployment/workshop_control_calibration_real/config/control_estimated_params_template.yaml
```

核心字段：

- `schema_version`: 当前为 `1`。
- `session_id`: 本次会话 ID。
- `vehicle_id`: 车辆 ID，必须与 `dataset_index.session.vehicle_id` 一致。
- `chassis_type`: `ackermann`、`differential`、`single_steer_wheel` 或 `multi_steer_wheel`。
- `control_axis`: `lateral_control`、`longitudinal_control` 或 `combined`。
- `controller_algorithm`: `pid`、`mpc`、`lqr` 或 `pure_pursuit`。
- `control_role`: 控制器角色，例如 `path_tracking_outer_loop`、`speed_loop`、`heading_loop`、`yaw_rate_loop`、`steering_angle_inner_loop`。
- `parameter_version`: 算法输出的参数版本号。
- `estimated_params`: 算法估计出的参数。
- `quality.data_quality_passed`: 数据质量是否达标。
- `quality.suitable_for_commit`: 是否允许进入待审批包。
- `quality.validation_summary`: 验收指标摘要。

只有 `data_quality_passed=true` 且 `suitable_for_commit=true` 的输出，才允许生成待审批包。

算法和控制轴约束：

- `pid` 可以用于纵向速度、差速航向/角速度、单舵轮/多舵轮/阿克曼舵角内环等回路。
- 使用 `pid` 时必须填写明确的 `control_role` 和 `loop_name`，例如 `speed_loop/speed`、`heading_loop/heading`、`yaw_rate_loop/yaw_rate`、`steering_angle_inner_loop/steering_angle`。
- `combined` 且使用 `pid` 时，必须使用 `pid_loops` 列表分别描述每个 PID 回路，不能用一个含糊的 PID 表达横纵向联合参数。
- 横向路径跟踪外环仍推荐按现场控制器选择 `pure_pursuit`、`lqr` 或 `mpc`；如果现场确实是 PID 外环，则用 `control_axis: lateral_control` 并明确 `control_role` 和 `loop_name`。

## 底盘类型默认回路

差速轮推荐：

- `path_tracking_outer_loop`: `pure_pursuit` / `lqr` / `mpc`，输出线速度和角速度参考。
- `speed_loop`: `pid`，整车线速度回路。
- `yaw_rate_loop` 或 `heading_loop`: `pid`，角速度或航向回路。
- `wheel_speed_inner_loop`: `pid`，左右轮速度内环。

单舵轮推荐：

- `path_tracking_outer_loop`: `pure_pursuit` / `lqr` / `mpc`，输出目标速度和目标舵角。
- `speed_loop`: `pid`，驱动轮速度或整车速度回路。
- `steering_angle_inner_loop`: `pid`，舵角位置内环。

多舵轮推荐：

- `path_tracking_outer_loop`: `pure_pursuit` / `lqr` / `mpc`，输出整车速度、角速度或模块目标。
- `wheel_speed_inner_loop`: `pid`，各驱动轮速度内环。
- `module_steering_inner_loop`: `pid`，各舵轮模块角度内环。

阿克曼推荐：

- `path_tracking_outer_loop`: `pure_pursuit` / `lqr` / `mpc`，输出目标曲率或目标前轮转角。
- `speed_loop`: `pid`，纵向速度回路。
- `steering_angle_inner_loop`: `pid`，转角执行器内环。

## 参数交接

生成待审批包：

```bash
python3 src/site_deployment/workshop_control_calibration_real/stage_control_parameter_commit.py \
  --dataset-index /data/agv_calib/site_a/session_001/dataset_index.yaml \
  --estimated-params /data/agv_calib/site_a/session_001/control/estimated_params.yaml
```

输出：

```bash
/data/agv_calib/site_a/session_001/control/pending_control_commit.yaml
```

审批交接：

```bash
python3 src/site_deployment/workshop_control_calibration_real/approve_control_pending_parameters.py \
  /data/agv_calib/site_a/session_001/control/pending_control_commit.yaml \
  --operator-id operator_001
```

输出：

```bash
/data/agv_calib/site_a/session_001/control/approved_control_parameter_handoff.yaml
```

`dataset_index.yaml` 的 `metadata` 会记录运控算法输出、待审批包、审批状态和交接包路径。总控 report 会把这些文件加入 `report_files`。

## 验收建议

真实算法至少应在 `quality.validation_summary` 写入：

- 横向误差均方根。
- 航向误差均方根。
- 速度误差均方根。
- 超调比例。
- 收敛时间。
- 停车位置误差。
- 最大 jerk。
- 控制饱和占比。
- 自动验收是否通过。

模板不会替算法做通过判定。算法工程师需要根据现场工艺要求设置阈值，并明确写出 `suitable_for_commit`。
