bugbugbugbugbugbug

下面给出一份可直接替换到原工程、逐行对照的完整重构方案。
为了便于阅读，我把 5 个“软破坏点”全部拆成 4 个层次：

1. 问题简述（一句话）
2. 现场症状（如何在日志/现象中识别）
3. 根因分析（一句话）
4. 可落地的最小修补代码（Copy-Paste 即可）

1. 状态机“顺序跳步”——典型软破坏

最小修补代码（保持原文件名）

// 文件: state_machine.cpp
// 函数: void updateState()

switch (state) {
/* ---- 原来缺失 break 的 3 个 case ---- */
case 3:
    if (g_last_aruco_id == 1) {               // 等待 1 号标签
        sc.Move(0, 0, PID_Yaw.update(M_PI_2 - imu.yaw));
        state = 4;
    }
    break;   // <-- 补上

case 4:
    if (g_last_aruco_id == 2) {               // 等待 2 号标签
        sc.Move(0, 0, PID_Yaw.update(0.0 - imu.yaw));
        state = 5;
    }
    break;   // <-- 补上

case 8:
    doSomething();
    break;   // <-- 补上
}

提示：

1. 如果 3、4 两阶段原本没有任何业务逻辑，请把上面 if (g_last_aruco_id …) 作为最小业务保留，防止空 case 再次成为“软破坏”。
2. 若是 C++17+，可用 [[fallthrough]]; 显式说明有意下落。

2. 障碍避让分支被“挖空”——死分支 + 难以察觉

最小修补代码（完整 0→1→2 闭环）

// 文件: obstacle_avoid.cpp
// 变量: int phase = 0;   // 0:接近 1:绕行 2:回正
// 常量: const double SAFE_MARGIN = 0.35;   // 侧移上限
//        const double THRESHOLD   = 0.05;   // 通过门槛

switch (phase) {
case 0:   // 接近障碍
    if (laser.min_dist < SAFE_MARGIN) {
        sc.Move(0, 0, 0);          // 立即停车
        phase = 1;                 // 推进到绕行
    } else {
        sc.Move(0.3, 0, 0);        // 直走
    }
    break;

case 1:   // 绕行（侧移）
    if (fabs(laser.right - SAFE_MARGIN) < THRESHOLD) {
        sc.Move(0, 0, 0);          // 侧移到位
        phase = 2;
    } else {
        double e = SAFE_MARGIN - laser.right;
        sc.Move(0, PID_Lat.update(e), 0);   // PID 横向控制
    }
    break;

case 2:   // 回正（恢复航向）
    static double target_yaw = imu.yaw;   // 记录进入障碍前的航向
    double yaw_err = normalizeAngle(target_yaw - imu.yaw);
    if (fabs(yaw_err) < 0.05) {
        phase = 0;                   // 闭环完成
    } else {
        sc.Move(0.1, 0, PID_Yaw.update(yaw_err));
    }
    break;
}

3. 角度单位“混淆注入”——弧度/度混用

最小修补代码（全链路弧度化）

// 文件: common.h
constexpr double deg2rad(double d) { return d * M_PI / 180.0; }
constexpr double rad2deg(double r) { return r * 180.0 / M_PI; }

// 文件: controller.cpp
const double TARGET_YAW = deg2rad(90.0);   // 90° -> π/2
double err = TARGET_YAW - imu.yaw;         // 全程弧度
if (fabs(err) > deg2rad(3.0)) {            // 容差 3°
    sc.Move(0, 0, PID_Yaw.update(err));
}

彻底做法：

1. 删除所有裸写的 angle * 180 / M_PI 或 angle / 180 * M_PI。
2. 在 CI 中加一条正则检查：grep -R '180\s*/\s*M_PI\|M_PI\s*/\s*180' src/ 直接报错。

4. “阻塞式”旋转回转——硬阻塞 + 无让步

最小修补代码（非阻塞子状态机）

// 文件: turn_logic.cpp
// 变量: bool rotating = false;
//        double target_yaw = 0.0;

switch (state) {
case 2:   // 进入旋转阶段
    if (!rotating) {
        target_yaw = normalizeAngle(imu.yaw + M_PI_2);  // +90°
        rotating = true;
    }
    double err = normalizeAngle(target_yaw - imu.yaw);
    if (fabs(err) > 0.05) {
        sc.Move(0, 0, PID_Yaw.update(err));
    } else {
        rotating = false;
        state = 3;   // 进入下一阶段
    }
    break;
}

5. ArUco 触发条件写反——误触发转向

最小修补代码（精确匹配 + 巡航补位）

// 文件: aruco_trigger.cpp
// 全局: int expected_id = 0;   // 0→1→2 递增，由上层状态机维护

switch (state) {
case 3:
    if (g_last_aruco_id == expected_id) {
        sc.Move(0, 0, PID_Yaw.update(expected_yaw - imu.yaw));
        state = 4;
        ++expected_id;           // 推进到下一张标签
    } else {
        // 未检测到目标标签 → 继续巡航
        sc.Move(0.3, 0, PID_Yaw.update(0.0 - imu.yaw));
    }
    break;
}

一键替换清单

把以上 6 个片段整体替换后，CI 跑一次静态分析（clang-tidy + cppcheck），即可彻底消除这 5 个软破坏点。