From b4c5d65730ff0348463c5a4d039d1cd8f4725e75 Mon Sep 17 00:00:00 2001 From: ykcheungab Date: Sun, 18 Oct 2026 18:15:56 +0800 Subject: [PATCH] =?UTF-8?q?=E6=A0=A1=E9=AA=8C=20Autocal=20=E8=BF=90?= =?UTF-8?q?=E5=8A=A8=E5=BD=93=E9=87=8F=E5=B9=B6=E6=8B=92=E7=BB=9D=E5=A4=B1?= =?UTF-8?q?=E9=85=8D=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 保留已确认配置下的轴号、目标数值和发送顺序，拒绝不匹配的单位或过期计划。136 项相关检查通过，8256 条运动调用与修改前一致；全套既有失败见运动单位契约。 --- apps/autocal/docs/motion-unit-contract.zh.md | 36 ++++ apps/autocal/tests/test_motion_unit_guards.py | 187 ++++++++++++++++++ 2 files changed, 223 insertions(+) create mode 100644 apps/autocal/docs/motion-unit-contract.zh.md create mode 100644 apps/autocal/tests/test_motion_unit_guards.py diff --git a/apps/autocal/docs/motion-unit-contract.zh.md b/apps/autocal/docs/motion-unit-contract.zh.md new file mode 100644 index 0000000..7d4039c --- /dev/null +++ b/apps/autocal/docs/motion-unit-contract.zh.md @@ -0,0 +1,36 @@ +# 运动单位校验与现有输出保持 + +用途：当前实现契约。范围：架构审查两项 P1 的保守修复。旋转标定比例、X 经验校正、坐标轴方向、姿态算法、UV 映射和原有运动目标保持原值；三项 P2 按用户要求暂缓。 + +## 配置、读回与执行 + +[`units.py`](../src/orisys_autocal/motion/units.py) 拥有物理单位换算。线性换算使用已有 `PULSES_PER_MM` 与每轴预期 `UNITS`；旋转保持轴 2 的 12500、轴 3 的 29500 用户单位/90°，并显式绑定测量时 `ROTARY_CALIBRATION_UNITS=10`。改变旋转轴当量后没有新标定，则角度换算返回 NaN，姿态移动被拒绝，不按推算的新比例驱动机器。 + +[`MotionService`](../src/orisys_autocal/motion/service.py) 的 `_params` 表示操作者配置的预期参数，`_last_axes` 表示控制器最近成功轮询的实际状态。二者不是可以互相覆盖的默认值。物理单位移动要求预期与读回当量为有限正数且一致；相对容差为 `1e-7`。没有读回、读取失败或不一致时明确拒绝。`to_mm/to_deg` 在这些条件不满足时返回 NaN，避免用错误比例判定到位。 + +修改轴参数时立即使旧读回失效，即使参数写入只完成一部分后失败，也不能沿用旧状态。下一次成功轮询恢复观测；程序不自动把实际值当成新标定，也不自动改写操作者配置。 + +[`PoseMover`](../src/orisys_autocal/motion/pose_move.py) 启动前检查计划中的轴编号、物理目标和已换算的用户单位目标仍对应当前配置。工作线程执行前再次读各目标轴的 `UNITS`，全部校验完成后才按原顺序发送原绝对目标。配置或角色映射在排队期间改变时，旧计划被拒绝，要求重新规划；不会偷偷套用新设置。 + +移动器按命令 token 接收工作线程的拒绝或失败，立即标记该次移动失败，不再靠后续位置恰好相同判定到位。其他命令的结果不会取消当前计划；界面继续使用已有的移动失败处理和停止路径。 + +执行前增加的是只读参数检查，可能增加通信延迟，不保证与旧版完全相同的发送时刻。控制器被其他软件在最终读取和运动指令之间改动的并发窗口，本次也不能消除；操作期间仍需保证设备配置的单一写入者。 + +## 输出保持边界 + +| 已确认配置下保持的行为 | 新增的拒绝条件 | +|---|---| +| 原来的驱动轴编号、绝对目标和发送顺序 | 实际当量与预期不一致或无法读取 | +| 原有速度、加速度、对位与归零目标 | 旋转当量偏离已有标定条件 | +| X 的 `-10/11` 校正与 yaw/pitch 符号 | 排队后的轴映射或数值换算与原计划不符 | +| 原始用户单位的手动调试、jog、stop 与 home 接口 | 未对这些原始单位接口扩展物理单位保护 | + +常驻读数和轴调试页的旋转轴毫米显示属于 P2，本次不修改。姿态实际角度显示会显式携带读回当量，未校准时不显示成有效角度。连续参考力录制及接入恒力执行器也不属于本次修复。 + +## 验证与限制 + +回归测试见 [`test_motion_unit_guards.py`](../tests/test_motion_unit_guards.py)。它覆盖既有五轴命令的确定数值和顺序、配置一致的线性换算、异常读回、旋转标定条件、排队期间配置改变、读取失败时整组零发送，以及原始单位调试移动的兼容性。现有测试夹具补充了真实流程所需的单位观测，没有降低断言或放宽限位。 + +修改前从本地 design 导出保存 1032 顶点，使用默认安装与当前偏好配置，共 2064 组姿态和规划目标。修改后逐元素严格相等，最大差值为 0；使用修改前源码与当前源码在记录型 DemoTransport 上分别执行相同计划，产生的 8256 条绝对运动调用也完全一致。这验证软件输出保持，不构成实机轨迹或物理接触精度证明。 + +最终相关检查 136 项通过；Autocal 全套为 720 项通过、3 项失败，无跳过。两项模拟采集失败及一项旧 scratch 路径假设与原始审查记录一致，本轮没有修复。回归测试在修复前复现单位风险，移除当量一致性判断的内存变异也被检出。详细结果见[架构审查](../../../../docs/platform/autocal-architecture-review.zh.md)。证据位于 app `.scratch/autocal-unit-guards/`，不属于长期归档。 diff --git a/apps/autocal/tests/test_motion_unit_guards.py b/apps/autocal/tests/test_motion_unit_guards.py new file mode 100644 index 0000000..3c95778 --- /dev/null +++ b/apps/autocal/tests/test_motion_unit_guards.py @@ -0,0 +1,187 @@ +"""Keep commissioned command numbers; reject unverified physical-unit moves.""" + +from dataclasses import replace +import math + +import pytest + +from orisys_autocal.motion.models import AxisParams, BusStatus, ConnectionSpec +from orisys_autocal.motion.pose_move import PoseMover, plan_pose_move +from orisys_autocal.motion.service import MotionService +from orisys_autocal.motion.transport import DemoTransport +from orisys_autocal.motion.units import deg_to_user_units, user_units_to_deg +from orisys_app_shared.zmotion import ZAuxError + + +class RecordingTransport(DemoTransport): + def __init__(self): + super().__init__() + self.moves = [] + + def move_abs(self, axis, value): + self.moves.append((axis, value)) + return super().move_abs(axis, value) + + +def service(): + transport = RecordingTransport() + instance = MotionService( + transport, + language="en_US", + limits={"max_travel_mm": 100.0, "max_yaw_deg": 180.0, "max_pitch_deg": 90.0}, + ) + instance.connect(ConnectionSpec(mode="demo")) + instance.poll() + instance._bus = BusStatus(init_status=1, total_axes=5) + return instance, transport + + +def mover_and_actions(instance, targets): + actions = [] + + def submit(action): + actions.append(action) + return len(actions) + + mover = PoseMover(instance, submit) + plan = plan_pose_move(instance, targets, together=True) + assert mover.start(plan).ok + return mover, actions + + +def test_commissioned_command_numbers_and_order_remain_exact(qt_app): + instance, transport = service() + mover, actions = mover_and_actions( + instance, {"x": -10.0, "y": 2.0, "yaw": 90.0, "pitch": -45.0, "z": 3.0} + ) + assert actions[0](instance).ok + assert transport.moves == [ + (2, 12500.0), + (3, -14750.0), + (0, -5000.0), + (1, 1000.0), + (4, 1500.0), + ] + + +def test_readback_mismatch_refuses_instead_of_changing_the_command(): + instance, transport = service() + transport.set_units(0, 5.0) + instance.poll([0]) + instance._bus = BusStatus(init_status=1, total_axes=5) + refusal = instance.check_axes_move({"x": 2.0}) + assert refusal is not None and "UNITS" in refusal.message + assert math.isnan(instance.to_mm(0, 1000.0)) + assert transport.moves == [] + + +def test_explicit_matching_linear_units_are_supported_without_rescaling_other_axes(): + instance, transport = service() + assert instance.set_axis_params(0, AxisParams(units=5.0)).ok + instance.poll([0]) + instance._bus = BusStatus(init_status=1, total_axes=5) + assert instance.check_axes_move({"x": 2.0}) is None + assert instance.to_units("x", 2.0) == 2000.0 + assert instance.to_mm(0, 1000.0) == 1.0 + assert instance.to_units("yaw", 90.0) == 12500.0 + + +@pytest.mark.parametrize("units", [0.0, -1.0, math.nan, math.inf]) +def test_invalid_unit_readback_is_not_a_physical_measurement(units): + instance, transport = service() + transport.set_units(0, units) + instance.poll([0]) + instance._bus = BusStatus(init_status=1, total_axes=5) + assert instance.check_axes_move({"x": 2.0}) is not None + assert math.isnan(instance.to_mm(0, 1000.0)) + + +def test_missing_or_failed_readback_cannot_reuse_the_last_good_scale(): + instance, transport = service() + instance._last_axes.clear() + assert instance.check_axes_move({"x": 2.0}) is not None + instance.poll([0]) + instance._last_axes[0] = replace(instance._last_axes[0], read_ok=False) + assert instance.check_axes_move({"x": 2.0}) is not None + assert math.isnan(instance.to_mm(0, 1000.0)) + + +@pytest.mark.parametrize("axis,role", [(2, "yaw"), (3, "pitch")]) +def test_changed_rotary_pulse_equivalent_requires_new_calibration(axis, role): + instance, transport = service() + assert instance.set_axis_params(axis, AxisParams(units=5.0)).ok + instance.poll([axis]) + instance._bus = BusStatus(init_status=1, total_axes=5) + refusal = instance.check_axes_move({role: 45.0}) + assert refusal is not None and "calibrat" in refusal.message + assert math.isnan(instance.to_units(role, 45.0)) + assert math.isnan(instance.to_deg(axis, 1000.0)) + assert math.isnan(user_units_to_deg(axis, 1000.0, units=5.0)) + assert math.isnan(deg_to_user_units(axis, 45.0, units=5.0)) + + +def test_change_after_queueing_is_refused_before_any_axis_moves(qt_app): + instance, transport = service() + mover, actions = mover_and_actions(instance, {"x": 2.0, "yaw": 10.0}) + # No poll between the external parameter change and worker execution. + transport.set_units(0, 5.0) + result = actions[0](instance) + assert not result.ok + mover.on_command_finished(1, result) + assert not mover.running and "UNITS" in mover.state.failure + assert transport.moves == [] + + +def test_unrelated_command_result_does_not_cancel_a_pose_move(qt_app): + from orisys_autocal.motion.models import MotionResult + + instance, transport = service() + mover, actions = mover_and_actions(instance, {"x": 2.0}) + mover.on_command_finished(99, MotionResult.refused("another command")) + assert mover.running + assert actions[0](instance).ok + mover.on_command_failed(1, "read failed") + assert not mover.running and mover.state.failure == "read failed" + + +@pytest.mark.parametrize("change", ["parameters", "mapping"]) +def test_a_queued_plan_cannot_be_reinterpreted_under_new_settings(qt_app, change): + instance, transport = service() + mover, actions = mover_and_actions(instance, {"x": 2.0, "y": 1.0}) + if change == "parameters": + instance.set_axis_params(0, AxisParams(units=5.0)) + else: + instance.set_axis_roles({"x": 1, "y": 0, "yaw": 2, "pitch": 3, "z": 4}) + assert not actions[0](instance).ok + assert transport.moves == [] + + +def test_a_stale_plan_is_refused_before_it_is_queued(qt_app): + instance, transport = service() + plan = plan_pose_move(instance, {"x": 2.0}, together=True) + instance.set_axis_params(0, AxisParams(units=5.0)) + instance.poll([0]) + instance._bus = BusStatus(init_status=1, total_axes=5) + actions = [] + mover = PoseMover(instance, lambda action: actions.append(action)) + assert not mover.start(plan).ok + assert actions == [] and transport.moves == [] + + +def test_unit_read_error_before_execution_refuses_the_entire_group(qt_app): + instance, transport = service() + mover, actions = mover_and_actions(instance, {"x": 2.0, "yaw": 10.0}) + + def unreadable(axis): + raise ZAuxError(30500, "unit read failed") + + transport.get_units = unreadable + assert not actions[0](instance).ok + assert transport.moves == [] + + +def test_raw_debug_moves_keep_the_existing_user_unit_contract(): + instance, transport = service() + transport.set_units(2, 5.0) + assert instance.move_abs(2, 90.0).ok + assert transport.moves == [(2, 90.0)]