# 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。

## 验收证据

每次面板变更必须运行：

```text
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 也通过。