#![allow(clippy::unwrap_used, clippy::expect_used)]

use std::sync::Mutex;

pub mod report {
    //! 报告与产物写出：CSV / TOML / JSON / Markdown（可选 SVG）。
    //!
    //! 产物布局（`--out-dir`）：
    //!
    //! | 文件 | 内容 |
    //! | --- | --- |
    //! | `trials.csv` | 全部候选：增益 + 指标 + 成本 + 判定（可用任意表格软件复盘） |
    //! | `best.toml` | 可直接粘贴进 `chassis.toml` 的 `[[motor]]` 片段 |
    //! | `best-trace.csv` | 最优增益的完整步响应轨迹 |
    //! | `report.md` | 人类可读总结：设置、Top-N、结论与注意事项 |
    //! | `summary.json` | 机器可读结果（CI / 后续工具消费） |
    //! | `best.svg` | 步响应三联图（仅 `--features plot`） |

    use std::fmt::Write as _;
    use std::path::{Path, PathBuf};

    use experiment::{Scenario, Trace};
    use serde::Serialize;
    use sim_harness::LoopLimits;

    use experiment::StepMetrics;
    use tuning::gains::GainSpace;
    use tuning::search::{Ranked, SearchConfig, Trial, verdict_hint};

    /// 报告写出错误。
    #[derive(Debug, thiserror::Error)]
    pub enum ReportError {
        /// 目录创建或文件写入失败。
        #[error("io error at {path}: {source}")]
        Io {
            /// 出错路径。
            path: PathBuf,
            /// 底层错误。
            source: std::io::Error,
        },
        /// CSV 写出失败。
        #[error("csv error: {0}")]
        Csv(#[from] csv::Error),
        /// JSON 写出失败。
        #[error("json error: {0}")]
        Json(#[from] serde_json::Error),
        /// TOML 写出失败。
        #[error("toml error: {0}")]
        Toml(#[from] toml::ser::Error),
        /// 没有可用的最优结果。
        #[error("no feasible trial to report")]
        NoBest,
        /// SVG 绘图失败（仅 `--features plot`）。
        #[error("plot error: {0}")]
        Plot(String),
    }

    fn io(path: impl Into<PathBuf>, source: std::io::Error) -> ReportError {
        ReportError::Io { path: path.into(), source }
    }

    /// 生成产物所需的上下文。
    #[derive(Debug, Clone)]
    pub struct ReportContext {
        /// 输出目录。
        pub out_dir: PathBuf,
        /// 本次搜索使用的参数空间。
        pub space: GainSpace,
        /// 搜索配置。
        pub config: SearchConfig,
        /// 场景。
        pub scenario: Scenario,
        /// 限幅。
        pub limits: LoopLimits,
        /// 后端描述（`sim(...)` / `bench(...)`）。
        pub backend: String,
        /// 目标轮名（写回 TOML 用）。
        pub motor_name: String,
        /// 验收阈值：最大超调（%）。
        pub max_overshoot_pct: f32,
        /// 验收阈值：最大稳态误差（%）。
        pub max_ss_error_pct: f32,
        /// 最优增益的轨迹（有则写 `best-trace.csv`）。
        pub best_trace: Option<Trace>,
    }

    /// 写出全部产物，返回写出的文件列表。
    ///
    /// # Errors
    ///
    /// 目录创建、文件写入或序列化失败时返回 [`ReportError`]。
    pub fn write_reports(
        ctx: &ReportContext,
        ranked: &Ranked,
    ) -> Result<Vec<PathBuf>, ReportError> {
        std::fs::create_dir_all(&ctx.out_dir).map_err(|e| io(&ctx.out_dir, e))?;
        let mut written = Vec::new();

        let trials_path = ctx.out_dir.join("trials.csv");
        write_trials_csv(&trials_path, &ranked.trials)?;
        written.push(trials_path);

        let best_path = ctx.out_dir.join("best.toml");
        write_best_toml(&best_path, ctx, &ranked.best)?;
        written.push(best_path);

        if let Some(trace) = &ctx.best_trace {
            let trace_path = ctx.out_dir.join("best-trace.csv");
            write_trace_csv(&trace_path, trace)?;
            written.push(trace_path);
        }

        let report_path = ctx.out_dir.join("report.md");
        write_markdown(&report_path, ctx, ranked)?;
        written.push(report_path);

        let summary_path = ctx.out_dir.join("summary.json");
        write_summary(&summary_path, ctx, ranked)?;
        written.push(summary_path);

        #[cfg(feature = "plot")]
        if let Some(trace) = &ctx.best_trace {
            let svg_path = ctx.out_dir.join("best.svg");
            crate::tune::plot::write_step_svg(&svg_path, trace, &ctx.scenario)?;
            written.push(svg_path);
        }

        Ok(written)
    }

    /// `trials.csv` 的一行。
    #[derive(Debug, Serialize)]
    struct TrialRow {
        index: u64,
        phase: &'static str,
        kp: f32,
        ki: f32,
        kd: f32,
        feedforward: f32,
        cost: f64,
        verdict: &'static str,
        settled: bool,
        rise_time_s: f32,
        overshoot_pct: f32,
        settling_time_s: f32,
        ss_error_pct: f32,
        steady_rpm: f32,
        iae: f32,
        peak_effort_raw: f32,
        rms_effort_raw: f32,
        saturated_pct: f32,
        max_rpm: f32,
    }

    impl TrialRow {
        fn from_trial(trial: &Trial) -> Self {
            let metrics = trial.score.metrics.unwrap_or_default();
            Self {
                index: trial.index,
                phase: trial.phase.label(),
                kp: trial.gains.kp,
                ki: trial.gains.ki,
                kd: trial.gains.kd,
                feedforward: trial.gains.feedforward,
                cost: trial.score.cost,
                verdict: trial.score.verdict.label(),
                settled: metrics.settled,
                rise_time_s: metrics.rise_time_s,
                overshoot_pct: metrics.overshoot_pct,
                settling_time_s: metrics.settling_time_s,
                ss_error_pct: metrics.ss_error_pct,
                steady_rpm: metrics.steady_rpm,
                iae: metrics.iae,
                peak_effort_raw: metrics.peak_effort_raw,
                rms_effort_raw: metrics.rms_effort_raw,
                saturated_pct: metrics.saturated_pct,
                max_rpm: metrics.max_rpm,
            }
        }
    }

    fn write_trials_csv(path: &Path, trials: &[Trial]) -> Result<(), ReportError> {
        let mut writer = csv::Writer::from_path(path)?;
        for trial in trials {
            writer.serialize(TrialRow::from_trial(trial))?;
        }
        writer.flush().map_err(|e| io(path, e))?;
        Ok(())
    }

    /// 轨迹 CSV 的一行。
    #[derive(Debug, Serialize)]
    struct TraceRow {
        t_s: f32,
        setpoint_rpm: f32,
        rpm: f32,
        effort_raw: i16,
        saturated: bool,
    }

    fn write_trace_csv(path: &Path, trace: &Trace) -> Result<(), ReportError> {
        let mut writer = csv::Writer::from_path(path)?;
        for index in 0..trace.len() {
            writer.serialize(TraceRow {
                t_s: trace.t_s[index],
                setpoint_rpm: trace.setpoint_rpm[index],
                rpm: trace.rpm[index],
                effort_raw: trace.effort_raw[index],
                saturated: trace.saturated[index],
            })?;
        }
        writer.flush().map_err(|e| io(path, e))?;
        Ok(())
    }

    /// 可粘贴进既有 `[[motor]]` 段落的增益补丁。
    #[derive(Debug, Serialize)]
    struct GainPatch {
        kp: f32,
        ki: f32,
        kd: f32,
        feedforward: f32,
    }

    fn write_best_toml(path: &Path, ctx: &ReportContext, best: &Trial) -> Result<(), ReportError> {
        let gains_patch = GainPatch {
            kp: best.gains.kp,
            ki: best.gains.ki,
            kd: best.gains.kd,
            feedforward: best.gains.feedforward,
        };
        let mut text = String::new();
        writeln!(
            text,
            "# 由 chassis-tune 生成（seed={}, backend={}）",
            ctx.config.seed, ctx.backend
        )
        .ok();
        writeln!(
            text,
            "# 轮子：{}｜场景：{}｜限流 {} raw",
            ctx.motor_name,
            tuning::search::scenario_summary(&ctx.scenario),
            ctx.limits.current_limit_raw
        )
        .ok();
        writeln!(text, "# 参数空间：{}", ctx.space.describe()).ok();
        text.push_str("# 把下面四行粘进 chassis.toml 里对应的 [[motor]] 段落即可。\n");
        text.push_str(&toml::to_string(&gains_patch)?);
        std::fs::write(path, text).map_err(|e| io(path, e))?;
        Ok(())
    }

    /// `summary.json` 的结构。
    #[derive(Debug, Serialize)]
    struct Summary<'a> {
        backend: &'a str,
        seed: u64,
        samples: usize,
        top_k: usize,
        solver: &'static str,
        evals: u64,
        ok_trials: usize,
        rejected_trials: usize,
        scenario: String,
        gain_space: String,
        limits: LimitSummary,
        thresholds: Thresholds,
        best: BestSummary,
        top: Vec<BestSummary>,
        notes: Vec<String>,
    }

    #[derive(Debug, Serialize)]
    struct LimitSummary {
        current_limit_raw: i16,
    }

    #[derive(Debug, Serialize)]
    struct Thresholds {
        max_overshoot_pct: f32,
        max_ss_error_pct: f32,
    }

    #[derive(Debug, Serialize)]
    struct BestSummary {
        index: u64,
        phase: &'static str,
        kp: f32,
        ki: f32,
        kd: f32,
        feedforward: f32,
        cost: f64,
        verdict: &'static str,
        metrics: Option<MetricsSummary>,
    }

    #[derive(Debug, Serialize)]
    struct MetricsSummary {
        rise_time_s: f32,
        overshoot_pct: f32,
        settling_time_s: f32,
        ss_error_pct: f32,
        steady_rpm: f32,
        iae: f32,
        rms_effort_raw: f32,
        saturated_pct: f32,
        max_rpm: f32,
    }

    impl MetricsSummary {
        fn from_metrics(metrics: &StepMetrics) -> Self {
            Self {
                rise_time_s: metrics.rise_time_s,
                overshoot_pct: metrics.overshoot_pct,
                settling_time_s: metrics.settling_time_s,
                ss_error_pct: metrics.ss_error_pct,
                steady_rpm: metrics.steady_rpm,
                iae: metrics.iae,
                rms_effort_raw: metrics.rms_effort_raw,
                saturated_pct: metrics.saturated_pct,
                max_rpm: metrics.max_rpm,
            }
        }
    }

    fn best_summary(trial: &Trial) -> BestSummary {
        BestSummary {
            index: trial.index,
            phase: trial.phase.label(),
            kp: trial.gains.kp,
            ki: trial.gains.ki,
            kd: trial.gains.kd,
            feedforward: trial.gains.feedforward,
            cost: trial.score.cost,
            verdict: trial.score.verdict.label(),
            metrics: trial.score.metrics.as_ref().map(MetricsSummary::from_metrics),
        }
    }

    fn write_summary(path: &Path, ctx: &ReportContext, ranked: &Ranked) -> Result<(), ReportError> {
        let mut notes = Vec::new();
        if !ranked.best.score.verdict.is_ok() {
            notes.push(format!(
                "没有任何候选达标：最优判定为 {}（{}）",
                ranked.best.score.verdict.label(),
                verdict_hint(ranked.best.score.verdict)
            ));
        }
        if let Some(metrics) = ranked.best.score.metrics {
            if metrics.overshoot_pct > ctx.max_overshoot_pct {
                notes.push(format!(
                    "最优解超调 {:.1}% 超过阈值 {:.1}%",
                    metrics.overshoot_pct, ctx.max_overshoot_pct
                ));
            }
            if metrics.ss_error_pct > ctx.max_ss_error_pct {
                notes.push(format!(
                    "最优解稳态误差 {:.1}% 超过阈值 {:.1}%",
                    metrics.ss_error_pct, ctx.max_ss_error_pct
                ));
            }
            if metrics.saturated_pct > 5.0 {
                notes.push(format!("最优解饱和占比 {:.1}%，限流可能偏紧", metrics.saturated_pct));
            }
        }
        // 贴边界的警告排在"通用提醒"之前：它是本次搜索最具体的一条结论。
        notes.extend(ctx.space.boundary_hits(&ranked.best.gains));
        notes.push(
            "仿真整定依赖被控对象模型；上真机前先用 `validate` 在台架上复验（--backend bench）。"
                .into(),
        );

        let summary = Summary {
            backend: &ctx.backend,
            seed: ctx.config.seed,
            samples: ctx.config.samples,
            top_k: ctx.config.top_k,
            solver: ctx.config.solver.name(),
            evals: ranked.evals,
            ok_trials: ranked.ok_count(),
            rejected_trials: ranked.rejected,
            scenario: tuning::search::scenario_summary(&ctx.scenario),
            gain_space: ctx.space.describe(),
            limits: LimitSummary { current_limit_raw: ctx.limits.current_limit_raw },
            thresholds: Thresholds {
                max_overshoot_pct: ctx.max_overshoot_pct,
                max_ss_error_pct: ctx.max_ss_error_pct,
            },
            best: best_summary(&ranked.best),
            top: ranked.top(10).iter().map(best_summary).collect(),
            notes,
        };
        let text = serde_json::to_string_pretty(&summary)?;
        std::fs::write(path, text).map_err(|e| io(path, e))?;
        Ok(())
    }

    fn write_markdown(
        path: &Path,
        ctx: &ReportContext,
        ranked: &Ranked,
    ) -> Result<(), ReportError> {
        let mut text = String::new();
        let best = &ranked.best;

        writeln!(text, "# 速度环自动整定报告\n").ok();
        write_markdown_conclusion(&mut text, ctx, best);
        write_markdown_settings(&mut text, ctx, ranked);
        write_markdown_top(&mut text, ranked);
        write_markdown_artifacts(&mut text);
        write_markdown_notes(&mut text, ctx, best);

        std::fs::write(path, text).map_err(|e| io(path, e))?;
        Ok(())
    }

    /// 结论段：最优增益、指标、验收、无解时的原因。
    fn write_markdown_conclusion(text: &mut String, ctx: &ReportContext, best: &Trial) {
        writeln!(text, "## 结论\n").ok();
        writeln!(
            text,
            "**kp = {:.3}　ki = {:.3}　kd = {:.3}　feedforward = {:.3}**（成本 {:.4}，判定 {}）\n",
            best.gains.kp,
            best.gains.ki,
            best.gains.kd,
            best.gains.feedforward,
            best.cost(),
            best.score.verdict.label()
        )
        .ok();
        if let Some(metrics) = best.score.metrics {
            writeln!(
                text,
                "- 上升时间 {:.0} ms｜超调 {:.1}%｜调节时间 {:.0} ms｜稳态误差 {:.2}%",
                metrics.rise_time_s * 1000.0,
                metrics.overshoot_pct,
                metrics.settling_time_s * 1000.0,
                metrics.ss_error_pct
            )
            .ok();
            writeln!(
                text,
                "- 峰值电流 {:.0} raw｜RMS 电流 {:.0} raw｜饱和 {:.1}%｜峰值转速 {:.0} rpm",
                metrics.peak_effort_raw,
                metrics.rms_effort_raw,
                metrics.saturated_pct,
                metrics.max_rpm
            )
            .ok();
            writeln!(
                text,
                "- 验收：{}（阈值 超调 ≤ {:.1}%，稳态误差 ≤ {:.1}%）\n",
                if ctx.best_passes(&metrics) { "✓ 通过" } else { "✗ 未通过" },
                ctx.max_overshoot_pct,
                ctx.max_ss_error_pct
            )
            .ok();
        }
        if !best.score.verdict.is_ok() {
            writeln!(
                text,
                "> ⚠ 没有任何候选达标（最优：{}）。{}\n",
                best.score.verdict.label(),
                verdict_hint(best.score.verdict)
            )
            .ok();
        }
    }

    /// 设置段：复现本次搜索所需的全部输入。
    fn write_markdown_settings(text: &mut String, ctx: &ReportContext, ranked: &Ranked) {
        writeln!(text, "## 设置\n").ok();
        writeln!(text, "| 项 | 值 |").ok();
        writeln!(text, "| --- | --- |").ok();
        writeln!(text, "| 后端 | `{}` |", ctx.backend).ok();
        writeln!(text, "| 场景 | `{}` |", tuning::search::scenario_summary(&ctx.scenario)).ok();
        writeln!(text, "| 参数空间 | `{}` |", ctx.space.describe()).ok();
        writeln!(text, "| 限流 | {} raw |", ctx.limits.current_limit_raw).ok();
        writeln!(text, "| 种子 | {} |", ctx.config.seed).ok();
        writeln!(
            text,
            "| 搜索 | samples={}, top_k={}, solver={}, max_iters={} |",
            ctx.config.samples,
            ctx.config.top_k,
            ctx.config.solver.name(),
            ctx.config.max_iters
        )
        .ok();
        writeln!(
            text,
            "| 评估 | {} 次（达标 {} / 共 {}） |",
            ranked.evals,
            ranked.ok_count(),
            ranked.trials.len()
        )
        .ok();
        writeln!(text, "| 目标轮 | `{}` |\n", ctx.motor_name).ok();
    }

    /// Top-10 表格。
    fn write_markdown_top(text: &mut String, ranked: &Ranked) {
        writeln!(text, "## Top 10\n").ok();
        writeln!(
            text,
            "| # | 阶段 | kp | ki | kd | ff | 成本 | 判定 | 超调 % | 稳态误差 % | 调节 ms |"
        )
        .ok();
        writeln!(text, "| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |").ok();
        for (rank, trial) in ranked.top(10).iter().enumerate() {
            let metrics = trial.score.metrics.unwrap_or_default();
            writeln!(
                text,
                "| {} | {} | {:.3} | {:.3} | {:.3} | {:.3} | {:.4} | {} | {:.1} | {:.2} | {:.0} |",
                rank + 1,
                trial.phase.label(),
                trial.gains.kp,
                trial.gains.ki,
                trial.gains.kd,
                trial.gains.feedforward,
                trial.cost(),
                trial.score.verdict.label(),
                metrics.overshoot_pct,
                metrics.ss_error_pct,
                metrics.settling_time_s * 1000.0
            )
            .ok();
        }
        writeln!(text).ok();
    }

    /// 产物清单。
    fn write_markdown_artifacts(text: &mut String) {
        writeln!(text, "## 产物\n").ok();
        writeln!(text, "- `trials.csv`：全部候选（含未达标者与判定原因）").ok();
        writeln!(text, "- `best.toml`：可粘贴的 `[[motor]]` 增益片段").ok();
        writeln!(text, "- `best-trace.csv`：最优增益的完整轨迹").ok();
        writeln!(text, "- `hil-validation.csv`：真机重复性复验（仅 `--backend bench`）").ok();
        writeln!(text, "- `summary.json`：机器可读结果\n").ok();
    }

    /// 注意事项：把"仿真整定不能替代实车复验"写进报告，而不是只写在 README 里。
    fn write_markdown_notes(text: &mut String, ctx: &ReportContext, best: &Trial) {
        let hits = ctx.space.boundary_hits(&best.gains);
        writeln!(text, "## 注意事项\n").ok();
        writeln!(
            text,
            "1. 仿真整定只保证在被控对象模型内最优；模型参数（摩擦 / 延迟）是量级估计，"
        )
        .ok();
        writeln!(
            text,
            "   上真机前请用同一 `--scenario` 跑 `chassis-tune sweep --backend bench` 复验。"
        )
        .ok();
        writeln!(
            text,
            "2. 台架搜索会真的驱动轮子：必须架空或整车固定，且加 `--i-know-the-wheel-spins`。"
        )
        .ok();
        writeln!(
            text,
            "3. `current_limit` 属于安全约束，不参与搜索；它会钳住 PID 输出，也决定饱和判定。"
        )
        .ok();
        writeln!(text, "4. 复现本次结果：同一 `--seed` + 同一参数空间 → 逐位一致。").ok();
        for hit in &hits {
            writeln!(text, "- ⚠ 搜索落在参数空间边界：{hit}").ok();
        }
        writeln!(
        text,
        "5. 本模型不含测量噪声：仿真里更高的增益不会被噪声惩罚，因此最优解可能偏激进——\n   台架复验（`--backend bench`）是把它拉回现实的唯一手段。"
    )
    .ok();
    }

    impl ReportContext {
        /// 一组指标是否满足验收阈值。
        #[must_use]
        pub fn best_passes(&self, metrics: &StepMetrics) -> bool {
            metrics.settled
                && metrics.overshoot_pct <= self.max_overshoot_pct
                && metrics.ss_error_pct <= self.max_ss_error_pct
        }
    }

    #[cfg(test)]
    mod tests {
        use super::*;
        use crate::SimEvaluator;
        use motor_model::PlantParams;
        use sim_harness::{LoopLimits, PlantEnsemble};
        use tuning::Evaluator;
        use tuning::cost::{Objective, Weights};
        use tuning::gains::GainSpace;
        use tuning::search::{SearchConfig, sweep};

        fn ranked(name: &str) -> (GainSpace, ReportContext, Ranked) {
            let space = GainSpace::default_gm3508();
            let scenario = Scenario::step(1500.0, 1.0);
            let limits = LoopLimits::gm3508();
            let objective = Objective::new(Weights::default(), scenario, limits);
            let ensemble = PlantEnsemble::homogeneous(PlantParams::gm3508(), 1);
            let evaluator = SimEvaluator::new(ensemble, scenario, limits, objective, 0.0);
            let config = SearchConfig {
                seed: 3,
                samples: 48,
                top_k: 2,
                max_iters: 40,
                max_evals: 900,
                ..SearchConfig::default()
            };
            let ranked = sweep(&space, &config, &evaluator, None).unwrap();
            let trace =
                sim_harness::simulate(ranked.best.gains, &PlantParams::gm3508(), &scenario, limits)
                    .unwrap();
            let ctx = ReportContext {
                out_dir: std::env::temp_dir().join(format!("chassis-tune-report-{name}")),
                space,
                config,
                scenario,
                limits,
                backend: evaluator.describe(),
                motor_name: "front_left".into(),
                max_overshoot_pct: 20.0,
                max_ss_error_pct: 5.0,
                best_trace: Some(trace),
            };
            (space, ctx, ranked)
        }

        #[test]
        fn writes_every_artifact() {
            let (_, ctx, ranked) = ranked("writes_every_artifact");
            let _ = std::fs::remove_dir_all(&ctx.out_dir);
            let written = write_reports(&ctx, &ranked).unwrap();
            let names: Vec<String> = written
                .iter()
                .map(|p| p.file_name().unwrap_or_default().to_string_lossy().into_owned())
                .collect();
            for expected in
                ["trials.csv", "best.toml", "best-trace.csv", "report.md", "summary.json"]
            {
                assert!(names.iter().any(|n| n == expected), "missing {expected}: {names:?}");
            }
            for path in &written {
                assert!(path.exists(), "{} must exist", path.display());
            }
        }

        #[test]
        fn trials_csv_has_a_stable_header_and_one_row_per_trial() {
            let (_, ctx, ranked) = ranked("trials_csv_has_a_stable_header_and_one_row_per_trial");
            write_reports(&ctx, &ranked).unwrap();
            let text = std::fs::read_to_string(ctx.out_dir.join("trials.csv")).unwrap();
            let mut lines = text.lines();
            let header = lines.next().unwrap();
            for column in ["index", "phase", "kp", "ki", "kd", "feedforward", "cost", "verdict"] {
                assert!(header.contains(column), "header missing {column}: {header}");
            }
            assert_eq!(lines.count(), ranked.trials.len());
        }

        #[test]
        fn best_toml_parses_back_through_the_config_schema() {
            let (_, ctx, ranked) = ranked("best_toml_parses_back_through_the_config_schema");
            write_reports(&ctx, &ranked).unwrap();
            let text = std::fs::read_to_string(ctx.out_dir.join("best.toml")).unwrap();
            // 片段本体是合法 TOML：与其它段落拼起来即可被 chassis-config 读回。
            let patch = text
                .lines()
                .filter(|line| !line.trim_start().starts_with('#'))
                .collect::<Vec<_>>()
                .join("\n");
            let full = format!(
                "[can]\ninterface = \"can0\"\n[mecanum]\nhalf_length = 0.2\nhalf_width = 0.25\nwheel_radius = 0.0762\n\n[[motor]]\nname = \"front_left\"\nesc_id = 1\ndirection = 1\ngear_ratio = 19.203\n{patch}"
            );
            let mut motors = Vec::new();
            for index in 1..4 {
                motors.push(format!(
                "[[motor]]\nname = \"w{index}\"\nesc_id = {}\ndirection = 1\ngear_ratio = 19.203\n",
                index + 1
            ));
            }
            let full = format!("{full}\n{}", motors.join("\n"));
            let config =
                chassis_config::Config::from_toml(&full).expect("best.toml must be readable");
            let gains = config.motors[0].velocity_gains();
            assert_eq!(gains, ranked.best.gains);
        }

        #[test]
        fn summary_json_is_machine_readable() {
            let (_, ctx, ranked) = ranked("summary_json_is_machine_readable");
            write_reports(&ctx, &ranked).unwrap();
            let text = std::fs::read_to_string(ctx.out_dir.join("summary.json")).unwrap();
            let value: serde_json::Value = serde_json::from_str(&text).unwrap();
            assert_eq!(value["seed"], serde_json::json!(3));
            assert_eq!(value["samples"], serde_json::json!(48));
            assert!(value["best"]["kp"].as_f64().unwrap() > 0.0);
            assert!(value["top"].as_array().unwrap().len() <= 10);
            assert!(!value["notes"].as_array().unwrap().is_empty());
        }

        #[test]
        fn markdown_mentions_the_gains_and_thresholds() {
            let (_, ctx, ranked) = ranked("markdown_mentions_the_gains_and_thresholds");
            write_reports(&ctx, &ranked).unwrap();
            let text = std::fs::read_to_string(ctx.out_dir.join("report.md")).unwrap();
            assert!(text.contains("kp ="), "{text}");
            assert!(text.contains("Top 10"), "{text}");
            assert!(text.contains("front_left"), "{text}");
            assert!(text.contains("注意事项"), "{text}");
        }

        #[test]
        fn best_trace_csv_matches_the_trace_length() {
            let (_, ctx, ranked) = ranked("best_trace_csv_matches_the_trace_length");
            write_reports(&ctx, &ranked).unwrap();
            let text = std::fs::read_to_string(ctx.out_dir.join("best-trace.csv")).unwrap();
            let rows = text.lines().count();
            let expected = ctx.best_trace.as_ref().unwrap().len() + 1; // + 表头
            assert_eq!(rows, expected);
        }

        #[test]
        fn best_passes_respects_the_thresholds() {
            let (_, ctx, _) = ranked("t");
            let passing = StepMetrics {
                settled: true,
                overshoot_pct: 10.0,
                ss_error_pct: 1.0,
                ..StepMetrics::default()
            };
            assert!(ctx.best_passes(&passing));
            let overshooting = StepMetrics { overshoot_pct: 50.0, ..passing };
            assert!(!ctx.best_passes(&overshooting));
            let unsettled = StepMetrics { settled: false, ..passing };
            assert!(!ctx.best_passes(&unsettled));
        }
    }
}

#[cfg(feature = "plot")]
pub mod plot {
    //! 可选（`--features plot`）：把最优步响应画成 SVG。
    //!
    //! 为什么是 SVG 而不是 PNG：矢量图在任何缩放级别都能看清起动段的细节，
    //! 且不需要位图编码器（依赖更小）。默认关闭该 feature——绘图不是整定的
    //! 必要条件，CSV 已经给了全部数据。

    use std::path::Path;

    use experiment::{Scenario, Trace};
    use plotters::backend::SVGBackend;
    use plotters::chart::ChartBuilder;
    use plotters::drawing::IntoDrawingArea as _;
    use plotters::series::LineSeries;
    use plotters::style::{BLACK, BLUE, Color as _, RED, WHITE};

    use crate::report::ReportError;

    /// 写出步响应三联图：转速跟随、误差、电流。
    ///
    /// # Errors
    ///
    /// 绘图或写文件失败时返回 [`ReportError::Plot`]。
    pub fn write_step_svg(
        path: &Path,
        trace: &Trace,
        scenario: &Scenario,
    ) -> Result<(), ReportError> {
        let root = SVGBackend::new(path, (1000, 900)).into_drawing_area();
        root.fill(&WHITE).map_err(plot_err)?;
        let (upper, lower) = root.split_vertically(600);
        let (middle, bottom) = lower.split_vertically(150);

        let total = trace.t_s.last().copied().unwrap_or(1.0).max(1.0e-3);
        let peak = trace.rpm.iter().copied().fold(scenario.target_rpm, f32::max).max(1.0);
        let effort_peak =
            trace.effort_raw.iter().map(|&raw| f32::from(raw).abs()).fold(1.0f32, f32::max);

        // 转速跟随。
        let mut chart = ChartBuilder::on(&upper)
            .caption("velocity step response (rpm)", ("sans-serif", 24))
            .margin(12)
            .x_label_area_size(36)
            .y_label_area_size(64)
            .build_cartesian_2d(0.0f32..total, 0.0f32..peak * 1.1)
            .map_err(plot_err)?;
        chart.configure_mesh().x_desc("t (s)").y_desc("rpm").draw().map_err(plot_err)?;
        chart
            .draw_series(LineSeries::new(
                trace.t_s.iter().copied().zip(trace.setpoint_rpm.iter().copied()),
                &BLACK,
            ))
            .map_err(plot_err)?
            .label("setpoint")
            .legend(|(x, y)| plotters::element::PathElement::new([(x, y), (x + 18, y)], BLUE));
        chart
            .draw_series(LineSeries::new(
                trace.t_s.iter().copied().zip(trace.rpm.iter().copied()),
                &BLUE,
            ))
            .map_err(plot_err)?
            .label("measured")
            .legend(|(x, y)| plotters::element::PathElement::new([(x, y), (x + 18, y)], RED));
        chart
            .configure_series_labels()
            .background_style(WHITE.mix(0.8))
            .draw()
            .map_err(plot_err)?;

        // 误差。
        let mut error_chart = ChartBuilder::on(&middle)
            .caption("error (rpm)", ("sans-serif", 16))
            .margin(8)
            .x_label_area_size(28)
            .y_label_area_size(64)
            .build_cartesian_2d(0.0f32..total, -peak..peak)
            .map_err(plot_err)?;
        error_chart.configure_mesh().draw().map_err(plot_err)?;
        error_chart
            .draw_series(LineSeries::new(
                trace
                    .t_s
                    .iter()
                    .zip(trace.setpoint_rpm.iter().zip(trace.rpm.iter()))
                    .map(|(&t, (&sp, &rpm))| (t, sp - rpm)),
                &RED,
            ))
            .map_err(plot_err)?;

        // 电流。
        let mut effort_chart = ChartBuilder::on(&bottom)
            .caption("effort (raw)", ("sans-serif", 16))
            .margin(8)
            .x_label_area_size(28)
            .y_label_area_size(64)
            .build_cartesian_2d(0.0f32..total, -effort_peak..effort_peak)
            .map_err(plot_err)?;
        effort_chart.configure_mesh().draw().map_err(plot_err)?;
        effort_chart
            .draw_series(LineSeries::new(
                trace.t_s.iter().zip(trace.effort_raw.iter()).map(|(&t, &raw)| (t, f32::from(raw))),
                &BLUE,
            ))
            .map_err(plot_err)?;

        root.present().map_err(plot_err)?;
        Ok(())
    }

    fn plot_err<E: std::fmt::Debug>(error: E) -> ReportError {
        ReportError::Plot(format!("{error:?}"))
    }

    #[cfg(test)]
    mod tests {
        use super::*;
        use experiment::SetpointProfile;
        use motor_control::VelocityGains;
        use motor_model::PlantParams;
        use sim_harness::{LoopLimits, simulate};

        #[test]
        fn writes_a_non_empty_svg() {
            let scenario = Scenario::ramp_and_hold(1200.0, 0.2, 0.8)
                .with_profile(SetpointProfile::RampAndHold);
            let trace = simulate(
                VelocityGains::new(4.0, 12.0, 0.0, 0.3),
                &PlantParams::gm3508(),
                &scenario,
                LoopLimits::gm3508(),
            )
            .unwrap();
            let path = std::env::temp_dir().join("chassis-tune-plot.svg");
            write_step_svg(&path, &trace, &scenario).unwrap();
            let text = std::fs::read_to_string(&path).unwrap();
            assert!(text.starts_with("<?xml") || text.contains("<svg"), "not an svg");
            assert!(text.len() > 1000, "svg looks empty");
            let _ = std::fs::remove_file(&path);
        }
    }
}

// `chassis-tune`：底盘速度环 PID 自动整定命令行工具。
//
// ```sh
// # 0) 看预设文件里有哪些工况预设（只读，不搜索）
// cargo run -p chassis-tune -- presets
//
// # 1) 仿真搜索（默认；不碰硬件，可反复跑）
// cargo run --release -p chassis-tune -- sweep --samples 512 --out-dir target/tune
//
// # 1b) 用预设跑（超参数进版本管理，见 config/tune.toml）
// cargo run --release -p chassis-tune -- sweep \
//   --preset config/tune.toml --preset-name bench_loaded
//
// # 2) 复算一组给定增益（CI / 回归用，按阈值给退出码）
// cargo run -p chassis-tune -- validate --gains 2,10,0,0
//
// # 3) 台架复验（**轮子会转**：必须架空或整车固定，急停可及）
// cargo run --release -p chassis-tune -- sweep --backend bench \
//   --device /dev/ttyACM0 --esc-id 1 --samples 24 --top-k 3 \
//   --i-know-the-wheel-spins
// ```
//
// # 超参数的优先级
//
// `内置默认 < 预设文件（`--preset` + `--preset-name`）< 显式命令行参数`。
// 机械 / 安全参数（`--current-limit`、`--direction`、`--gear-ratio`、电调 ID）
// 不参与这条链：它们只来自 `--config`（`chassis.toml`）或显式 CLI，
// 预设文件**不能**覆盖它们。
//
// 退出码：最优解满足验收阈值（`--max-overshoot` / `--max-ss-error`）为 0，
// 否则 1；参数 / IO 错误为 2。

use std::path::{Path, PathBuf};
use std::process::ExitCode;
use std::time::Duration;

use self::report::{ReportContext, write_reports};
use anyhow::{Context as _, Result, bail};
use bench::CanSpeed;
use bench::hil::{BenchConfig, BenchEvaluator as BenchRunner, open_link};
use bench::safety::SafetyEnvelope;
use chassis_config::Config;
use clap::{Args as ClapArgs, Parser, Subcommand, ValueEnum};
use esc_bus::EscConfig;
use experiment::SetpointProfile;
use indicatif::ProgressBar;
use motor_control::VelocityGains;
use motor_protocol::EscModel;
use serde::Serialize;
use sim_harness::{LoopLimits, PlantEnsemble};
use tuning::{
    AcceptanceSpec, BackendSpec, BenchEnvelope, BenchSpec, CostSpec, DEFAULT_PRESET_PATH,
    Evaluator, Objective, PlantSpec, Preset, PresetFile, ProfileSpec, RangeSpec, Ranked, ScaleSpec,
    ScenarioSpec, Score, SearchSpec, SimSpec, SolverSpec, SpaceSpec, Tuning, Verdict, parse_axis,
    sweep,
};

/// 子命令。
#[derive(Debug, Subcommand)]
enum Command {
    /// 分层粗扫 + 多起点精修（默认动作）
    Sweep(SweepArgs),
    /// 只复算一组给定增益的指标（不搜索）
    Validate(ValidateArgs),
    /// 列出预设文件里的超参数预设（只读）
    Presets(PresetsArgs),
}

/// 公共参数（仿真与真机共用）。
///
/// 超参数（参数空间、场景、权重、阈值、搜索预算、被控对象、安全包络）都可以缺省：
/// 缺省时按 **内置默认 → 预设文件 → 显式 CLI** 解算，见模块文档与
/// `tuning::preset`。这里的 `Option` 正是"用户是否显式给了"的载体。
#[derive(Debug, Clone, ClapArgs)]
struct CommonArgs {
    /// 评估后端：`sim`（离线）或 `bench`（真机台架）
    #[arg(long, value_enum)]
    backend: Option<BackendArg>,

    // ---------------- 超参数预设 ----------------
    /// 超参数预设文件（TOML）。缺省时若给了 `--preset-name` 则用 `config/tune.toml`
    #[arg(long, value_name = "FILE")]
    preset: Option<PathBuf>,
    /// 预设名（缺省取文件里的 `default_preset`）
    #[arg(long, value_name = "NAME")]
    preset_name: Option<String>,

    // ---------------- 参数空间（覆盖预设） ----------------
    /// kp 范围，如 `0.5..30`（内置默认 `0.5..30`）
    #[arg(long, value_name = "MIN..MAX")]
    kp: Option<String>,
    /// ki 范围，如 `0.1..100`（内置默认 `0.1..100`）
    #[arg(long, value_name = "MIN..MAX")]
    ki: Option<String>,
    /// kd 范围（内置默认 `0.01..3`）
    #[arg(long, value_name = "MIN..MAX")]
    kd: Option<String>,
    /// 前馈范围（raw/rpm；内置默认 `0.01..2.5`）
    #[arg(long, value_name = "MIN..MAX")]
    feedforward: Option<String>,
    /// kp 刻度（内置默认 `log`）
    #[arg(long, value_enum)]
    kp_scale: Option<ScaleArg>,
    /// ki 刻度（`log0` 允许精确取 0；内置默认 `log0`）
    #[arg(long, value_enum)]
    ki_scale: Option<ScaleArg>,
    /// kd 刻度（内置默认 `log0`）
    #[arg(long, value_enum)]
    kd_scale: Option<ScaleArg>,
    /// 前馈刻度（内置默认 `log0`）
    #[arg(long, value_enum)]
    feedforward_scale: Option<ScaleArg>,

    // ---------------- 场景（覆盖预设） ----------------
    /// 目标转子转速（rpm；内置默认 1500）
    #[arg(long)]
    target_rpm: Option<f32>,
    /// 场景类型（内置默认 `ramp-and-hold`）
    #[arg(long, value_enum)]
    scenario: Option<ScenarioArg>,
    /// 斜坡时间（毫秒；内置默认 200）
    #[arg(long)]
    ramp_ms: Option<f32>,
    /// 保持时间（毫秒；内置默认 1800）
    #[arg(long)]
    hold_ms: Option<f32>,
    /// 阶梯级数（`--scenario staircase`；内置默认 4）
    #[arg(long)]
    stair_levels: Option<u32>,
    /// 采样 / 控制节拍（微秒；内置默认 1000）
    #[arg(long)]
    dt_us: Option<f32>,
    /// 电流限幅（raw；同时是 PID 输出钳位点）。缺省取 `--config` 里该电机的值，否则 12000
    #[arg(long)]
    current_limit: Option<i16>,
    /// 电调型号。缺省取 `--config` 里该电机的值，否则 C620
    #[arg(long, value_enum)]
    model: Option<ModelArg>,
    /// 现有 `chassis.toml`：用作机械 / 安全参数的来源（电流限幅、电调 ID、方向、减速比）
    #[arg(long)]
    config: Option<PathBuf>,
    /// 把整定结果写回一份配置（需同时给 `--config`；只改写 kp/ki/kd/feedforward）
    #[arg(long)]
    write_config: Option<PathBuf>,

    // ---------------- 成本权重（覆盖预设） ----------------
    /// 调节时间权重（内置默认 1.0）
    #[arg(long)]
    w_settle: Option<f64>,
    /// 超调权重（内置默认 1.0）
    #[arg(long)]
    w_overshoot: Option<f64>,
    /// IAE 权重（内置默认 0.5）
    #[arg(long)]
    w_iae: Option<f64>,
    /// 电流（RMS）权重（内置默认 0.1）
    #[arg(long)]
    w_effort: Option<f64>,

    // ---------------- 验收阈值（覆盖预设） ----------------
    /// 允许的最大超调（%；内置默认 20）
    #[arg(long)]
    max_overshoot: Option<f32>,
    /// 允许的最大稳态误差（%；内置默认 5）
    #[arg(long)]
    max_ss_error: Option<f32>,

    // ---------------- 搜索（覆盖预设） ----------------
    /// 随机种子（同 seed 结果逐位一致；内置默认 20260101）
    #[arg(long)]
    seed: Option<u64>,
    /// 粗扫样本数（内置默认 512）
    #[arg(long)]
    samples: Option<usize>,
    /// 进入精修的种子数（内置默认 8）
    #[arg(long)]
    top_k: Option<usize>,
    /// 精修求解器（内置默认 `nelder-mead`）
    #[arg(long, value_enum)]
    solver: Option<SolverArg>,
    /// 每个起点的最大迭代数（内置默认 200）
    #[arg(long)]
    max_iters: Option<usize>,
    /// PSO 粒子数（`--solver pso`；内置默认 24）
    #[arg(long)]
    particles: Option<usize>,
    /// 评估预算上限（内置默认 4000）
    #[arg(long)]
    max_evals: Option<u64>,
    /// 线程数（0 = rayon 默认；真机后端强制 1；内置默认 0）
    #[arg(long)]
    threads: Option<usize>,

    // ---------------- 真机安全包络（覆盖预设） ----------------
    /// 过速保护上限（rpm；内置默认 3000）
    #[arg(long)]
    max_rpm: Option<f32>,
    /// 温度保护上限（℃；内置默认 70）
    #[arg(long)]
    max_temp_c: Option<i8>,
    /// 单次试验超时（毫秒；内置默认 6000）
    #[arg(long)]
    trial_timeout_ms: Option<u64>,
    /// 试验之间的静默期（毫秒；内置默认 500）
    #[arg(long)]
    between_trials_ms: Option<u64>,
    /// 启动时等待反馈的超时（毫秒；内置默认 5000）
    #[arg(long)]
    startup_timeout_ms: Option<u64>,
    /// 安全事件后继续搜索（默认立即收工）
    #[arg(long)]
    continue_on_abort: bool,
    /// 最优增益的复验次数（写入 hil-validation.csv；内置默认 3）
    #[arg(long)]
    validate_runs: Option<usize>,

    // ---------------- 输出 ----------------
    /// 产物目录
    #[arg(long, default_value = "target/chassis-tune")]
    out_dir: PathBuf,
    /// 目标轮名（写进 best.toml 注释与报告）
    #[arg(long, default_value = "front_left")]
    motor: String,
    /// 把 JSON 摘要打印到 stdout
    #[arg(long)]
    json: bool,

    #[command(flatten)]
    sim: SimArgs,
    #[command(flatten)]
    bench: BenchArgs,
}

/// 仿真后端参数（覆盖预设）。
#[derive(Debug, Clone, ClapArgs)]
struct SimArgs {
    /// 被控对象模型（内置默认 `gm3508-bench`）
    #[arg(long, value_enum)]
    plant: Option<PlantArg>,
    /// 集成成员数（域随机化；1 = 只用名义模型；内置默认 8）
    #[arg(long)]
    ensemble: Option<usize>,
    /// 鲁棒权重：0 = 只看均值，1 = 只看最坏成员（内置默认 0.5）
    #[arg(long)]
    robust_weight: Option<f64>,
    /// 抖动幅度，如 `gain=0.2,tau=0.3,delay=3,friction=0.5`（内置默认同左）
    #[arg(long)]
    jitter: Option<String>,
}

/// 真机接线参数（**不参与搜索，也不受预设影响**）。
#[derive(Debug, Clone, ClapArgs)]
struct BenchArgs {
    /// slcan 串口设备
    #[arg(long, default_value = "/dev/ttyACM0")]
    device: String,
    /// SocketCAN 接口名（给了它就走 SocketCAN，忽略 --device）
    #[arg(long)]
    interface: Option<String>,
    /// 串口波特率
    #[arg(long, default_value_t = 2_000_000)]
    serial_baud: u32,
    /// CAN 波特率档位
    #[arg(long, value_enum, default_value_t = CanSpeedArg::M1)]
    can_speed: CanSpeedArg,
    /// 目标电调 ID（缺省取 `--config`，否则 1）
    #[arg(long)]
    esc_id: Option<u8>,
    /// 安装方向 +1 / -1（缺省取 `--config`，否则 1）
    #[arg(long, allow_hyphen_values = true)]
    direction: Option<f32>,
    /// 减速比（转子 : 输出轴；缺省取 `--config`，否则 19.203）
    #[arg(long)]
    gear_ratio: Option<f32>,
    /// **明确确认**：轮子会真的转起来（架空或整车固定、急停可及）
    #[arg(long)]
    i_know_the_wheel_spins: bool,
}

#[derive(Debug, ClapArgs)]
struct SweepArgs {
    #[command(flatten)]
    common: CommonArgs,
}

#[derive(Debug, ClapArgs)]
struct ValidateArgs {
    #[command(flatten)]
    common: CommonArgs,
    /// 四个增益，如 `2,10,0,0`（kp,ki,kd,feedforward）
    #[arg(long)]
    gains: String,
}

#[derive(Debug, ClapArgs)]
struct PresetsArgs {
    /// 预设文件（缺省 `config/tune.toml`）
    #[arg(long, default_value = DEFAULT_PRESET_PATH)]
    preset: PathBuf,
}

#[derive(Debug, Parser)]
#[command(
    name = "chassis-tune",
    version,
    about = "底盘速度环 PID 自动整定（参数空间搜索：仿真 / 真机台架）"
)]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

// ---------------------------------------------------------------- 枚举参数

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
enum BackendArg {
    /// 离线被控对象仿真
    Sim,
    /// 真机台架（会驱动电机）
    Bench,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
enum ScaleArg {
    /// 线性
    Linear,
    /// 对数（恒正）
    Log,
    /// 以一定概率取 0，否则对数
    Log0,
}

impl From<ScaleArg> for ScaleSpec {
    fn from(value: ScaleArg) -> Self {
        match value {
            ScaleArg::Linear => Self::Linear,
            ScaleArg::Log => Self::Log,
            ScaleArg::Log0 => Self::Log0,
        }
    }
}

impl From<BackendArg> for BackendSpec {
    fn from(value: BackendArg) -> Self {
        match value {
            BackendArg::Sim => Self::Sim,
            BackendArg::Bench => Self::Bench,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
enum ScenarioArg {
    /// 阶跃
    Step,
    /// 斜坡 + 保持
    RampAndHold,
    /// 阶梯
    Staircase,
    /// 升 → 保持 → 降 → 保持
    UpDown,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
enum SolverArg {
    /// Nelder-Mead（默认，无导数）
    NelderMead,
    /// 粒子群
    Pso,
}

impl From<SolverArg> for SolverSpec {
    fn from(value: SolverArg) -> Self {
        match value {
            SolverArg::NelderMead => Self::NelderMead,
            SolverArg::Pso => Self::Pso,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
enum PlantArg {
    /// 理想一阶模型（无摩擦、无延迟）
    Gm3508,
    /// 台架量级：静 / 库仑摩擦 + 2 拍延迟
    Gm3508Bench,
}

impl From<PlantArg> for PlantSpec {
    fn from(value: PlantArg) -> Self {
        match value {
            PlantArg::Gm3508 => Self::Gm3508,
            PlantArg::Gm3508Bench => Self::Gm3508Bench,
        }
    }
}

impl From<ScenarioArg> for ProfileSpec {
    fn from(value: ScenarioArg) -> Self {
        match value {
            ScenarioArg::Step => Self::Step,
            ScenarioArg::RampAndHold => Self::RampAndHold,
            ScenarioArg::Staircase => Self::Staircase,
            ScenarioArg::UpDown => Self::UpDown,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
enum ModelArg {
    /// C620（±16384 ↔ ±20 A）
    C620,
    /// C610（±10000 ↔ ±10 A）
    C610,
}

impl From<ModelArg> for EscModel {
    fn from(value: ModelArg) -> Self {
        match value {
            ModelArg::C620 => Self::C620,
            ModelArg::C610 => Self::C610,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
enum CanSpeedArg {
    /// 1 Mbps
    #[value(name = "1m")]
    M1,
    /// 500 kbps
    #[value(name = "500k")]
    K500,
}

impl From<CanSpeedArg> for CanSpeed {
    fn from(value: CanSpeedArg) -> Self {
        match value {
            CanSpeedArg::M1 => Self::M1,
            CanSpeedArg::K500 => Self::K500,
        }
    }
}

// ---------------------------------------------------------------- 入口

fn main() -> ExitCode {
    init_tracing();
    let cli = Cli::parse();
    match run(cli) {
        Ok(code) => code,
        Err(error) => {
            eprintln!("✗ {error:#}");
            ExitCode::from(2)
        }
    }
}

fn init_tracing() {
    let filter = tracing_subscriber::EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("warn"));
    let _ = tracing_subscriber::fmt().with_env_filter(filter).try_init();
}

fn run(cli: Cli) -> Result<ExitCode> {
    match cli.command {
        Command::Sweep(args) => sweep_cmd(&args.common.resolve()?),
        Command::Validate(args) => validate_cmd(&args.common.resolve()?, &args.gains),
        Command::Presets(args) => presets_cmd(&args),
    }
}

/// 解算后的运行设置：**已校验**的超参数 + 本次运行的透传项。
///
/// 下游只面对这个结构，因此"超参数是从哪来的"（内置默认 / 预设 / CLI）
/// 不再散落在每个使用点，而是集中在 [`CommonArgs::resolve`] 一处。
#[derive(Debug)]
struct Settings {
    // ---- 透传：机械 / 安全与输出（不参与超参数优先级链） ----
    /// `chassis.toml` 路径。
    config: Option<PathBuf>,
    /// 整定结果写回路径。
    write_config: Option<PathBuf>,
    /// 产物目录。
    out_dir: PathBuf,
    /// 目标轮名。
    motor: String,
    /// 打印 JSON 摘要。
    json: bool,
    /// 电流限幅覆盖（缺省取 `chassis.toml`，再缺省 12000）。
    current_limit: Option<i16>,
    /// 电调型号覆盖。
    model: Option<ModelArg>,
    /// 真机接线参数。
    bench: BenchArgs,
    /// 超参数来源描述（打印与报告用）。
    source: String,
    // ---- 超参数（已解析 / 已校验） ----
    /// 解算后的超参数。
    tuning: Tuning,
    /// 真机安全包络。
    envelope: BenchEnvelope,
}

impl CommonArgs {
    /// 解算超参数：**内置默认 → 预设文件 → 显式 CLI**。
    ///
    /// # Errors
    ///
    /// 预设文件读取 / 解析失败、预设名不存在、区间 / 阈值 / 预算非法、
    /// 或预设路径缺失时返回错误。
    fn resolve(&self) -> Result<Settings> {
        let (file, prefix) = preset_source(
            self.preset.as_ref(),
            self.preset_name.as_deref(),
            Path::new(DEFAULT_PRESET_PATH),
        )?;

        let (name, selected) = file.select_named(self.preset_name.as_deref())?;
        let mut merged = Preset::builtin().overlay(selected).overlay(&self.range_overlay()?);
        // 刻度与抖动允许"只改这一项"，因此不放进 range_overlay，而是在合并后定点覆盖。
        apply_scales(&mut merged, self);
        apply_jitter(&mut merged, self)?;

        let source =
            if prefix.is_empty() { "内置默认".to_owned() } else { format!("{prefix}{name}") };
        let tuning = merged.to_tuning().with_context(|| format!("解算预设 '{source}' 失败"))?;
        let envelope = merged
            .bench_envelope()
            .with_context(|| format!("解算预设 '{source}' 的安全包络失败"))?;

        Ok(Settings {
            config: self.config.clone(),
            write_config: self.write_config.clone(),
            out_dir: self.out_dir.clone(),
            motor: self.motor.clone(),
            json: self.json,
            current_limit: self.current_limit,
            model: self.model,
            bench: self.bench.clone(),
            source,
            tuning,
            envelope,
        })
    }

    /// 只含"显式给出的区间 / 后端 / 场景 / 权重 / 阈值 / 搜索 / 被控对象"的覆盖层。
    ///
    /// 刻度（`--kp-scale` 等）与 `--jitter` 不在这里：它们可以单独给出，
    /// 由 [`apply_scales`] / [`apply_jitter`] 在合并后覆盖。
    ///
    /// # Errors
    ///
    /// `--kp` 这类区间文本无法解析时返回错误。
    fn range_overlay(&self) -> Result<Preset> {
        let space = SpaceSpec {
            kp: range(self.kp.as_deref(), "kp")?,
            ki: range(self.ki.as_deref(), "ki")?,
            kd: range(self.kd.as_deref(), "kd")?,
            feedforward: range(self.feedforward.as_deref(), "feedforward")?,
        };
        let scenario = ScenarioSpec {
            profile: self.scenario.map(Into::into),
            target_rpm: self.target_rpm,
            ramp_ms: self.ramp_ms,
            hold_ms: self.hold_ms,
            stair_levels: self.stair_levels,
            dt_us: self.dt_us,
        };
        let cost = CostSpec {
            settle: self.w_settle,
            overshoot: self.w_overshoot,
            iae: self.w_iae,
            effort: self.w_effort,
        };
        let acceptance = AcceptanceSpec {
            max_overshoot_pct: self.max_overshoot,
            max_ss_error_pct: self.max_ss_error,
        };
        let search = SearchSpec {
            seed: self.seed,
            samples: self.samples,
            top_k: self.top_k,
            solver: self.solver.map(Into::into),
            max_iters: self.max_iters,
            particles: self.particles,
            max_evals: self.max_evals,
            threads: self.threads,
        };
        let sim = SimSpec {
            plant: self.sim.plant.map(Into::into),
            ensemble: self.sim.ensemble,
            robust_weight: self.sim.robust_weight,
            ..SimSpec::default()
        };
        let bench = BenchSpec {
            max_rpm: self.max_rpm,
            max_temp_c: self.max_temp_c,
            trial_timeout_ms: self.trial_timeout_ms,
            between_trials_ms: self.between_trials_ms,
            startup_timeout_ms: self.startup_timeout_ms,
            // `--continue-on-abort` 是布尔开关：只在给出时为 true，不去覆盖预设的 true。
            continue_on_abort: self.continue_on_abort.then_some(true),
            validate_runs: self.validate_runs,
        };
        Ok(Preset {
            backend: self.backend.map(Into::into),
            space,
            scenario,
            cost,
            acceptance,
            search,
            sim,
            bench,
            ..Preset::default()
        })
    }
}

/// 选择预设来源，返回（预设库, 来源前缀）。
///
/// 顺序：显式 `--preset` > 给了 `--preset-name` 时的 `default_path` > 内置库。
/// `default_path` 作为参数传入（而不是直接读常量），这样"只给 `--preset-name`"
/// 的回落逻辑可以在不依赖当前工作目录的情况下被测试。
///
/// # Errors
///
/// 预设文件不存在 / 无法解析，或"给了名字却找不到默认文件"时返回错误。
fn preset_source(
    explicit: Option<&PathBuf>,
    preset_name: Option<&str>,
    default_path: &Path,
) -> Result<(PresetFile, String)> {
    let path = match explicit {
        Some(path) => path.clone(),
        None if preset_name.is_some() => {
            if !default_path.exists() {
                bail!(
                    "给了 --preset-name 但没给 --preset，且默认路径 {} 不存在\n  \
                     请显式指定：--preset {} --preset-name <NAME>",
                    default_path.display(),
                    default_path.display()
                );
            }
            default_path.to_path_buf()
        }
        None => return Ok((PresetFile::builtin(), String::new())),
    };
    let file =
        PresetFile::load(&path).with_context(|| format!("加载预设文件 {}", path.display()))?;
    Ok((file, format!("{}#", path.display())))
}

/// 解析 `--kp 0.5..30` 形式的区间（刻度由预设 / 内置默认提供）。
///
/// # Errors
///
/// 区间文本非法时返回错误。
fn range(text: Option<&str>, name: &'static str) -> Result<Option<RangeSpec>> {
    text.map(|text| {
        // 先用线性刻度只解析区间；对数轴"下界必须为正"的检查留给最终解算，
        // 这样只给区间、刻度继承预设时也能得到准确的报错字段。
        let axis = parse_axis(name, text, tuning::Scale::Linear)?;
        Ok(RangeSpec::new(axis.min, axis.max))
    })
    .transpose()
}

/// 用显式 `--kp-scale` 等覆盖合并结果的刻度（允许"只改刻度"）。
fn apply_scales(preset: &mut Preset, cli: &CommonArgs) {
    let set = |axis: &mut Option<RangeSpec>, scale: Option<ScaleArg>| {
        if let (Some(axis), Some(scale)) = (axis.as_mut(), scale) {
            axis.scale = Some(scale.into());
        }
    };
    set(&mut preset.space.kp, cli.kp_scale);
    set(&mut preset.space.ki, cli.ki_scale);
    set(&mut preset.space.kd, cli.kd_scale);
    set(&mut preset.space.feedforward, cli.feedforward_scale);
}

/// 用显式 `--jitter` 覆盖域随机化幅度。
///
/// # Errors
///
/// 抖动文本不是 `key=value` 或含未知键时返回错误。
fn apply_jitter(preset: &mut Preset, cli: &CommonArgs) -> Result<()> {
    let Some(spec) = cli.sim.jitter.as_deref() else {
        return Ok(());
    };
    for part in spec.split(',').map(str::trim).filter(|part| !part.is_empty()) {
        let (key, value) =
            part.split_once('=').with_context(|| format!("抖动参数 '{part}' 应为 key=value"))?;
        let value: f64 =
            value.trim().parse().with_context(|| format!("抖动参数 '{part}' 的数值无法解析"))?;
        match key.trim() {
            "gain" => preset.sim.gain_pct = Some(value as f32),
            "tau" => preset.sim.tau_pct = Some(value as f32),
            "delay" => preset.sim.delay_ticks_max = Some(value.max(0.0) as u32),
            "friction" => preset.sim.friction_pct = Some(value as f32),
            other => bail!("未知抖动参数 '{other}'（可用 gain/tau/delay/friction）"),
        }
    }
    Ok(())
}

/// 后端选择：把两种评估器收进一个枚举，报告与后处理因此不必 `Box<dyn>`。
/// Test-only offline evaluator for search regression tests.
struct SimEvaluator {
    ensemble: sim_harness::PlantEnsemble,
    scenario: experiment::Scenario,
    limits: sim_harness::LoopLimits,
    objective: tuning::cost::Objective,
    robust_weight: f64,
}

impl SimEvaluator {
    /// Build an offline evaluator.
    #[must_use]
    pub fn new(
        ensemble: sim_harness::PlantEnsemble,
        scenario: experiment::Scenario,
        limits: sim_harness::LoopLimits,
        objective: tuning::cost::Objective,
        robust_weight: f64,
    ) -> Self {
        Self { ensemble, scenario, limits, objective, robust_weight }
    }
}

impl Evaluator for SimEvaluator {
    fn evaluate(&self, gains: &VelocityGains) -> Score {
        let mut costs = Vec::with_capacity(self.ensemble.len());
        let mut nominal = None;
        let mut worst_verdict = tuning::cost::Verdict::Ok;
        for (index, plant) in self.ensemble.iter().enumerate() {
            let score = match sim_harness::simulate(*gains, plant, &self.scenario, self.limits) {
                Ok(trace) => self.objective.score(&trace),
                Err(error) => {
                    tuning::cost::Score::penalized(tuning::cost::Objective::from_error(error))
                }
            };
            if index == 0 {
                nominal = Some(score);
            }
            if !score.verdict.is_ok() && worst_verdict.is_ok() {
                worst_verdict = score.verdict;
            }
            costs.push(score.cost);
        }
        let count = costs.len().max(1) as f64;
        let mean = costs.iter().sum::<f64>() / count;
        let worst = costs.iter().copied().fold(f64::NEG_INFINITY, f64::max);
        let cost_value = (1.0 - self.robust_weight) * mean + self.robust_weight * worst;
        let nominal = nominal
            .unwrap_or_else(|| tuning::cost::Score::penalized(tuning::cost::Verdict::Rejected));
        let verdict = if nominal.verdict.is_ok() { worst_verdict } else { nominal.verdict };
        tuning::cost::Score { cost: cost_value, verdict, metrics: nominal.metrics }
    }

    fn describe(&self) -> String {
        format!("sim(ensemble={}, robust_weight={:.2})", self.ensemble.len(), self.robust_weight)
    }
}

/// Tuning adapter around the hardware-only bench runner.
struct TuningBench {
    runner: BenchRunner,
    objective: Objective,
    continue_on_abort: bool,
    best: Mutex<Option<(f64, experiment::Trace)>>,
    aborts: Mutex<Vec<String>>,
    describe: String,
}

impl TuningBench {
    fn open(
        link: can::CanLink,
        config: BenchConfig,
        objective: Objective,
        continue_on_abort: bool,
    ) -> Result<Self> {
        let describe = format!(
            "bench(esc={}, name={}, limit={} raw, target={} rpm, trial={:.1}s, gap={}ms)",
            config.esc.esc_id,
            config.esc.name,
            config.esc.current_limit,
            config.scenario.target_rpm,
            config.scenario.total_s(),
            config.between_trials.as_millis()
        );
        let runner = BenchRunner::open(link, config).map_err(|e| anyhow::anyhow!("{e}"))?;
        Ok(Self {
            runner,
            objective,
            continue_on_abort,
            best: Mutex::new(None),
            aborts: Mutex::new(Vec::new()),
            describe,
        })
    }

    fn best_trace(&self) -> Option<experiment::Trace> {
        self.best
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .as_ref()
            .map(|(_, trace)| trace.clone())
    }

    fn aborts(&self) -> Vec<String> {
        self.aborts.lock().unwrap_or_else(std::sync::PoisonError::into_inner).clone()
    }
}

impl Evaluator for TuningBench {
    fn evaluate(&self, gains: &VelocityGains) -> Score {
        let outcome = self.runner.run_trial(gains);
        let score = if let Some(reason) = outcome.abort {
            self.aborts
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner)
                .push(format!("{}: {reason}", self.describe));
            Score::penalized(verdict_for(&reason))
        } else {
            match experiment::StepMetrics::from_trace(&outcome.trace, &self.scenario()) {
                Some(metrics) => self.objective.score_metrics(metrics),
                None => Score::penalized(Verdict::Rejected),
            }
        };
        let mut best = self.best.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
        if best.as_ref().is_none_or(|(cost, _)| score.cost < *cost) {
            *best = Some((score.cost, outcome.trace));
        }
        if !score.verdict.is_ok() && !self.continue_on_abort {
            tracing::warn!(verdict = score.verdict.label(), "bench trial did not pass");
        }
        score
    }

    fn describe(&self) -> String {
        self.describe.clone()
    }
}

impl TuningBench {
    fn scenario(&self) -> experiment::Scenario {
        self.runner.scenario()
    }
}

/// Map a safety abort to a tuning verdict.
fn verdict_for(abort: &bench::Abort) -> Verdict {
    match abort {
        bench::Abort::Overspeed { .. } | bench::Abort::OverTemperature { .. } => Verdict::Overspeed,
        bench::Abort::FeedbackLost { .. }
        | bench::Abort::Timeout { .. }
        | bench::Abort::Cancelled => Verdict::Rejected,
    }
}

enum Backend {
    Sim(Box<SimEvaluator>),
    Bench(Box<TuningBench>),
}

impl Evaluator for Backend {
    fn evaluate(&self, gains: &VelocityGains) -> Score {
        match self {
            Self::Sim(evaluator) => evaluator.evaluate(gains),
            Self::Bench(evaluator) => evaluator.evaluate(gains),
        }
    }

    fn describe(&self) -> String {
        match self {
            Self::Sim(evaluator) => evaluator.describe(),
            Self::Bench(evaluator) => evaluator.describe(),
        }
    }
}

impl Backend {
    fn bench(&self) -> Option<&TuningBench> {
        match self {
            Self::Bench(evaluator) => Some(evaluator),
            Self::Sim(_) => None,
        }
    }
}

/// 场景的文本标签（报告 / `presets` 子命令用）。
fn profile_label(profile: SetpointProfile) -> &'static str {
    match profile {
        SetpointProfile::Step => "step",
        SetpointProfile::RampAndHold => "ramp-and-hold",
        SetpointProfile::Staircase { .. } => "staircase",
        SetpointProfile::UpDown => "up-down",
    }
}

/// 由解算后的权重与场景构造目标函数。
fn objective(settings: &Settings, limits: LoopLimits) -> Objective {
    Objective::new(settings.tuning.weights, settings.tuning.scenario, limits)
}

/// 已知的机械 / 安全参数（CLI > `chassis.toml` > 内置默认）。
#[derive(Debug, Clone)]
struct Hardware {
    /// 轮名。
    name: String,
    /// 电调 ID。
    esc_id: u8,
    /// 安装方向。
    direction: f32,
    /// 减速比。
    gear_ratio: f32,
    /// 限幅与型号。
    limits: LoopLimits,
    /// 基线增益（来自 `--config`；仅用于对比）。
    baseline: Option<VelocityGains>,
}

/// 解析机械 / 安全参数：显式 CLI 覆盖 `--config`，`--config` 覆盖内置默认。
///
/// 这些参数**不参与搜索**（它们是安全与机械约束），但必须来自同一份配置——
/// 否则"整定工具用的限流"和"守护进程用的限流"会悄悄不一致。
fn hardware(settings: &Settings) -> Result<Hardware> {
    let config = settings
        .config
        .as_ref()
        .map(|path| Config::load(path).with_context(|| format!("读取配置 {}", path.display())))
        .transpose()?;

    let motor = match (&config, &settings.motor) {
        (Some(config), name) => {
            let index = config.motor_index(name).with_context(|| {
                format!(
                    "配置里没有名为 '{name}' 的电机（可用：{}）",
                    config.motors.iter().map(|m| m.name.as_str()).collect::<Vec<_>>().join(", ")
                )
            })?;
            Some(&config.motors[index])
        }
        (None, _) => None,
    };

    let limits = LoopLimits {
        current_limit_raw: settings
            .current_limit
            .or_else(|| motor.map(|m| m.current_limit))
            .unwrap_or(12_000),
        model: settings
            .model
            .map(Into::into)
            .or_else(|| motor.map(|m| m.model.into()))
            .unwrap_or(EscModel::C620),
    };
    if limits.current_limit_raw <= 0 {
        bail!("电流限幅必须为正，得到 {}", limits.current_limit_raw);
    }

    Ok(Hardware {
        name: settings.motor.clone(),
        esc_id: settings.bench.esc_id.or_else(|| motor.map(|m| m.esc_id)).unwrap_or(1),
        direction: settings.bench.direction.or_else(|| motor.map(|m| m.direction)).unwrap_or(1.0),
        gear_ratio: settings
            .bench
            .gear_ratio
            .or_else(|| motor.map(|m| m.gear_ratio))
            .unwrap_or(19.203),
        baseline: motor.map(chassis_config::MotorConfig::velocity_gains),
        limits,
    })
}

/// 线程池：真机后端强制单线程（只有一条总线），仿真后端默认吃满所有核。
fn install_thread_pool(threads: usize) -> Result<()> {
    let mut builder = rayon::ThreadPoolBuilder::new();
    if threads > 0 {
        builder = builder.num_threads(threads);
    }
    builder.build_global().context("初始化线程池失败")?;
    Ok(())
}

fn progress_bar(settings: &Settings) -> ProgressBar {
    ProgressBar::new(settings.tuning.search.samples as u64 + settings.tuning.search.top_k as u64)
}

/// 构造后端（仿真或真机）。
fn build_backend(
    settings: &Settings,
    hardware: &Hardware,
    limits: LoopLimits,
    objective: Objective,
) -> Result<Backend> {
    match settings.tuning.backend {
        BackendSpec::Sim => {
            let ensemble = PlantEnsemble::randomized(
                settings.tuning.plant,
                settings.tuning.tolerances,
                settings.tuning.ensemble,
                settings.tuning.search.seed,
            );
            Ok(Backend::Sim(Box::new(SimEvaluator::new(
                ensemble,
                settings.tuning.scenario,
                limits,
                objective,
                settings.tuning.robust_weight,
            ))))
        }
        BackendSpec::Bench => {
            Ok(Backend::Bench(Box::new(open_bench(settings, hardware, limits, objective)?)))
        }
    }
}

// ---------------------------------------------------------------- presets

/// 列出预设文件里的全部预设（只读，不搜索、不碰硬件）。
fn presets_cmd(args: &PresetsArgs) -> Result<ExitCode> {
    let file = PresetFile::load(&args.preset)
        .with_context(|| format!("加载预设文件 {}", args.preset.display()))?;
    println!("=== 预设文件 {}（version {}）===", args.preset.display(), file.version);
    println!("共 {} 个预设", file.preset.len());
    for (name, preset) in &file.preset {
        let merged = Preset::builtin().overlay(preset);
        let tuning = merged.to_tuning().with_context(|| format!("解算预设 '{name}' 失败"))?;
        let envelope =
            merged.bench_envelope().with_context(|| format!("解算预设 '{name}' 的安全包络失败"))?;
        let mark =
            if file.default_preset.as_deref() == Some(name.as_str()) { "（默认）" } else { "" };
        println!("\n{name}{mark}：{}", preset.description.as_deref().unwrap_or("（无说明）"));
        println!(
            "  后端 {}｜场景 {}｜目标 {:.0} rpm｜dt {:.0}µs｜样本 {}｜top-k {}｜种子 {}｜求解器 {}",
            tuning.backend.name(),
            profile_label(tuning.scenario.profile),
            tuning.scenario.target_rpm,
            tuning.scenario.dt_s * 1e6,
            tuning.search.samples,
            tuning.search.top_k,
            tuning.search.seed,
            tuning.search.solver.name(),
        );
        println!("  空间：{}", tuning.space.describe());
        println!(
            "  权重：{}｜验收 超调 ≤ {:.1}% / 稳态误差 ≤ {:.1}%",
            tuning.weights.describe(),
            tuning.acceptance.max_overshoot_pct,
            tuning.acceptance.max_ss_error_pct
        );
        println!(
            "  被控对象 {}｜集成 {}｜鲁棒权重 {:.2}｜抖动 gain±{:.0}% tau±{:.0}% delay≤{}拍 friction±{:.0}%",
            tuning.plant_spec.name(),
            tuning.ensemble,
            tuning.robust_weight,
            tuning.tolerances.gain_pct * 100.0,
            tuning.tolerances.tau_pct * 100.0,
            tuning.tolerances.delay_ticks_max,
            tuning.tolerances.friction_pct * 100.0,
        );
        println!(
            "  安全包络：过速 {:.0} rpm｜温度 ≤ {}℃｜试验超时 {}ms｜启动等待 {}ms｜试验间隔 {}ms｜复验 {} 次｜安全事件后{}",
            envelope.max_rpm,
            envelope.max_temp_c,
            envelope.trial_timeout_ms,
            envelope.startup_timeout_ms,
            envelope.between_trials_ms,
            envelope.validate_runs,
            if envelope.continue_on_abort { "继续" } else { "收工" },
        );
    }
    println!("\n用法：chassis-tune sweep --preset {} --preset-name <NAME>", args.preset.display());
    Ok(ExitCode::SUCCESS)
}

// ---------------------------------------------------------------- sweep

fn sweep_cmd(settings: &Settings) -> Result<ExitCode> {
    let hardware = hardware(settings)?;
    let limits = hardware.limits;
    let objective = objective(settings, limits);
    let config = settings.tuning.search.clone();
    install_thread_pool(match settings.tuning.backend {
        BackendSpec::Bench => 1,
        BackendSpec::Sim => settings.tuning.threads,
    })?;

    println!("=== chassis-tune sweep ===");
    println!("超参数来源：{}", settings.source);
    println!("参数空间：{}", settings.tuning.space.describe());
    println!("场景：{}", tuning::search::scenario_summary(&settings.tuning.scenario));
    println!(
        "轮子：{}｜电调 {}｜方向 {:+.0}｜减速比 {:.3}｜限流 {} raw",
        hardware.name,
        hardware.esc_id,
        hardware.direction,
        hardware.gear_ratio,
        limits.current_limit_raw
    );

    let evaluator = build_backend(settings, &hardware, limits, objective)?;
    println!("后端：{}", evaluator.describe());
    println!(
        "种子：{}｜粗扫 {}｜top-k {}｜求解器 {}",
        config.seed,
        config.samples,
        config.top_k,
        config.solver.name()
    );

    if settings.tuning.backend == BackendSpec::Bench {
        let trials = config.samples as u64
            + config.top_k as u64 * 2
            + settings.envelope.validate_runs as u64;
        let per_trial = settings.tuning.scenario.total_s()
            + settings.envelope.between_trials_ms as f32 / 1000.0;
        println!(
            "⚠ 真机模式：轮子会转！预计 {} 次试验 × {:.1}s ≈ {:.0}s",
            trials,
            per_trial,
            trials as f32 * per_trial
        );
    }

    let bar = progress_bar(settings);
    let ranked = sweep(&settings.tuning.space, &config, &evaluator, Some(&bar))?;
    bar.finish_and_clear();

    // 最优轨迹：仿真后端重放名义模型；真机后端用搜索期间记录的最好一次。
    let trace = match &evaluator {
        Backend::Sim(_) => sim_harness::simulate(
            ranked.best.gains,
            &settings.tuning.plant,
            &settings.tuning.scenario,
            limits,
        )
        .ok(),
        Backend::Bench(evaluator) => evaluator.best_trace(),
    };

    let ctx = ReportContext {
        out_dir: settings.out_dir.clone(),
        space: settings.tuning.space,
        config: config.clone(),
        scenario: settings.tuning.scenario,
        limits,
        backend: evaluator.describe(),
        motor_name: settings.motor.clone(),
        max_overshoot_pct: settings.tuning.acceptance.max_overshoot_pct,
        max_ss_error_pct: settings.tuning.acceptance.max_ss_error_pct,
        best_trace: trace,
    };
    let written = write_reports(&ctx, &ranked)?;
    print_ranked(&ranked);
    if settings.json {
        println!("\n{}", serde_json::to_string_pretty(&summary_json(&ctx, &ranked))?);
    }
    println!("\n产物：");
    for path in &written {
        println!("  {}", path.display());
    }

    compare_with_baseline(&evaluator, &hardware, &ranked);
    // 真机：对最优增益做重复性复验（仿真到真机是否可迁移的证据）。
    if let Some(bench_evaluator) = evaluator.bench() {
        hil_validate(
            bench_evaluator,
            ranked.best.gains,
            settings.envelope.validate_runs,
            &settings.out_dir,
        )?;
        print_aborts(bench_evaluator);
    }
    if let Some(path) = &settings.write_config {
        write_config(settings, &hardware, ranked.best.gains, path)?;
    }

    let passes = ranked.best.score.metrics.is_some_and(|metrics| ctx.best_passes(&metrics));
    Ok(exit_code(passes))
}

/// 与 `--config` 里的现有增益对比（有基线才有意义）。
fn compare_with_baseline(evaluator: &Backend, hardware: &Hardware, ranked: &Ranked) {
    let Some(baseline) = hardware.baseline else {
        return;
    };
    let base = evaluator.evaluate(&baseline);
    println!(
        "\n基线（来自 --config）：kp={:.3} ki={:.3} kd={:.3} ff={:.3}｜成本 {:.4}｜判定 {}",
        baseline.kp,
        baseline.ki,
        baseline.kd,
        baseline.feedforward,
        base.cost,
        base.verdict.label()
    );
    if base.cost > 0.0 {
        println!(
            "  → 整定后成本 {:.4}（基线的 {:.0}%）",
            ranked.best.cost(),
            ranked.best.cost() / base.cost * 100.0
        );
    }
}

/// 打印真机搜索期间触发的安全事件（最多 5 条）。
fn print_aborts(evaluator: &TuningBench) {
    let aborts = evaluator.aborts();
    if aborts.is_empty() {
        return;
    }
    println!("\n⚠ 搜索期间触发 {} 次安全事件：", aborts.len());
    for abort in aborts.iter().take(5) {
        println!("  - {abort}");
    }
}

/// 把整定结果写回一份 `chassis.toml`（只改写目标电机的四个增益）。
fn write_config(
    settings: &Settings,
    hardware: &Hardware,
    gains: VelocityGains,
    path: &Path,
) -> Result<()> {
    let source = settings
        .config
        .as_ref()
        .context("--write-config 必须与 --config 一起使用（否则不知道该从哪份配置派生）")?;
    let mut config =
        Config::load(source).with_context(|| format!("读取配置 {}", source.display()))?;
    config
        .set_motor_gains_by_name(&hardware.name, gains)
        .with_context(|| format!("配置里没有名为 '{}' 的电机", hardware.name))?;
    let text = config.to_toml_string().context("序列化配置失败")?;
    std::fs::write(path, text).with_context(|| format!("写入 {}", path.display()))?;
    println!(
        "\n已写出 {}（仅 {} 的 kp/ki/kd/feedforward 改写为 {:.3}/{:.3}/{:.3}/{:.3}）",
        path.display(),
        hardware.name,
        gains.kp,
        gains.ki,
        gains.kd,
        gains.feedforward
    );
    Ok(())
}

/// `hil-validation.csv` 的一行。
#[derive(Debug, Serialize)]
struct HilRow {
    run: usize,
    cost: f64,
    verdict: &'static str,
    settled: bool,
    overshoot_pct: f32,
    ss_error_pct: f32,
    settling_time_s: f32,
    peak_effort_raw: f32,
}

/// 真机重复性复验：同一组增益跑 `runs` 次，写出 `hil-validation.csv`。
fn hil_validate(
    evaluator: &TuningBench,
    gains: VelocityGains,
    runs: usize,
    out_dir: &Path,
) -> Result<()> {
    let runs = runs.max(1);
    println!("\n=== 真机复验（{runs} 次）===");
    let mut rows = Vec::with_capacity(runs);
    for run in 0..runs {
        let score = evaluator.evaluate(&gains);
        let metrics = score.metrics;
        let row = HilRow {
            run: run + 1,
            cost: score.cost,
            verdict: score.verdict.label(),
            settled: metrics.is_some_and(|m| m.settled),
            overshoot_pct: metrics.map_or(f32::NAN, |m| m.overshoot_pct),
            ss_error_pct: metrics.map_or(f32::NAN, |m| m.ss_error_pct),
            settling_time_s: metrics.map_or(f32::NAN, |m| m.settling_time_s),
            peak_effort_raw: metrics.map_or(f32::NAN, |m| m.peak_effort_raw),
        };
        println!(
            "  第 {} 次：{}｜超调 {:.1}%｜稳态误差 {:.2}%｜调节 {:.0}ms",
            row.run,
            row.verdict,
            row.overshoot_pct,
            row.ss_error_pct,
            row.settling_time_s * 1000.0
        );
        rows.push(row);
    }
    let ok = rows.iter().filter(|row| row.verdict == "ok").count();
    println!("复验结果：{ok} / {runs} 次达标");

    let path = out_dir.join("hil-validation.csv");
    let mut writer =
        csv::Writer::from_path(&path).with_context(|| format!("写出 {}", path.display()))?;
    for row in &rows {
        writer.serialize(row)?;
    }
    writer.flush()?;
    println!("  → {}", path.display());
    Ok(())
}

fn print_ranked(ranked: &Ranked) {
    println!("\n=== Top 5 ===");
    println!(
        "{:<4} {:<8} {:>9} {:>9} {:>9} {:>9} {:>10} {:<11}",
        "#", "阶段", "kp", "ki", "kd", "ff", "成本", "判定"
    );
    for (rank, trial) in ranked.top(5).iter().enumerate() {
        println!(
            "{:<4} {:<8} {:>9.3} {:>9.3} {:>9.3} {:>9.3} {:>10.4} {:<11}",
            rank + 1,
            trial.phase.label(),
            trial.gains.kp,
            trial.gains.ki,
            trial.gains.kd,
            trial.gains.feedforward,
            trial.cost(),
            trial.score.verdict.label()
        );
    }
    let best = &ranked.best;
    println!(
        "\n最优：kp={:.3} ki={:.3} kd={:.3} ff={:.3}（成本 {:.4}，判定 {}）",
        best.gains.kp,
        best.gains.ki,
        best.gains.kd,
        best.gains.feedforward,
        best.cost(),
        best.score.verdict.label()
    );
    if let Some(metrics) = best.score.metrics {
        println!(
            "指标：上升 {:.0}ms｜超调 {:.1}%｜调节 {:.0}ms｜稳态误差 {:.2}%｜峰值电流 {:.0} raw｜饱和 {:.1}%",
            metrics.rise_time_s * 1000.0,
            metrics.overshoot_pct,
            metrics.settling_time_s * 1000.0,
            metrics.ss_error_pct,
            metrics.peak_effort_raw,
            metrics.saturated_pct
        );
    }
    println!(
        "评估 {} 次：达标 {} / {}（{} 次被硬约束拦下）",
        ranked.evals,
        ranked.ok_count(),
        ranked.trials.len(),
        ranked.rejected
    );
}

fn summary_json(ctx: &ReportContext, ranked: &Ranked) -> serde_json::Value {
    serde_json::json!({
        "backend": ctx.backend,
        "seed": ctx.config.seed,
        "samples": ctx.config.samples,
        "evals": ranked.evals,
        "ok": ranked.ok_count(),
        "rejected": ranked.rejected,
        "best": {
            "kp": ranked.best.gains.kp,
            "ki": ranked.best.gains.ki,
            "kd": ranked.best.gains.kd,
            "feedforward": ranked.best.gains.feedforward,
            "cost": ranked.best.cost(),
            "verdict": ranked.best.score.verdict.label(),
        },
    })
}

fn exit_code(passes: bool) -> ExitCode {
    if passes { ExitCode::SUCCESS } else { ExitCode::from(1) }
}

// ---------------------------------------------------------------- validate

fn validate_cmd(settings: &Settings, gains_text: &str) -> Result<ExitCode> {
    let hardware = hardware(settings)?;
    let gains = parse_gains(gains_text)?;
    let limits = hardware.limits;
    let objective = objective(settings, limits);
    // 单组增益不需要并行：单线程既省事又让真机路径的顺序确定。
    install_thread_pool(1)?;

    let evaluator = build_backend(settings, &hardware, limits, objective.clone())?;
    println!("=== chassis-tune validate ===");
    println!("超参数来源：{}", settings.source);
    println!("后端：{}", evaluator.describe());
    println!("增益：kp={} ki={} kd={} ff={}", gains.kp, gains.ki, gains.kd, gains.feedforward);

    let score = evaluator.evaluate(&gains);
    let acceptance = settings.tuning.acceptance;
    let passes = score.metrics.is_some_and(|metrics| {
        objective.passes(&metrics, acceptance.max_overshoot_pct, acceptance.max_ss_error_pct)
    });
    println!("判定：{}（成本 {:.6}）", score.verdict.label(), score.cost);
    match score.metrics {
        Some(metrics) => {
            println!(
                "上升 {:.0}ms｜超调 {:.1}%｜调节 {:.0}ms｜稳态误差 {:.2}%｜峰值电流 {:.0} raw｜饱和 {:.1}%",
                metrics.rise_time_s * 1000.0,
                metrics.overshoot_pct,
                metrics.settling_time_s * 1000.0,
                metrics.ss_error_pct,
                metrics.peak_effort_raw,
                metrics.saturated_pct
            );
            println!(
                "验收（超调 ≤ {:.1}%，稳态误差 ≤ {:.1}%）：{}",
                acceptance.max_overshoot_pct,
                acceptance.max_ss_error_pct,
                if passes { "✓ 通过" } else { "✗ 未通过" }
            );
        }
        None => println!("没有可用指标（{}）", tuning::search::verdict_hint(score.verdict)),
    }
    Ok(exit_code(passes))
}

/// `kp,ki,kd,ff` → 增益组。
fn parse_gains(text: &str) -> Result<VelocityGains> {
    let parts: Vec<&str> = text.split(',').map(str::trim).collect();
    if parts.len() != 4 {
        bail!("--gains 需要四个逗号分隔的数值（kp,ki,kd,feedforward），得到 '{text}'");
    }
    let value = |index: usize| -> Result<f32> {
        parts[index]
            .parse::<f32>()
            .with_context(|| format!("--gains 第 {} 项 '{}' 不是数值", index + 1, parts[index]))
    };
    let gains = VelocityGains::new(value(0)?, value(1)?, value(2)?, value(3)?);
    if !gains.is_finite() {
        bail!("--gains 必须是有限值");
    }
    Ok(gains)
}

// ---------------------------------------------------------------- bench

/// 打开真机后端（含安全横幅与确认门控）。
fn open_bench(
    settings: &Settings,
    hardware: &Hardware,
    limits: LoopLimits,
    objective: Objective,
) -> Result<TuningBench> {
    let bench = &settings.bench;
    let envelope_spec = settings.envelope;
    if !bench.i_know_the_wheel_spins {
        bail!(
            "真机模式必须显式确认：加 `--i-know-the-wheel-spins`。\n  \
             前提：轮子架空或整车固定、急停可及、电流限流已按台架设置（当前 {} raw）。",
            limits.current_limit_raw
        );
    }
    println!("⚠ 台架模式：轮子会以最高 {:.0} rpm（转子）转动。", envelope_spec.max_rpm);
    println!("  确认：轮子已架空或整车固定，急停可及，ctrl-c 随时安全停机。");

    let link = open_link(
        &bench.device,
        bench.serial_baud,
        bench.can_speed.into(),
        bench.interface.as_deref(),
    )?;

    let mut esc = EscConfig::gm3508(hardware.name.clone(), hardware.esc_id, hardware.direction);
    esc.gear_ratio = hardware.gear_ratio;
    esc.current_limit = limits.current_limit_raw;
    esc.model = limits.model;

    let envelope = SafetyEnvelope::new()
        .with_overspeed(envelope_spec.max_rpm, Duration::from_millis(60))
        .with_temperature_max(envelope_spec.max_temp_c)
        .with_feedback_timeout(Duration::from_millis(200))
        .with_trial_timeout(Duration::from_millis(envelope_spec.trial_timeout_ms));

    let mut config = BenchConfig::new(esc, settings.tuning.scenario, envelope);
    config.between_trials = Duration::from_millis(envelope_spec.between_trials_ms);
    config.startup_timeout = Duration::from_millis(envelope_spec.startup_timeout_ms);

    TuningBench::open(link, config, objective, envelope_spec.continue_on_abort)
        .map_err(|e| anyhow::anyhow!("{e}"))
}

#[cfg(test)]
mod tests {
    use super::*;

    /// 一份最小可用配置（四轮，顺序 FL/FR/RL/RR）。
    const CONFIG: &str = r#"
[can]
interface = "can0"

[mecanum]
half_length = 0.2
half_width = 0.25
wheel_radius = 0.0762

[[motor]]
name = "front_left"
esc_id = 3
direction = -1
gear_ratio = 19.203
current_limit = 6000
kp = 2.0
ki = 10.0
kd = 0.0
feedforward = 0.0

[[motor]]
name = "front_right"
esc_id = 4
direction = 1
gear_ratio = 19.203
current_limit = 6000
kp = 2.0
ki = 10.0
kd = 0.0
feedforward = 0.0

[[motor]]
name = "rear_left"
esc_id = 5
direction = -1
gear_ratio = 19.203
current_limit = 6000
kp = 2.0
ki = 10.0
kd = 0.0
feedforward = 0.0

[[motor]]
name = "rear_right"
esc_id = 6
direction = 1
gear_ratio = 19.203
current_limit = 6000
kp = 2.0
ki = 10.0
kd = 0.0
feedforward = 0.0
"#;

    fn write_temp(name: &str, text: &str) -> PathBuf {
        let path = std::env::temp_dir().join(format!("chassis-tune-cli-{name}.toml"));
        std::fs::write(&path, text).unwrap();
        path
    }

    /// 仓库里随代码一起评审的预设文件。
    fn repo_preset_path() -> PathBuf {
        Path::new(env!("CARGO_MANIFEST_DIR")).join("../../config/tune.toml")
    }

    fn args_with(extra: &[&str]) -> CommonArgs {
        let mut argv = vec!["chassis-tune", "sweep"];
        argv.extend_from_slice(extra);
        match Cli::parse_from(argv).command {
            Command::Sweep(sweep) => sweep.common,
            _ => panic!("expected sweep"),
        }
    }

    /// 解算后的设置（内置默认 + 额外 CLI）。
    fn settings_with(extra: &[&str]) -> Settings {
        args_with(extra).resolve().unwrap()
    }

    #[test]
    fn hardware_defaults_without_config() {
        let settings = settings_with(&[]);
        let hardware = hardware(&settings).unwrap();
        assert_eq!(hardware.esc_id, 1);
        assert!((hardware.direction - 1.0).abs() < 1e-6);
        assert!((hardware.gear_ratio - 19.203).abs() < 1e-6);
        assert_eq!(hardware.limits.current_limit_raw, 12_000);
        assert!(hardware.baseline.is_none());
    }

    #[test]
    fn hardware_takes_mechanical_parameters_from_config() {
        let path = write_temp("mech", CONFIG);
        let settings =
            settings_with(&["--config", path.to_str().unwrap(), "--motor", "front_left"]);
        let hardware = hardware(&settings).unwrap();
        assert_eq!(hardware.esc_id, 3, "电调 ID 必须来自配置");
        assert_eq!(hardware.direction.to_bits(), (-1.0f32).to_bits());
        assert_eq!(hardware.limits.current_limit_raw, 6000);
        assert_eq!(hardware.baseline.unwrap(), VelocityGains::new(2.0, 10.0, 0.0, 0.0));
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn explicit_cli_overrides_the_config() {
        let path = write_temp("override", CONFIG);
        let settings = settings_with(&[
            "--config",
            path.to_str().unwrap(),
            "--motor",
            "front_left",
            "--current-limit",
            "1500",
        ]);
        let hardware = hardware(&settings).unwrap();
        assert_eq!(hardware.limits.current_limit_raw, 1500, "显式 CLI 必须覆盖配置");
        assert_eq!(hardware.esc_id, 3, "未显式给出的字段仍取配置");
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn unknown_motor_name_is_rejected() {
        let path = write_temp("unknown", CONFIG);
        let settings = settings_with(&["--config", path.to_str().unwrap(), "--motor", "ghost"]);
        let error = hardware(&settings).unwrap_err().to_string();
        assert!(error.contains("ghost"), "{error}");
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn write_config_only_touches_the_target_motor() {
        let source = write_temp("write-src", CONFIG);
        let out = std::env::temp_dir().join("chassis-tune-cli-write-out.toml");
        let settings = settings_with(&[
            "--config",
            source.to_str().unwrap(),
            "--motor",
            "front_left",
            "--write-config",
            out.to_str().unwrap(),
        ]);
        let hardware = hardware(&settings).unwrap();
        let gains = VelocityGains::new(4.5, 22.0, 0.25, 0.75);
        write_config(&settings, &hardware, gains, &out).unwrap();

        let written = Config::load(&out).unwrap();
        assert_eq!(written.motors[0].velocity_gains(), gains);
        assert_eq!(
            written.motors[1].velocity_gains(),
            VelocityGains::new(2.0, 10.0, 0.0, 0.0),
            "其它电机不得被改写"
        );
        assert_eq!(written.motors[0].current_limit, 6000, "安全字段不得被改写");
        assert_eq!(written.motors[0].direction.to_bits(), (-1.0f32).to_bits());
        let _ = std::fs::remove_file(&source);
        let _ = std::fs::remove_file(&out);
    }

    #[test]
    fn write_config_requires_config() {
        let settings = settings_with(&[]);
        let hardware = hardware(&settings).unwrap();
        let out = std::env::temp_dir().join("chassis-tune-cli-never.toml");
        let error =
            write_config(&settings, &hardware, VelocityGains::ZERO, &out).unwrap_err().to_string();
        assert!(error.contains("--config"), "{error}");
        assert!(!out.exists(), "报错时不得写出文件");
    }

    // ------------------------------------------------ 超参数优先级

    #[test]
    fn defaults_match_the_documented_builtin_values() {
        let settings = settings_with(&[]);
        assert_eq!(settings.source, "内置默认");
        let tuning = &settings.tuning;
        assert_eq!(tuning.backend, BackendSpec::Sim);
        assert!((tuning.space.kp.min - 0.5).abs() < 1e-12);
        assert!((tuning.space.kp.max - 30.0).abs() < 1e-12);
        assert_eq!(tuning.search.samples, 512);
        assert_eq!(tuning.search.seed, 20_260_101);
        assert!((tuning.scenario.target_rpm - 1500.0).abs() < 1e-6);
        assert!((tuning.acceptance.max_overshoot_pct - 20.0).abs() < 1e-6);
        assert_eq!(tuning.plant_spec, PlantSpec::Gm3508Bench);
        assert_eq!(settings.envelope.validate_runs, 3);
    }

    #[test]
    fn preset_supplies_hyperparameters_and_cli_overrides_them() {
        let path = write_temp(
            "preset",
            r#"
version = 1
default_preset = "quick"

[preset.quick]
description = "快跑"

[preset.quick.space]
kp = { min = 1.0, max = 4.0, scale = "log" }

[preset.quick.search]
samples = 24
top_k = 3
seed = 7

[preset.other]

[preset.other.search]
samples = 99
"#,
        );

        // 预设生效，来源可追溯。
        let settings = settings_with(&["--preset", path.to_str().unwrap()]);
        assert!(settings.source.ends_with("#quick"), "{}", settings.source);
        assert_eq!(settings.tuning.search.samples, 24);
        assert_eq!(settings.tuning.search.top_k, 3);
        assert_eq!(settings.tuning.search.seed, 7);
        assert!((settings.tuning.space.kp.max - 4.0).abs() < 1e-12);
        // 预设没写的项继续沿用内置默认。
        assert_eq!(settings.tuning.search.max_iters, 200);
        assert!((settings.tuning.scenario.target_rpm - 1500.0).abs() < 1e-6);

        // 显式 CLI 覆盖预设的同一项，但不影响预设的其它项。
        let settings = settings_with(&["--preset", path.to_str().unwrap(), "--samples", "128"]);
        assert_eq!(settings.tuning.search.samples, 128, "CLI 必须覆盖预设");
        assert_eq!(settings.tuning.search.top_k, 3, "预设的其它项必须保留");
        assert_eq!(settings.tuning.search.seed, 7);

        // 按名字选另一个预设。
        let settings =
            settings_with(&["--preset", path.to_str().unwrap(), "--preset-name", "other"]);
        assert!(settings.source.ends_with("#other"), "{}", settings.source);
        assert_eq!(settings.tuning.search.samples, 99);

        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn unknown_preset_name_lists_the_available_ones() {
        let path = write_temp("unknown-preset", "version = 1\n[preset.alpha]\n[preset.beta]\n");
        let error = args_with(&["--preset", path.to_str().unwrap(), "--preset-name", "ghost"])
            .resolve()
            .unwrap_err()
            .to_string();
        assert!(error.contains("ghost"), "{error}");
        assert!(error.contains("alpha") && error.contains("beta"), "{error}");
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn preset_name_without_file_falls_back_to_the_default_path() {
        // 用临时文件充作"默认路径"，验证"只给 --preset-name"的回落逻辑
        // （不依赖当前工作目录，因此可测）。
        let path = write_temp(
            "fallback",
            "version = 1\ndefault_preset = \"only\"\n[preset.only]\n[preset.only.search]\nsamples = 11\n",
        );
        let (file, prefix) = preset_source(None, Some("only"), &path).unwrap();
        assert!(prefix.ends_with('#'), "{prefix}");
        assert_eq!(file.select(Some("only")).unwrap().search.samples, Some(11));

        // 默认路径不存在时必须给出可操作的报错。
        let error = preset_source(None, Some("only"), Path::new("/definitely/not/here/tune.toml"))
            .unwrap_err()
            .to_string();
        assert!(error.contains("--preset"), "{error}");

        // 没给名字也没给文件 → 内置库。
        let (file, prefix) = preset_source(None, None, &path).unwrap();
        assert!(prefix.is_empty());
        assert!(file.preset.contains_key("default"));

        // 端到端：仓库里的 config/tune.toml 能按名字直接选中（避开 cwd 依赖）。
        let settings = args_with(&[
            "--preset",
            repo_preset_path().to_str().unwrap(),
            "--preset-name",
            "bench_noload",
        ])
        .resolve()
        .unwrap();
        assert!(settings.source.ends_with("#bench_noload"), "{}", settings.source);
        assert_eq!(settings.tuning.backend, BackendSpec::Bench);

        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn presets_cannot_smuggle_safety_parameters() {
        // current_limit / direction / gear_ratio 不是预设的字段：写进去必须报错，
        // 否则预设文件就成了绕过限流的口子。
        for key in ["current_limit = 16384", "direction = -1.0", "gear_ratio = 1.0"] {
            let text = format!("version = 1\n[preset.a.bench]\n{key}\n");
            assert!(PresetFile::parse_str(&text).is_err(), "'{key}' 不得被预设接受");
        }
    }

    #[test]
    fn scale_can_be_overridden_without_touching_the_range() {
        // 只给 --kp-scale：区间必须仍然来自内置默认。
        let settings = settings_with(&["--kp-scale", "linear"]);
        assert_eq!(settings.tuning.space.kp.scale, tuning::Scale::Linear);
        assert!((settings.tuning.space.kp.min - 0.5).abs() < 1e-12);
        assert!((settings.tuning.space.kp.max - 30.0).abs() < 1e-12);

        // 只给区间：刻度必须从内置默认继承（Log）。
        let settings = settings_with(&["--kp", "1..10"]);
        assert!((settings.tuning.space.kp.min - 1.0).abs() < 1e-12);
        assert!((settings.tuning.space.kp.max - 10.0).abs() < 1e-12);
        assert_eq!(settings.tuning.space.kp.scale, tuning::Scale::Log);
    }

    #[test]
    fn continue_on_abort_only_ever_turns_on() {
        assert!(!settings_with(&[]).envelope.continue_on_abort);
        assert!(settings_with(&["--continue-on-abort"]).envelope.continue_on_abort);
    }

    #[test]
    fn the_repo_preset_file_resolves_completely() {
        let path = repo_preset_path();
        let file = PresetFile::load(&path).unwrap_or_else(|error| {
            panic!("{} 必须能被加载：{error}", path.display());
        });
        assert!(!file.preset.is_empty());
        let default = file.default_preset.as_deref().expect("必须指定 default_preset");
        assert!(file.preset.contains_key(default), "default_preset '{default}' 必须存在");
        for (name, preset) in &file.preset {
            let merged = Preset::builtin().overlay(preset);
            let tuning = merged
                .to_tuning()
                .unwrap_or_else(|error| panic!("预设 '{name}' 无法解算：{error}"));
            merged
                .bench_envelope()
                .unwrap_or_else(|error| panic!("预设 '{name}' 的安全包络非法：{error}"));
            assert!(
                preset.description.as_deref().is_some_and(|text| !text.is_empty()),
                "预设 '{name}' 必须有说明（评审时要知道它是给什么工况用的）"
            );
            // 命名约定必须与后端一致：否则一个叫 bench_* 的预设可能悄悄跑离线，
            // 拿它当"台架已验证"的证据就是错的。
            let expected = if name.starts_with("bench_") || name.starts_with("field_") {
                BackendSpec::Bench
            } else {
                BackendSpec::Sim
            };
            assert_eq!(
                tuning.backend,
                expected,
                "预设 '{name}' 的后端 ({}) 与命名约定不符",
                tuning.backend.name()
            );
        }
    }

    #[test]
    fn presets_cmd_lists_every_preset() {
        let args = PresetsArgs { preset: repo_preset_path() };
        assert_eq!(presets_cmd(&args).unwrap(), ExitCode::SUCCESS);
    }

    // ------------------------------------------------ 参数校验

    #[test]
    fn gain_space_comes_from_cli_ranges() {
        let settings = settings_with(&["--kp", "1..10", "--ki", "0..5", "--ki-scale", "linear"]);
        let space = settings.tuning.space;
        assert!((space.kp.min - 1.0).abs() < 1e-12);
        assert!((space.kp.max - 10.0).abs() < 1e-12);
        assert_eq!(space.ki.scale, tuning::Scale::Linear);
    }

    #[test]
    fn bad_ranges_are_rejected() {
        assert!(args_with(&["--kp", "abc"]).resolve().is_err());
        assert!(args_with(&["--kp=-1..5"]).resolve().is_err(), "对数轴的负下界必须被拒绝");
    }

    #[test]
    fn scenario_comes_from_cli() {
        let settings = settings_with(&[
            "--dt-us",
            "2000",
            "--ramp-ms",
            "100",
            "--hold-ms",
            "900",
            "--target-rpm",
            "800",
        ]);
        let scenario = settings.tuning.scenario;
        assert!((scenario.dt_s - 0.002).abs() < 1e-9);
        assert!((scenario.ramp_s - 0.1).abs() < 1e-6);
        assert!((scenario.total_s() - 1.0).abs() < 1e-6);
        assert!((scenario.target_rpm - 800.0).abs() < 1e-6);
    }

    #[test]
    fn degenerate_scenario_is_rejected() {
        assert!(args_with(&["--dt-us", "0"]).resolve().is_err());
        assert!(
            args_with(&["--hold-ms", "0", "--ramp-ms", "0", "--scenario", "step"])
                .resolve()
                .is_err()
        );
    }

    #[test]
    fn gains_parse_requires_four_finite_values() {
        assert_eq!(parse_gains("2, 10, 0, 0.5").unwrap(), VelocityGains::new(2.0, 10.0, 0.0, 0.5));
        assert!(parse_gains("2,10,0").is_err());
        assert!(parse_gains("2,10,0,inf").is_err());
    }

    #[test]
    fn jitter_parses_known_keys_only() {
        let settings = settings_with(&["--jitter", "gain=0.1,tau=0.2,delay=2,friction=0.3"]);
        let tolerances = settings.tuning.tolerances;
        assert!((tolerances.gain_pct - 0.1).abs() < 1e-6);
        assert!((tolerances.tau_pct - 0.2).abs() < 1e-6);
        assert_eq!(tolerances.delay_ticks_max, 2);
        assert!((tolerances.friction_pct - 0.3).abs() < 1e-6);

        assert!(args_with(&["--jitter", "gain"]).resolve().is_err());
        assert!(args_with(&["--jitter", "gain=abc"]).resolve().is_err());
        assert!(args_with(&["--jitter", "unknown=1"]).resolve().is_err());
    }

    #[test]
    fn negative_weights_are_rejected() {
        // 负数必须用 `=` 形式，否则 clap 会把它当成选项。
        assert!(args_with(&["--w-iae=-1"]).resolve().is_err());
        assert!(args_with(&["--max-overshoot=-1"]).resolve().is_err());
    }

    #[test]
    fn cli_requires_a_subcommand() {
        assert!(Cli::try_parse_from(["chassis-tune"]).is_err());
    }
}