Update multi-vehicle sync and crab walk docs

2026-06-29 16:00:34 +08:00
parent 8b19a15fbb
commit c093fa32e6
12 changed files with 1355 additions and 102 deletions
@@ -194,3 +194,40 @@ lock (MultiVehicleFleet)
 | 日期 | 说明 |
 |------|------|
 | 2026-06-28 | 初版：基于 Tutorial MultiWheelC 自动联动实现与联调日志分析整理 |
+| 2026-06-28 | A~H 全部修复落地（PilotDefinition.cs / ChassisController.cs / VehicleSyncModels.cs / PilotConfig.cs），见下「修复实现」 |
+| 2026-06-29 | 修正 `MultiVehicleSyncUseDetour` 语义：仅控制"车队内姿态纠正"，整车队姿态计算始终用 Detour；并修复 `FleetRotateInPlace` 欠转（航向闭环判停），见下「语义修正」 |
+
+## 修复实现（A~H）
+
+- **A**：新增 `public readonly object FleetLock`，所有对 `MultiVehicleFleet` 的读写统一 `lock(FleetLock)`（含 ChassisController 回调），不再锁会被整体替换的字段引用。
+- **B**：`MultiVehicleSendMotion` 回调写入 `MultiVehicleAutoCmdTime`；主车自动分支按 `MultiVehicleAutoCmdTimeoutMs`(0=auto) 判定命令新鲜度，超时清零速度/idealPos 并关闭 `AutoEnabled`，避免末速度滑行。
+- **C**：新增本地 `_multiVehicleFleetSeen` 存活时刻表，register/notify 收到即刷新；主车 Tick `PruneStaleFleetMembers()` 按 `MultiVehicleMemberTtlMs`(0=auto) 剔除掉线成员，`fleetReady`(数量==总数) 因此蕴含全员新鲜。
+- **D**：回调不再丢弃 `idealPos/idealAngle`，写入 `MultiVehicleAutoIdeal*` 并经 notify(`HasIdeal/IdealX/Y/Th`) 广播；自动模式下以理想车队中心作为各车 layout 前馈目标（`MultiVehicleAutoUseIdealCenter`，默认开）。
+- **E**：新增 `MultiVehicleControlRadius`(0=syncDistance/2)，`ControlPointRadius` 与 `SendMotion(localControlRadius)` 统一取该值，删除硬编码 510。
+- **F**：notify 改为 POST + JSON body（取代 GET query 串）；新增单调递增 `Seq`，从车丢弃乱序旧包（含主车重启回退识别）。
+- **G**：新增 `FleetCenterSnapshot` 不可变快照 + `volatile` 引用，`PublishFleetCenter` 整体赋值，控制器线程 `GetFleetCenterSnapshot()` 只读完整快照，消除 torn read。
+- **H**：自动模式新增 `MultiVehicleAutoRequireFleetCenter`(默认开) 门控——无有效车队中心（定位丢失）时强制停车，补上纯 SLAM 模式安全网；手动模式不受限。
+
+## 语义修正（2026-06-29）
+
+### 1. `MultiVehicleSyncUseDetour` 重新定义：仅控制"车队内姿态纠正"
+
+**问题**：原实现把"是否读 Detour 全局位姿"与"是否做车队内姿态纠正"绑在同一开关上。`false` 时 `posAvailable` 直接为假、根本不读 SLAM，导致 `TryInferFleetCenter` 失败、整车队姿态无法计算——这与该开关应有的含义不符。
+
+**修正**（`PilotDefinition.TickMultiVehicle`）：将单一 `posAvailable` 拆为三个语义清晰的量：
+
+| 变量 | 含义 | 取值 |
+|------|------|------|
+| `useDetourCorrection` | 是否做**车队内姿态纠正**（`PosBias*` 逐车 SLAM 补偿） | `= MultiVehicleSyncUseDetour` |
+| `slamRead` | 本车本轮是否读取 Detour 全局位姿 | `useDetourCorrection \|\| (isMaster && autoMode)` |
+| `fleetPosValid` | 整车队全局姿态是否已知（主车=自身读到，从车=主车广播） | 见代码 |
+
+- **整车队姿态计算**（反推/广播车队中心、SLAM 间距、自动安全门 H、自动入口门）一律改用 `slamRead`/`fleetPosValid`，**始终依赖 Detour**，不再受开关限制；自动入口门与 H 门去掉 `&& MultiVehicleSyncUseDetour` 条件。
+- **车队内姿态纠正**（`PosBias*` 补偿块）是唯一受 `useDetourCorrection` 控制的开关点。
+- 即 `false` 时：自动模式主车仍 `getCartLocation()` 计算整车队姿态（无定位则阻塞停车），但不再逐车 SLAM 纠偏。
+
+### 2. `FleetRotateInPlace` 欠转修复（航向闭环判停）
+
+**问题**：原地旋转 MovementDefinition 的判停沿用 `MultiVehicleSyncUseDetour`，关闭时退化为"按估算时长开环停止"，实际转速 < 指令时（PI 纠偏吃速率 + 起步斜坡）会**没转到目标就停**（实测 180° 欠转）。
+
+**修正**（`MovementTests.FleetRotateInPlace`）：新增 `FleetRotateUseDetourHeading`(默认 `true`)，**与 `MultiVehicleSyncUseDetour` 解耦**——转到指定角度属于"整车队姿态计算"，故默认读主车 SLAM 航向闭环累计实际转角，到 `|TargetDeltaDeg|` 才停。新增 `FleetRotateDbg` 落盘日志（实际航向/累计转角/实际vs指令角速率/判停原因）便于复现核对。