✨ feat(compat): 补齐飞拍执行等待与 FANUC 状态驱动链路

- 为 ExecuteFlyShotTraj 补齐 wait 语义，并让 move_to_start
  先完成临时 PTP 运动后再启动正式飞拍轨迹
- 将 J519 命令发送改为由机器人 UDP status sequence 驱动，
  避免在未收到状态包时主动发周期命令
- 将 10010 状态通道关节字段统一按 JointRadians 命名，
  同步更新运行时读取逻辑与协议测试
- 新增 FANUC 10010 状态帧、流运动手册和 Python client
  逆向文档，并更新 README 与兼容需求说明
- 补充兼容层编排测试与 HTTP 集成测试，覆盖 wait 和
  move_to_start 串行化行为

docs/fanuc-field-runtime-workflow.md

@@ -23,7 +23,7 @@ POST /init_mpc_robt
 2. `SetUpRobot(robot_name)`：加载机器人配置、关节限制和伺服周期。
 3. `SetActiveController(sim)`：选择仿真或 FANUC 真机运行时。
 4. `Connect(robot_ip)`：真机模式下依次建立 `TCP 10010` 状态通道、`TCP 10012` 命令通道、`UDP 60015` J519 运动通道。
-5. `EnableRobot(2)`：真机模式下执行 `StopProg("RVBUSTSM") -> Reset -> GetProgStatus("RVBUSTSM") -> StartProg("RVBUSTSM")`，随后启动 J519 8ms 周期发送器。
+5. `EnableRobot(2)`：真机模式下执行 `StopProg("RVBUSTSM") -> Reset -> GetProgStatus("RVBUSTSM") -> StartProg("RVBUSTSM")`，随后允许 J519 在收到机器人 UDP status 包后回发下一帧命令。
 
 也可以使用拆分端点按同样顺序调用：
 
@@ -37,6 +37,15 @@ GET  /enable_robot/?buffer_size=2
 
 ## 2. 参数设置
 
+规划约束参数：
+
+当前现场抓包已经确认，`50001/TCP+JSON` 的 `ExecuteFlyShotTraj(save_traj=true,use_cache=false)` 请求不会显式携带 `JointLimits / acc_limit / jerk_limit / velocity / acceleration / jerk`。因此新系统把规划约束分成两层处理：
+
+1. 旧 `RobotConfig.json` 中已有的 `acc_limit / jerk_limit` 继续作为模型加载时的基础倍率。
+2. 若旧系统导出的 `JointTraj.txt` 明显比当前 C# 规划更慢，使用 replacement-only 的内部校准参数限制规划阶段加速度，设计字段为 `planning_acceleration_scale`。
+
+`planning_acceleration_scale` 只影响 `JointTraj.txt` 这类规划结果时间轴，不下发到 FANUC 控制柜，也不改变 J519 发送周期。若需要临时整体验证，也可以使用当前已有的 `planning_speed_scale`，但它是新系统兼容开关，不是旧抓包中出现的字段。
+
 速度倍率：
 
 ```bash
@@ -44,7 +53,7 @@ POST /set_speedRatio/
 { "speed": 0.7 }
 ```
 
-真机模式下会通过 `TCP 10012` 下发 `0x2207 SetSpeedRatio`，同时运行时保存当前倍率。J519 执行时仍必须按该倍率重采样轨迹时间轴：
+真机模式下会通过 `TCP 10012` 下发 `0x2207 SetSpeedRatio`，同时运行时保存当前倍率。`speed_ratio` 是执行期倍率，不参与 `IsFlyShotTrajValid` / `SaveTrajInfo` / `ExecuteFlyShotTraj(save_traj=true)` 的规划时长计算。J519 执行时仍必须按该倍率重采样轨迹时间轴：
 
 ```text
 t_traj = k * 0.008 * speed_ratio
@@ -121,18 +130,21 @@ POST /execute_flyshot/
   "move_to_start": true,
   "method": "self-adapt-icsp",
   "save_traj": false,
-  "use_cache": true
+  "use_cache": true,
+  "wait": true
 }
 ```
 
 执行链路：
 
 1. 从上传缓存读取 waypoint、shot flag、offset、IO 地址组。
-2. 使用 `icsp` 或 `self-adapt-icsp` 规划关节轨迹。
+2. 使用 `icsp` 或 `self-adapt-icsp` 规划关节轨迹；规划阶段先应用 `acc_limit / jerk_limit`，再应用 replacement-only 的规划加速度校准参数。
 3. 生成 `TrajectoryDoEvent`，把拍照触发绑定到轨迹时间。
-4. 真机模式下把规划输出的 `rad` 稠密轨迹按 J519 周期重采样并转成 `deg`。
-5. 启动前若已有 J519 响应且 `accept_cmd` 或 `sysrdy` 未就绪，则拒绝执行。
-6. 周期命令中嵌入 IO 脉冲；当前 UTTC 抓包确认 mask 集合为 `10/12/14`，共 17 个 set 脉冲和 17 个 clear 帧。
+4. 若 `move_to_start=true`，先从运行时当前关节位置生成临时 PTP 稠密轨迹移动到规划轨迹起点，并等待运行时 `IsInMotion=false` 后再启动飞拍轨迹，避免第一帧 J519 目标从当前位置跳到起点。
+5. 真机模式下把规划输出的 `rad` 稠密轨迹按 J519 轨迹时间步长重采样并转成 `deg`，命令实际发包由机器人 UDP status 包驱动。
+6. 若 `wait=true`，正式飞拍轨迹启动后继续等待运行时 `IsInMotion=false`，机器人执行完整条飞拍轨迹后 HTTP 才返回；`wait=false` 时启动后立即返回。
+7. 启动前若已有 J519 响应且 `accept_cmd` 或 `sysrdy` 未就绪，则拒绝执行。
+8. 周期命令中嵌入 IO 脉冲；当前 UTTC 抓包确认 mask 集合为 `10/12/14`，共 17 个 set 脉冲和 17 个 clear 帧。
 
 `method="doubles"` 当前明确返回未实现；现场主链路使用 `icsp` / `self-adapt-icsp`。
 
@@ -146,8 +158,8 @@ POST /disconnect_robot/
 
 真机模式下：
 
-- `StopMove()` 取消当前稠密轨迹生成任务并停止 J519 发送循环。
-- `DisableRobot()` 发送 J519 end 控制包，然后 `StopProg("RVBUSTSM")`。
+- `StopMove()` 取消当前稠密轨迹生成任务并停止 J519 状态包驱动发送。
+- `DisableRobot()` 发送 J519 packet type 2 状态输出停止包，然后 `StopProg("RVBUSTSM")`。
 - `Disconnect()` 关闭状态、命令和 J519 三条通道，并清理本地运行状态。
 
 ## 6. 现场抓包覆盖
@@ -162,8 +174,8 @@ POST /disconnect_robot/
 
 测试同时检查：
 
-- 主运行窗口命令序号连续，无重复 seq。
+- 主运行窗口命令序号连续，无重复 seq；J519 客户端单元测试覆盖按最新 status sequence 回发命令。
 - 响应 `status=15` 段覆盖主运行窗口，响应相对命令滞后 2 到 8 帧。
 - 实发点位相对重采样期望的全局 RMS 小于 `0.012deg`，最大绝对误差小于 `0.07deg`。
-- `lastData=0`，结束运动依赖 J519 end 控制包。
+- `lastData=0`，结束运动当前依赖 J519 packet type 2 状态输出停止包；`../j519 协议.pcap` 中另有 1 个 `LastData=1` 后紧跟 type 2 的样本，停止语义后续单独验证。
 - IO 脉冲数量和 mask 集合 `10/12/14` 与抓包一致。