同步五轴仿真文档和验证证据

work/working1/01-功能内容.md

@@ -0,0 +1,112 @@
+# 01-功能内容
+
+## 功能目标
+
+完善 Web RTCP 五轴仿真页面的数控控制按钮互相功能，使按钮状态和点击反馈真实反映 LinuxCNC task/HAL 控制状态。
+
+本轮优先完成的按钮：
+
+- Run
+- Stop
+- Pause
+- Resume
+- Step
+- Home
+
+## 已实现内容
+
+1. Run 条件检查和提示
+   - 当执行条件不具备时，Run 按钮保持可点击。
+   - 点击后通过 `operatorMessage` 提示具体原因，例如机器未上电、未切到 AUTO、未 Home、task/HAL runtime 未就绪、未加载 LinuxCNC machine-file G-code 等。
+   - 前端按钮增加 `data-command-ready` 和 `aria-disabled` 状态，避免按钮被禁用后无法给出提示。
+
+2. Stop
+   - Web store 发送 `EMC_TASK_ABORT`。
+   - task/HAL 状态回到 idle/stopped。
+   - motion runtime 标记 aborted，并清空/停止执行队列。
+
+3. Pause
+   - Web store 发送 `EMC_TASK_PLAN_PAUSE`。
+   - task/HAL runtime 将解释器状态置为 `PAUSED`。
+   - motion runtime 接收 `EMC_TRAJ_PAUSE`，运动状态进入 paused。
+
+4. Resume
+   - Web store 发送 `EMC_TASK_PLAN_RESUME`。
+   - 仅当返回的 LinuxCNC task/HAL 状态仍应继续运行时，才恢复 task/HAL status loop。
+   - 避免 Resume 后在已完成、已停止或不应运行的状态下继续轮询。
+
+5. Step
+   - Web store 发送 `EMC_TASK_PLAN_STEP`，不再只跑空 cycle。
+   - task/HAL runtime 记录 `singleStepping=true` 和 `taskPaused=true`。
+   - motion runtime 增加 `EMC_TRAJ_STEP` / `EMCMOT_STEP` 支持，在 paused 状态下允许 step 命令通过。
+
+6. Home
+   - Web store 发送 `EMC_JOINT_HOME`。
+   - Home 后立即保持 Web 侧 `allHomed=true`，防止快速 `HOME -> SET_MODE` 时序丢失已归零状态。
+   - task/HAL 状态 patch 保留 `allHomed` 和 `noForceHoming`。
+   - task/HAL session 初始化时停止旧 status loop，防止旧循环覆盖新 session 状态。
+
+## LinuxCNC 源码依据
+
+参考 LinuxCNC 源程序：
+
+- `/home/meswork/cnc_wams/linuxcnc/src/emc/task/emctaskmain.cc`
+- `/home/meswork/cnc_wams/linuxcnc/src/emc/nml_intf/emc_nml.hh`
+- `/home/meswork/cnc_wams/linuxcnc/src/emc/nml_intf/emc.hh`
+
+对应命令语义：
+
+- `EMC_TASK_PLAN_RUN`
+- `EMC_TASK_PLAN_PAUSE`
+- `EMC_TASK_PLAN_RESUME`
+- `EMC_TASK_PLAN_STEP`
+- `EMC_TASK_ABORT`
+- `EMC_JOINT_HOME`
+- `EMC_TRAJ_PAUSE`
+- `EMC_TRAJ_RESUME`
+- `EMC_TRAJ_STEP`
+- `EMC_TRAJ_ABORT`
+
+## 修改文件
+
+- `/home/meswork/cnc_wams/web-rtcp-5axis-sim-plan/app/src/ui/gmoccapy-shell.js`
+- `/home/meswork/cnc_wams/web-rtcp-5axis-sim-plan/app/src/state/store.js`
+- `/home/meswork/cnc_wams/wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
+- `/home/meswork/cnc_wams/wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c`
+- `/home/meswork/cnc_wams/web-rtcp-5axis-sim-plan/tests/node/verify_linuxcnc_task_hal_runtime.mjs`
+- `/home/meswork/cnc_wams/web-rtcp-5axis-sim-plan/tests/browser/gmoccapy_shell_smoke.html`
+
+## 当前完成状态
+
+状态：已完成并通过选定严格测试。
+
+补充验收：已新增本地浏览器按钮流程取证，覆盖 Home、Run、Pause、Resume、Step、Stop 点击前后状态截图和 JSON 报告。
+
+取证文件：
+
+- `/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/capture-button-control-evidence.mjs`
+- `/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/button-control-evidence-report.json`
+- `/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/button-control-evidence-report.pdf`
+- `/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/screenshots/button-control-evidence/`
+
+云端补充验收：
+
+- 已重新部署当前静态站点到 `https://82.156.24.101:8092/`。
+- 已使用同一按钮流程脚本采集云端 Home、Run、Pause、Resume、Step、Stop 点击前后状态。
+- 云端报告状态：`PASS`
+- job_id：`btn-20260623091811-c291e49b`
+- report_id：`report-btn-20260623091811-c291e49b`
+- 云端 JSON：`/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/cloud-button-control-evidence-report.json`
+- 云端 PDF：`/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/cloud-button-control-evidence-report.pdf`
+- 云端截图：`/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/screenshots/cloud-button-control-evidence/`
+
+Native 对照补充验收：
+
+- 已生成 native task/HAL 对照报告。
+- 报告状态：`PASS_WITH_HOST_NATIVE_RUNTIME_BLOCKER`
+- 报告文件：
+  - `/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/native-task-hal-comparison-report.json`
+  - `/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/native-task-hal-comparison-report.md`
+- 结论：LinuxCNC source/phase0/native readiness audit 对照通过；host-native TRT runtime 状态转换日志因当前主机 native runtime 依赖阻塞无法生成。
+
+注意：本轮仍不声明真实硬件驱动、host realtime kernel、外部 User-M process 或 tool DB native runtime 已具备；这些边界在 native 对照报告中明确记录。