# 01-项目功能内容

## 项目目标

完善 `/home/mes123456/cnc_wams/wasm-port` 中 LinuxCNC WASM task/motion 执行链，使 `/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan` 的 AXIS 风格“执行 Run”按钮按 LinuxCNC 语义工作。

最终用户可见目标：

1. 未解除急停、未上电、未 Home 或未打开程序时，Run 按钮不能绕过 LinuxCNC 门禁。
2. 满足条件后点击 Run，系统切到 `MODE_AUTO`，发送 `EMC_TASK_PLAN_RUN`，task 进入 `INTERP_READING` 或 `INTERP_WAITING`。
3. 执行中当前行、队列深度、motion id、DRO、TCP、RTCP 位置由 task/motion status 驱动。
4. 执行中 Pause、Resume、Step 继续走 task/motion 命令链，不直接操作前端播放状态。
5. 执行完成、错误、急停、下电、abort 后，UI 与 task/motion status 一致，不能残留“前端 running”假状态。

## LinuxCNC 对标依据

来源文档：

`/home/mes123456/cnc_wams/项目分析/AXIS主控制按钮调用链与WASM完善指南.md`

核心调用链：

```text
AXIS task_run()
  -> ensure_mode(MODE_AUTO)
  -> linuxcnc.command().auto(AUTO_RUN, line)
  -> EMC_TASK_PLAN_RUN
  -> emcTaskPlan()
  -> emcTaskIssueCommand()
  -> interpreter readahead
  -> canonical motion commands
  -> taskintf.cc
  -> EMCMOT_SET_LINE / EMCMOT_SET_CIRCLE / ...
  -> motion command/control cycle
  -> emcStatus
  -> linuxcnc.stat().poll()
```

Run 不是前端播放按钮。LinuxCNC 中 Run 的真实结果是 task 解释器状态、motion 队列、status echo 和 GUI 可见状态共同变化。

## 功能范围

### 必须覆盖

1. 急停与解除急停：
   - `STATE_ESTOP` 与 `STATE_ESTOP_RESET` 的切换。
   - ESTOP 分支 abort、motion disable、IO estop on、volatile home 清理。
2. 上电与下电：
   - 只有 `STATE_ESTOP_RESET` 才能进入 `STATE_ON`。
   - `STATE_ON` 由 motion enabled 状态推导，不由前端直接写死。
3. Home：
   - Run 前必须满足 all homed 或 `no_force_homing`。
   - Home 应有 `homing -> homed` 过程态。
4. Run：
   - `MODE_AUTO`。
   - `EMC_TASK_PLAN_RUN`。
   - `interpState=READING`、`taskPaused=false`、`singleStepping=false`。
   - 程序文件已 open，或 task 能按 `emcStatus->task.file` 打开。
5. Pause/Resume/Step：
   - 作为 Run 后执行过程控制，不作为独立前端播放逻辑。
   - Pause 后 `taskPaused=true` 且 `motion.paused=true`。
   - Step 只推进一个 motion id 或一个可观测执行边界，并回到 paused。
6. Status 投影：
   - Web store 中 `taskState/mode/interpState/runState/currentLine/motionPaused/singleStepping` 来自 task/HAL status。

### 暂不覆盖

1. 完整 LinuxCNC NML 网络传输。WASM 可用内存队列替代 NML transport，但命令类型和状态语义必须保留。
2. 完整实时 HAL。当前阶段只要求 task/motion/Home/Run/Pause/Step 相关 HAL pin 可观测。
3. 所有 G-code 语义。G-code 到 canonical motion 应优先来自 LinuxCNC interpreter，不在 Web 层扩写解释器。

## 当前代码基线

### wasm-port 已有基础

关键文件：

- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c`
- `wasm-port/runtime/sdk/src/linuxcnc-task-hal.js`
- `wasm-port/tests/wasm/node/verify_task_hal_wasm.mjs`

已具备的基础：

- task/HAL WASM 入口已经存在。
- Pause/Resume/Step 已有 working8 基础验证。
- status JSON 已能输出部分 task/motion 字段。
- Web 项目已经能加载 task-hal WASM 并把部分 status 映射到 store。

### 主要差距

1. task/HAL runtime 仍有 `phase4_minimal` 过渡实现痕迹，部分命令解析和 G-code motion 派生仍是手写逻辑。
2. Run 的门禁需要完全对齐 `emcTaskPlan()`：不能只看 Web 自定义 `runState`。
3. 程序 open、canonical motion plan、motion queue、current line 的来源需要收敛到 LinuxCNC interpreter/task/motion 状态。
4. Home 状态常见简化是立即 `allHomed=true`，缺少 `homing/homeState` 过程态。
5. Web store 仍可能存在点击 Run 后直接写 `running` 的分支，需要改为等待 WASM status 确认。
6. 验收不能只看按钮 active，需要读取 task/HAL status、trace、截图和 Node/browser 断言。

## 完成定义

本项目完成必须同时满足：

1. Run 前置门禁：
   - ESTOP 下 Run 被拒绝。
   - ESTOP_RESET 未上电时 Run 被拒绝。
   - ON 但未 Home 且 `no_force_homing=false` 时 Run 被拒绝。
   - 未 open 程序或没有 canonical plan 时 Run 被拒绝并给出明确错误。
2. Run 命令链：
   - UI 点击 Run 后发送 `MODE_AUTO` 和 `EMC_TASK_PLAN_RUN`。
   - WASM status 显示 `task.mode=AUTO`。
   - WASM status 显示 `task.interpState=READING/WAITING`。
   - `task.taskPaused=false`、`motion.traj.singleStepping=false`。
3. 执行状态：
   - motion queue 或 canonical execution id 可观测。
   - 当前行、motion id、DRO/TCP 随 status 推进。
   - 执行完成后进入 `INTERP_IDLE` 与 `DONE` 或等价完成状态。
4. 执行中控制：
   - Pause 后 task 和 motion 双层 paused。
   - Resume 后恢复暂停前状态。
   - Step 后只推进一个边界并回到 paused。
5. Web 集成：
   - Web `runState` 是 task/HAL status 投影。
   - UI 按钮 enable/active 状态与 LinuxCNC 门禁一致。
   - 浏览器 trace 能证明 Run 后位置推进、Pause 后冻结、Resume 后继续。

## 非目标与风险提醒

1. 不把 Web frame 播放器当作 CNC task。
2. 不在 JS 中新增 G-code 正则解释器作为长期方案。
3. 不因为 UI 看起来 running 就关闭任务，必须有 WASM status 证据。
4. 不把单步实现为数组下标加一，Step 必须进入 task/motion 单步状态机。