# Suspension Lab · 通用悬架模拟器交接

更新：2026-10-31；当前版本 v9。用户目标已由 C6 Z06 专用修改为通用悬架模拟器，要求可直接粘贴任意车型的 AC 数据（含弹簧/阻尼/限位块）来填充，并能按整车质量、配重、簧下质量与轮上刚度计算轮端临界阻尼。本文已提前整理。

## 已完成

- 四角独立选择双叉臂 DWB / 麦弗逊 STRUT / 多连杆 ML，按当前角、当前轴、四角批量载入；ML 从 AC 的 `JOINT0–JOINT4` 键导入。
- 所有支持硬点 XYZ、静态外倾/前束、轮胎半径、轮圈直径、簧载质量、弹簧、慢速/快速压缩与回弹阻尼（含拐点）、限位块刚度与上/下行程可编辑。
- **AC 数据粘贴导入 + 结构自动判定**：不填 TYPE 也能识别双叉臂 / 麦弗逊 —— 有 `WBCAR_TOP_FRONT/REAR` + `WBTYRE_TOP` 判 DWB，有 `STRUT_CAR` + `STRUT_TYRE` 判 STRUT；TYPE 与结构键冲突时按键判定并提示。读取 `TRACK`、`STATIC_CAMBER`、`SPRING_RATE`、`DAMP_BUMP / DAMP_FAST_BUMP / DAMP_FAST_BUMPTHRESHOLD`、回弹同名字段、`BUMP_STOP_RATE / BUMPSTOP_UP / BUMPSTOP_DN`；支持整段文本或 `[FRONT]/[REAR]` 分节选择，粘贴时实时显示判定结果。
- 可设轴距、回弹/压缩扫描范围（±200 mm以内）、扫描步长。
- 保存当前结果为基准；基准、修改后/修正前、修正后三组曲线；撤销、重置、镜像。
- 四轮定位、总前束、推力角、左右轴距、轮心XY位移；三维旋转、正/侧/俯视、动画和等比例轮胎轮圈。
- 八项曲线：camber、toe、caster、KPI、track、shift、减震器行程、MR。
- DWB：上臂两安装点垫片及拉杆长度修正；STRUT：塔顶XYZ及拉杆长度修正。ML 暂不支持垫片/塔顶修正、损伤模式与拉杆优化。
- 定位反算：DWB使用前后垫片+拉杆，STRUT使用塔顶Y/X+拉杆；可匹配后倾，报告残差/不可达，检查全行程后应用。
- 拉杆内点轨迹局部优化：各轴±10 mm，降低前束RMS且峰值不增加，外倾偏差≤0.05°。
- 项目JSON v8、完整曲线CSV、AC数据粘贴导入/导出；兼容旧C6 v3–v6项目与 v7 项目（自动补齐新增阻尼/限位字段）。完整旧v6页面保留为历史入口。
- 减震器 F–v 图（轮端，慢速/快速两段，标注拐点），随参数实时重算。
- **整车质量 / 前配重 / 前簧下质量 / 后簧下质量 / 前轮上刚度 / 后轮上刚度**可填；每角簧载质量自动推导并写回参数区。
- AC 导入时自动带入：前配重 = `CG_LOCATION`、轮上刚度 = `SPRING_RATE`、簧下质量 = `HUB_MASS`；**STRUT 按 AC 规则取 80%**（20% 计入簧上，40 kg 实际需 HUB_MASS=50），DWB 取 100%。
- 轮端临界阻尼 c_crit = 2·√(k_轮上 · m_簧上/角)，前后桥分别计算；F–v 图标出 **1.0× 临界阻尼线**，并显示当前压缩/回弹的 ζ。

目前覆盖三类**刚体悬架运动学**（DWB / STRUT / ML）。AC 的 AXLE 整体桥仍未支持；不能宣称覆盖所有悬架拓扑或整车动力学。

## 工作目录与源码

原项目：`C:/Users/crazy/Documents/deepseek-harness/default-workspace`

新工程：原项目下 `suspension-lab/`。后续应主要修改此目录。

|文件|作用|
|---|---|
|core.cjs|通用数据、AC换算、STRUT内核、两结构扫描/反算/优化|
|dwb-legacy.cjs|冻结的旧DWB内核；构建时嵌入页面|
|ui.js|四角状态、输入、比较、图形、导入导出|
|template.html / style.css|新界面与样式|
|build.cjs|构建自包含index.html|
|index.html|可离线直接打开的新工具|
|verify.cjs / validation.json|独立约束与数值验证及结果|
|verify-browser.cjs / browser-validation.json|Edge操作回归及结果|
|c6-legacy.html|冻结的旧C6 v6单页|
|prepare-deploy.cjs|将新首页、旧页面、预览与交接同步到public-c6|
|handover.md|本交接副本|

原 `c6-suspension-simulator.html`、`c6-core.cjs` 和 AC C6/C7 对照脚本仍属于历史工程。**不要使用旧 build_c6.ps1 覆盖新发布首页。** 新工程不再采用旧单页的大量文本替换维护方式。

用户输出目录：`C:/Users/crazy/Documents/Codex/2026-10-31/c-users-crazy-documents-deepseek-harness/outputs/SuspensionLab`

## 构建、验证与发布

在新工程目录运行：

```powershell
node build.cjs
node verify.cjs
node verify-browser.cjs
node prepare-deploy.cjs
npx --yes wrangler@latest pages deploy ../public-c6 --project-name c6-suspension-simulator --branch main
```

构建和数学内核只需Node内置模块。浏览器回归使用本机绝对路径：
- Playwright：`C:/Users/crazy/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/node_modules/playwright`
- Edge：`C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe`

正式地址仍为 `https://c6-suspension-simulator.pages.dev/`，域名名称沿用历史项目。旧入口 `/c6-legacy.html`；历史AC对照 `/ac-c6.html`、`/ac-vs-c6.html`。不要未经用户要求创建其他Cloudflare项目或修改域名。

**最终发布状态见 deployment.json**。若文件不存在，不可仅凭发布目录已更新就声称已上线。

## 用户提供的数据与假设

```ini
STRUT_CAR=0.24083, 0.46361, -0.07195
STRUT_TYRE=0.12495, -0.10138, 0.00281
WBCAR_BOTTOM_FRONT=0.42459, -0.07639, 0.27323
WBCAR_BOTTOM_REAR=0.43308, -0.13122, -0.05298
WBTYRE_BOTTOM=0.12495, -0.10138, 0.00281
WBCAR_STEER=0.43981, -0.11922, 0.06899
WBTYRE_STEER=0.10431, -0.09843, 0.06899
```

AC采用m，轮心局部坐标：x向内、y向上、z向前。工具采用mm：X向前、Y向外、Z向上。

`X=z*1000; Y=track/2-x*1000; Z=wheelCentreHeight+y*1000`

STRUT_TYRE与下球头完全重合是合法输入。它被作为滑柱轴线下参考点处理，不可直接声称其为真实减震器支架。

初始前桥使用这组STRUT，后桥使用历史DWB，属于演示组合。前桥轮距1600、轮心高度330、轴距2700、camber−0.5°、toe+0.1°及弹簧阻尼都是显式可调假设；未取得车型/实车测量依据。

### AC 阻尼字段（用户给的格式，v8 直接支持）

```ini
DAMP_BUMP=3273
DAMP_FAST_BUMP=1934
DAMP_FAST_BUMPTHRESHOLD=0.050
DAMP_REBOUND=5873
DAMP_FAST_REBOUND=3601
DAMP_FAST_REBOUNDTHRESHOLD=0.130
```

导入后：慢速压缩 3273 N·s/m，0.05 m/s 以上切到 1934；慢速回弹 5873，0.13 m/s 以上切到 3601。与 `SPRING_RATE`、`BUMP_STOP_RATE / BUMPSTOP_UP / DN`、`TRACK`、`STATIC_CAMBER` 一起粘贴即可，无需再手填。

## 数学模型

正前束=内八；每侧局部Y均朝车外。轮轴初始方向归一化 `[tan(toe),1,-tan(camber)]`。前束/外倾从轮轴投影提取，后倾/KPI分别来自转向轴的侧视/正视投影。

DWB：上下臂轴转角、转向节绕球头连线扭转共3自由度；约束上下球头距离、拉杆长度、轮心高度。

STRUT：下摆臂转角及转向节扭转2自由度。下球头C、滑柱下参考D、固定塔顶A、初始轴n、刚体向量v=D0−C0；由 `A−C=q(v+L*n)` 求滑柱长度L与姿态q，再用拉杆长度、轮心高度两约束求解。支持D=C，也支持偏置D。没有用虚构上摆臂替代滑柱。

ML：AC 用 4 根连杆 + 1 根拉杆（JOINT0–JOINT4，每根有车架点 CAR 与转向节点 TYRE）定位转向节；手册明确 ML 不用于前桥。本工具把转向节当作刚体：未知量为轮心平移 u（3）与绕车轴的小转角（3），约束为 5 根连杆长度 + 轮心高度，共 6 个方程，牛顿迭代求解；静态外倾/前束只旋转车轮（不移动 TYRE 点），连杆长度按设计点直接计算；车轮轴由设计轴 a0 叠加转向节旋转得到。ML 没有主销概念，caster/KPI 记为 NaN；没有减震器安装点，行程按轮跳、MR 取 1（AC 的轮端刚度语义）。

两类结构采用静态向正负行程连续求解、有限差分牛顿法、线搜索和失败时细分；无解处曲线断开。数值残差不能解释为硬点测量精度。

MR由减震器长度对轮跳的导数求出。DWB下点固定在下摆臂并随臂转动；STRUT使用滑柱轴线长度。弹簧换算为同轴螺旋弹簧（k_轮端 = k_弹簧·MR²）。

簧下质量：DWB 桥取 `HUB_MASS`；STRUT 桥按 AC 麦弗逊规则取 `HUB_MASS × 0.8`（其余 20% 并入簧上质量），因此 40 kg 的实际簧下需要 HUB_MASS=50。

临界阻尼按单角簧上质量计算：m_簧上/角 = (整车质量 − 2·前簧下 − 2·后簧下) × 配重份额 ÷ 2；c_crit = 2·√(k_轮上 × m_簧上/角)。F–v 图上叠加 F = c_crit·v 的 1.0× 线，ζ = c_当前 / c_crit 分压缩、回弹显示。

阻尼采用两段线性模型（轮端）：压缩段在 `thrBump` 之前用 `dampBump`、之后用 `dampFastBump`；回弹段同理用 `dampRebound / dampFastRebound` 与 `thrReb`。F(v) 分段连续，用于 F–v 图与轮端力估算；限位块参数（刚度、上/下行程）目前只作为输入与显示，尚未参与受力计算。真实阀片曲线、预载与摩擦未建模。

## 与 AC MODDING MANUAL 3.0 的对照

参考 `ASSETTO CORSA MODDING MANUAL 3.0_0.34revD.pdf` 第 31 章（suspensions.ini）复核后确认：

- `SPRING_RATE` 是**单角轮端刚度**；`DAMP_*` 是**轮端阻尼**，两段式的 knee 定义与我们的 F–v 模型一致。
- **STRUT 额外有伪传动比**：手册示例 `0.90 × 20000 = 18000`，即轮端刚度 ≈ MR × SPRING_RATE。导入 STRUT 时工具用几何静态 MR（`staticMR`）折算后写入「轮上刚度」，临界阻尼因此用的是折算值。
- **STRUT / AXLE 的限位块是硬编码 ~500 000 N/m**，文件里的 `BUMP_STOP_RATE` 对这两种结构无效；导入 STRUT 时界面会提示。我们本就不做限位块受力，只存参数。
- **HUB_MASS** 是每角簧下质量（含轮辋轮胎）；STRUT 有 20% 转簧上的特殊规则（40 kg 实际需填 50），已实现。
- **ML = 4 根连杆 + 1 根拉杆（JOINT0–JOINT4）**，且**不适用于前桥**（不可转向）；静态外倾只“转动车轮”、**不移动 TYRE 点**，求解器已按此修正（连杆长度按未旋转的 TYRE 点计算）。
- `TOE_OUT` 是拉杆的横向位移长度，不是角度；导入时单轮前束仍由输入值决定。
- `PACKER_RANGE` 是到缓冲块的距离（总行程减去它就是缓冲块厚度），不是刚度。
- 手册对 ML 的评价：运动学曲线基本可用，但定位/前束偶有 bug，建议只用来导出曲线、再转成 DWB。

## 编辑模式与兼容

- 设计/实测输入：当前全部硬点定义新机构，静态外倾/前束由输入确定；可更换结构和轮端几何。
- 安装点损伤：保留基准轮端刚体和摆臂两腿长度，通过新车架点求静态变化。轮端点或结构类型变化要求切回设计模式。跨距变化为损伤等效模型，不保证原刚性部件可装配。

旧v6在表内保存派生球头坐标；导入新损伤模式时转换为基准刚体参考，避免重复变形。独立轮端编辑或解除刚性锁定的旧项目使用设计/实测模式。旧等效偏置转为轮轴输入角；旧实体垫片独立保存。

JSON v8包含 current/baseline、车型尺寸、每角参数（含慢速/快速阻尼、拐点、限位块）、模式、修正、目标和扫描范围。导入先完整校验，不合法时保持原状态；v7 项目缺少的新增字段由 `defaults()` 补齐，且缺失时快速段取慢速段数值。

## 验证

数值验证通过：整车质量/配重/簧下质量/轮上刚度推导临界阻尼；DWB/STRUT/ML 结构自动判定（含 TYPE 冲突与无法判定报错）；ML 五连杆扫掠；DWB、STRUT重合及偏置下参考点；关节/轮心/拉杆刚性距离；滑柱轴线穿过塔顶；指定轮心高度；刚体平移不变性；分数轮跳；反算；X安装点损伤；AC往返；AC 阻尼/弹簧/外倾解析；两段阻尼 F(v) 数值；自定义扫描范围。

给定STRUT示例在默认假设下：caster约7.5376°，KPI约11.5907°，轴线参考长度581.576 mm，静态MR约0.97839。±50 mm的101点可解，最大闭环残差约8.25e-10 mm。

浏览器通过：两结构混合、编辑、塔顶反算与应用、基准/撤销、按桥换结构、AC 导入（含阻尼/弹簧/外倾）、尺寸、物理修正影响前束、v8 JSON往返、无效导入保持原状态、CSV、v6兼容、分数行程、动画、390px布局，无JS异常。

## 后续边界

- 尚无 AC 的 AXLE 整体桥、拖曳臂；ML 暂不支持垫片修正 / 损伤模式 / 拉杆优化。
- 尚无车身滚转/俯仰动力学、转向机输入、轮胎力、柔顺性或结构强度。
- 尚无弹簧预载、真实行程限位与阀片曲线；目前是两段线性阻尼 + 几何行程。
- 反算与拉杆优化为有界局部搜索，不保证唯一解、全局最优或实车可实施。

## 当前状态

内核、界面及验证已完成，v9（AC 通用数据导入 + 两段阻尼 + 临界阻尼线）已发布到生产，部署编号与校验结果见 `deployment.json`。

可下载源码包：`outputs/SuspensionLab/SuspensionLab_v7_源码包.zip`（源码、构建与验证脚本、示例 JSON、交接文档）。压缩包大小与 SHA-256 记录在同目录 `SuspensionLab_v7_发布记录.json`，避免包内自引用。同一份交接文档在 `public-c6/handover.md` 提供。