linuxcncWebWASM/docs/linuxcnc-axis-web-iron-law.md

LinuxCNC AXIS Web 铁律

本仓库的 Web 控制面板必须对标 linuxcnc/src/emc/usr_intf/axis/scripts/axis.py 的 AXIS 行为。LinuxCNC AXIS 源码和 LinuxCNC WASM 是操作语义、门控、状态、错误和运动结果的唯一权威；React、浏览器事件和 Three.js 只能负责输入、异步传输、状态投影和显示。

强制映射

Web 操作	AXIS 源入口	WASM 命令/状态	Web 规则
急停/解除急停	commands.estop、General_Halt	ESTOP、IO estop	立即停机；解除后仍须按 LinuxCNC 的恢复/上电顺序
上电/断电/重置	commands.power、commands.reset	POWER、RESET、IO ready/task state	仅按 WASM gate 启用；断电保留程序但中止运动
HOME ALL/单轴回零	home_all_joints、home_joint	HOME、wasm_home_limit	只能在 manual_ok() 等价条件满足时执行
手动/JOG	ensure_mode(MODE_MANUAL)、jog_on/jog_off	SET_MODE、JOG_START/JOG_STOP、WASM TP tick	按住开始、释放停止；五个轴都必须使用同一 WASM 运动源
MDI	ensure_mode(MODE_MDI)、send_mdi_command	SET_MODE、MDI_EXECUTE	解释器运行时拒绝；队列和错误由 WASM 返回
运行/暂停/恢复/停止	task_run、task_pause、task_resume、task_stop	PROGRAM_RUN/PAUSE/RESUME/ABORT	运行期间不切手动/MDI；暂停保留 TP 队列，恢复继续同一队列
单步/重启/重新加载	task_step、reload_file、open_file_guts	PROGRAM_STEP/RESTART/LOAD_WORKSPACE/PROGRAM_LOAD	清理旧预览和执行轨迹，再显示新 WASM 结果
主轴/冷却/刀具/探针	spindle_*、mist_toggle、flood_toggle、change_tool、probe	SPINDLE_*、COOLANT_COMMAND、TOOL_*、PROBE_CONFIG	HAL/IO/设备状态由 WASM canonical snapshot 回显
进给/主轴/最大速度覆盖	set_feedrate、set_spindlerate、tpSetVlimit	SET_OVERRIDE、SET_SPINDLE_OVERRIDE、SET_MAX_VELOCITY	只发送目标值；显示值必须来自 WASM snapshot
预览/清图/视图	glcanon/clear_live_plot	PROGRAM_LOAD 生成的 canonical toolpath、VISUAL_CLEAR	视图变换是显示操作，不能重算 G-code 或运动

门控铁律

网页必须实现 AXIS manual_ok() 的等价行为：task 必须 STATE_ON，不能处于 AUTO/MDI 的非空闲解释器状态；MDI 还必须受 queued-MDI 上限限制。按钮的 disabled 属性只能投影 WASM snapshot 的 gate，不能在 React 中复制另一套 task/motion/kinematics 判断。WASM 拒绝的命令必须保留错误码、gate_reason 和 operation trace。

禁止事项

• 禁止 React/JavaScript 解析 G-code、规划轨迹、计算 RTCP/FK/IK、推进运动或伪造轴值。
• 禁止用本地按钮状态覆盖 WASM 的 task、IO、HAL、tool、probe、home/limit 或 planner 状态。
• 禁止把按钮“可点击”、静态截图或单次页面加载当作实现证据；必须有 worker/WASM command result 和后续 snapshot。
• 不具备对应 LinuxCNC/WASM ABI 的功能必须保持禁用，并明确记录 blocked_by_abi，不得用 JS 模拟补齐。
• 页面临时上下文和断电 checkpoint 可以使用 Worker-only OPFS 临时 JSON 保存，但 OPFS 只负责持久化，不得成为 CNC 业务 authority；恢复时必须重新交给 LinuxCNC WASM 校验和执行。
• React 不得直接访问 OPFS、localStorage 或 WASM 指针；所有页面缓存读写必须通过 Worker 消息完成，并带 schema、context、generation 和 hash。

验收证据

每次面板变更必须运行：

node --experimental-strip-types web/worker/test_xyzac_button_constraints.mjs
node --experimental-strip-types web/worker/test_xyzac_panel_buttons.mjs
npm run typecheck --prefix web/react
npm run build --prefix web/react
PLAYWRIGHT_MODULE=... node scripts/test_xyzac_panel_buttons_browser.mjs

浏览器审计必须覆盖真实发布站点的启动、打开文件、加载程序、上电、回零、重置、三种运动学、视图、清图、XYZAC JOG、主轴、冷却、刀具/探针、覆盖率、MDI、运行、暂停、恢复、停止、启动序列、编辑器加载和重新打开。结果应记录在 doc-rtcp/xyzac-panel-button-parity-test-report.md，并保持 STOP_RELEASE，直到更高层的完整 TP 数值 oracle 也通过。