# 2026-07-07 AXIS 按钮 LinuxCNC 真实 C++ 对标验收测试

## 1. 验收原则

本文件由 `19-20260707-AXIS按钮LinuxCNC-task-motion状态机制源码分析.md` 拆分而来，定义“急停、上电、Home、执行、暂停、单步执行”的真实验收标准。

验收原则：

- `compare 60/60 pass` 不是最终验收结论，只是旧 compare 摘要。
- 验收必须证明 Web 行为符合 LinuxCNC C++ task/motion/homing 真实实现。
- 每个按钮必须同时验收 UI gate、runtime gate、状态记录、非法命令拒绝、真实程序执行影响。
- 如果表面 compare 通过，但 C++ 状态机硬规则失败，结论必须是失败。

最终验收结论字段建议：

```json
{
  "surfaceSummary": {
    "legacyComparePassCount": 60,
    "legacyCompareFailCount": 0
  },
  "functionalSummary": {
    "status": "pass",
    "failCount": 0,
    "requiredImprovements": []
  }
}
```

只有 `functionalSummary.status == "pass"` 才允许写“真实通过”。

## 2. 验收准备

### 2.1 Native LinuxCNC 准备

命令：

```bash
/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment \
  python3 /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/tools/collect-native-xyzbc-trt-evidence.py \
  --run --timeout 90
```

必须采集：

- `task.state`
- `task.mode`
- `task.interpState`
- `task.execState`
- `task.task_paused`
- `task.currentLine`
- `task.readLine`
- `task.motionLine`
- `motion.traj.enabled`
- `motion.traj.paused`
- `motion.traj.single_stepping`
- `motion.traj.queue`
- `motion.joint[].homing`
- `motion.joint[].homed`
- active G-code line、motion id、axis pose、tcp pose、tool axis

### 2.2 Web 准备

命令：

```bash
npm --prefix /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/app run smoke:node
npm --prefix /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/app run smoke:browser
npm --prefix /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:web
```

必须采集与 native 同名字段，并额外采集：

- UI button enabled/disabled
- operator message
- runtime command accepted/rejected
- `machine.*` 状态快照
- Task/HAL status 快照

### 2.3 Compare 准备

命令：

```bash
npm --prefix /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:compare
```

compare 必须输出：

- 旧摘要 `surfaceSummary`
- 新硬规则 `functionalSummary`
- 每个 C++ 对标规则的 pass/fail 原因

## 3. 基础状态枚举验收

### T-STATE-001 task state 枚举一致

步骤：

1. 启动 Web runtime。
2. 依次发 `ESTOP`、`ESTOP_RESET`、`ON`、`OFF`。
3. 对照 LinuxCNC `EMC_TASK_STATE`。

期望：

- `ESTOP -> estop`
- `ESTOP_RESET -> estop-reset`
- `ON -> on`
- `OFF -> estop-reset/off 语义`，Web 显示必须与项目约定一致，但不能伪装为 on。

失败条件：

- Web 只用 `powerOn` 推导 state。
- runtime status 与 UI 状态不一致。

### T-STATE-002 task mode 枚举一致

步骤：

1. 在 machine on 状态依次切 `manual`、`auto`、`mdi`。
2. 在 `auto + reading` 时尝试切出 auto。

期望：

- 正常 idle 下切换成功。
- `auto + reading` 切出 auto 必须被拒绝，或按 LinuxCNC abort/close/synch 语义处理并记录。

失败条件：

- 解释器运行中静默切到 manual/mdi。

### T-STATE-003 interp/exec 状态一致

步骤：

1. Run 前检查 `interpState=idle`、`execState=done`。
2. Run 中检查 `interpState=reading/waiting`，`execState` 可进入 waiting 状态。
3. 完成后检查 `interpState=idle`、`execState=done`。

失败条件：

- 只记录 `runState`，没有 `interpState/execState`。

## 4. 急停验收

### T-ESTOP-001 ESTOP 可在任意状态触发

步骤：

1. machine on。
2. Home All。
3. Run 真实程序。
4. 在执行中发 ESTOP。

期望：

- runtime 接受 `EMC_TASK_SET_STATE ESTOP`。
- `taskState=estop`。
- `motionEnabled=false`。
- `interpState=idle`。
- `taskPaused=false`、`motionPaused=false`。
- `singleStepping=false`、`motionStepping=false`。
- feed velocity 为 0。
- spindle/coolant 关闭。

失败条件：

- ESTOP 后仍显示 running/paused/stepping。
- 位置继续推进。
- 只改 UI，不改 runtime status。

### T-ESTOP-002 ESTOP_RESET 只解除急停但不上电

步骤：

1. 进入 ESTOP。
2. 发 RESET/ESTOP_RESET。

期望：

- `taskState=estop-reset`。
- `powerOn=false`。
- `motionEnabled=false`。
- `interpState=idle`。

失败条件：

- RESET 后直接上电。

## 5. 上电/下电验收

### T-POWER-001 ESTOP 下 Power 被拒绝

步骤：

1. 设置 `taskState=estop`。
2. 点击/发送 Power。

期望：

- UI 禁用或 operator message 提示先解除急停。
- runtime 不接受 `ON`。
- 状态保持 estop。

失败条件：

- ESTOP 下进入 on。

### T-POWER-002 ESTOP_RESET 下 Power On

步骤：

1. RESET 到 `estop-reset`。
2. 点击 Power。

期望：

- 发送 `EMC_TASK_SET_STATE ON`。
- `motionEnabled=true`。
- 最终 `taskState=on`。

失败条件：

- 只设置 `powerOn=true`，runtime status 未 on。

### T-POWER-003 ON 下 Power Off

步骤：

1. machine on。
2. Home All。
3. Run 或进入 idle。
4. 点击 Power Off。

期望：

- 发送 `EMC_TASK_SET_STATE OFF`。
- abort/disable。
- `motionEnabled=false`。
- `interpState=idle`。
- pause/step 状态清理。

失败条件：

- 下电后保留 running/paused/stepping。

## 6. Home 验收

### T-HOME-001 未上电 Home 被拒绝

步骤：

1. taskState=estop-reset。
2. 发 `EMC_JOINT_HOME -1` 或点击 Home All。

期望：

- runtime 拒绝。
- operator message 指出 machine must be on。
- `homed[]` 不变化。

### T-HOME-002 MANUAL/ON/IDLE Home All

步骤：

1. RESET。
2. Power On。
3. 切 Manual。
4. 发 Home All。

期望：

- 出现 `homing=true` 瞬态。
- 完成后 `homing=false`。
- `homed[]` 全 true。
- `allHomed=true`。
- `homeState=homed` 或等价状态。

失败条件：

- 没有 homing 状态事件。
- 只设置 `allHomed=true`，没有 per-joint `homed[]`。

### T-HOME-003 Homing 中禁止重复 Home/Run/Step/Jog

步骤：

1. 启动 Home All。
2. 在 homing 仍 active 时发 Home、Run、Step、Jog。

期望：

- 全部拒绝。
- 原 homing 流程不被破坏。

失败条件：

- homing 中允许 Run 或 Step。

## 7. Run 验收

### T-RUN-001 未 Home Run 被拒绝

步骤：

1. machine on。
2. mode=auto。
3. 保持 `allHomed=false`。
4. 发 `EMC_TASK_PLAN_RUN`。

期望：

- runtime 拒绝。
- 错误等价于 LinuxCNC `Can't run a program when not homed`。
- `interpState` 保持 idle。

失败条件：

- 只因 UI 禁用，但 runtime 可直接 Run。

### T-RUN-002 合法 Run 真实程序

步骤：

1. RESET。
2. Power On。
3. Home All。
4. 加载真实 G-code。
5. mode=auto。
6. Run。

期望：

- `interpState=reading/waiting`。
- `taskPaused=false`。
- `singleStepping=false`。
- `currentLine/readLine/motionLine` 随执行推进。
- axis pose、tcp pose、tool axis 随真实程序变化。
- 完成后 `interpState=idle`。

失败条件：

- 只播放前端路径，不产生 task/motion 状态流。
- line/motion id 不推进。

### T-RUN-003 非 idle Run 被拒绝

步骤：

1. 合法 Run。
2. 在 reading 或 paused 状态再次发 Run。

期望：

- reading 时拒绝。
- paused 时应提示 resume，而不是重新 Run。

失败条件：

- 运行中重入 Run。

## 8. Pause/Resume 验收

### T-PAUSE-001 AUTO/READING Pause

步骤：

1. 合法 Run。
2. 等待进入 reading。
3. 发 Pause。
4. 连续采样至少 5 帧，每帧间隔 50ms。

期望：

- `interpState=paused`。
- `interpResumeState=reading` 或 waiting。
- `taskPaused=true`。
- `motionPaused=true`。
- feed velocity 为 0。
- activeLine、axis pose、tcp pose、tool axis 在暂停采样中冻结。

失败条件：

- 状态 paused 但位置继续变化。
- 只冻结 UI，不冻结 runtime feedback。

### T-PAUSE-002 Resume 恢复 interpResumeState

步骤：

1. 在 T-PAUSE-001 暂停状态发 Resume。

期望：

- `interpState` 恢复到 `interpResumeState`。
- `taskPaused=false`。
- `motionPaused=false`。
- `singleStepping=false`。
- 执行继续推进。

失败条件：

- Resume 固定写 reading，丢失 waiting/mdi 语义。

### T-PAUSE-003 非运行 Pause 被拒绝

步骤：

1. idle 状态发菜单 Pause。

期望：

- 拒绝或忽略。
- 状态保持 idle。

失败条件：

- idle 下进入 paused。

## 9. Step 验收

### T-STEP-001 IDLE Step 等价 Run 后 Pause

步骤：

1. RESET。
2. Power On。
3. Home All。
4. 加载真实程序。
5. mode=auto。
6. 在 idle 发 Step。

期望：

- 启动 program run。
- 随后进入 paused。
- `taskPaused=true`。
- `motionPaused=true`。
- `singleStepping=true` 或 evidence 中记录 single stepping 事件。
- active line/motion id 到第一步后停止。

失败条件：

- Step 只是前端 sample+1，没有 task/motion 状态。

### T-STEP-002 PAUSED Step 放行到下一个 motion id

步骤：

1. 执行 T-STEP-001 或 Run 后 Pause。
2. 记录当前 `motionId/currentLine`。
3. 发 Step。
4. 等待下一次 paused。

期望：

- motion id 或 currentLine 前进到下一段。
- 再次 `motionPaused=true`。
- `motionStepping` 事件出现后清理。
- 不是按固定采样点数量推进。

失败条件：

- Step 后没有 line/motion id 变化。
- Step 后持续 running 不再暂停。

### T-STEP-003 Resume/Abort/ESTOP/OFF 清 Step

步骤：

1. 进入 stepping/paused。
2. 分别执行 Resume、Abort、ESTOP、OFF。

期望：

- `singleStepping=false`。
- `motionStepping=false`。
- 不残留 step lock。

失败条件：

- 后续 Run 被旧 step 状态影响。

## 10. 非法命令矩阵验收

必须在无 UI runtime 层执行：

| 状态 | 命令 | 期望 |
|---|---|---|
| estop | ON | 拒绝，必须先 estop reset |
| estop-reset | RUN | 拒绝，machine must be on |
| on/manual/idle/unhomed | RUN | 拒绝，home first |
| on/auto/reading | HOME | 拒绝，interpreter must be idle |
| on/auto/reading | SET_MODE manual | 拒绝或按 C++ abort/synch 明确处理 |
| on/auto/idle/no program | RUN | 拒绝，无程序 |
| on/manual/idle | PAUSE | 拒绝 |
| on/auto/idle | PAUSE | 拒绝或忽略 |
| on/auto/paused/resumeInhibit | RESUME | 拒绝 |
| homing active | RUN/STEP/JOG/HOME | 拒绝 |

失败条件：

- UI 禁用但 runtime 接受非法命令。
- runtime 拒绝但 UI 显示允许。
- 非法命令改变状态。

## 11. 真实程序功能验收

真实程序验收不能只看按钮状态，需要验证程序执行功能：

1. 使用 LinuxCNC `xyzbc-trt` 配置真实可运行 G-code。
2. Native 和 Web 使用同一 G-code、同一 INI/HAL/profile、同一采样周期。
3. 采集预览路径、执行路径、task 状态、motion 状态、joint home 状态、line/motion id。
4. 在执行中插入 Pause、Resume、Step、ESTOP。
5. 对比每个动作前后真实程序状态。

必须检查：

- G-code line 读取顺序。
- `readLine/currentLine/motionLine` 对齐。
- motion id 单步推进。
- Pause 时路径冻结。
- Resume 后继续同一程序，不重头执行。
- ESTOP 后停止且不能继续运动。
- Home 前 Run 必须失败。

## 12. Compare 硬通过标准

compare 输出必须包含以下硬检查：

| 检查名 | 必须为 pass 的依据 |
|---|---|
| `cppTaskStateMachineParity` | ESTOP/RESET/ON/OFF 与 `emcTaskSetState()` 和 task update 推导一致 |
| `cppModeGateParity` | `emcTaskSetMode()` 的 AUTO 非 idle 限制一致 |
| `cppHomingParity` | `EMCMOT_JOINT_HOME` 和 `homing.c` 状态流一致 |
| `cppRunGateParity` | `EMC_TASK_PLAN_RUN` 的 ON/AUTO/IDLE/Home/Program gate 一致 |
| `cppPauseResumeParity` | `EMC_TASK_PLAN_PAUSE/RESUME` 和 `EMCMOT_PAUSE/RESUME` 一致 |
| `cppStepParity` | `EMC_TASK_PLAN_STEP` 和 `EMCMOT_STEP` 的 motion id 单步一致 |
| `illegalCommandParity` | runtime 和 UI gate 一致拒绝非法命令 |
| `realProgramExecutionParity` | 真实程序 line/path/pose/status 一致 |

最终判定规则：

```text
如果 legacy compare 60/60 pass，但任一 cpp*Parity 或 realProgramExecutionParity fail，则整体验收 fail。
如果 smoke pass，但非法命令矩阵 fail，则整体验收 fail。
如果截图正常，但 task/motion 状态流不符合 C++，则整体验收 fail。
```

## 13. 验收记录模板

每轮验收必须记录：

```text
验收时间：
LinuxCNC 源码 commit/版本：
Web 项目 commit/工作区状态：
使用 INI：
使用 G-code：
Native evidence：
Web evidence：
Compare evidence：
surfaceSummary：
functionalSummary：
失败项：
是否允许宣称真实通过：
结论：
```

结论只能使用：

- `真实通过`：所有 functional hard checks 通过。
- `表面通过但功能未通过`：legacy 60/60 通过但硬规则失败。
- `未通过`：legacy 或 functional 任一失败。
- `阻塞`：缺少 native evidence、Web evidence 或 C++ 映射。