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

work/working1/06-决策记录.md

@@ -0,0 +1,187 @@
+# 06-决策记录
+
+## DR-001：按钮 blocked 时保持可点击
+
+决策：Run、Stop、Pause、Resume、Step、Home 在 gate blocked 时不设置 HTML `disabled`。
+
+原因：
+
+- 用户要求点击 Run 时，如果执行条件不具备，请提示。
+- HTML disabled 按钮无法触发 click，用户拿不到具体阻塞原因。
+- 保持按钮可点击，同时用 `data-command-ready=false`、`aria-disabled=true`、title 和 operatorMessage 表达 blocked 状态，更符合操作员界面需求。
+
+影响：
+
+- blocked 按钮仍能 dispatch action。
+- store gate 是最终裁决点。
+- UI 可以显示真实阻塞原因。
+
+## DR-002：按钮语义以 LinuxCNC task command 为准
+
+决策：不新增独立 JavaScript CNC 行为，按钮映射 LinuxCNC command。
+
+映射：
+
+- Run -> `EMC_TASK_PLAN_RUN`
+- Stop -> `EMC_TASK_ABORT`
+- Pause -> `EMC_TASK_PLAN_PAUSE`
+- Resume -> `EMC_TASK_PLAN_RESUME`
+- Step -> `EMC_TASK_PLAN_STEP`
+- Home -> `EMC_JOINT_HOME`
+
+原因：
+
+- `wasm-port/SKILL.md` 要求 LinuxCNC 源码是语义源。
+- LinuxCNC task 状态、解释器状态、pause/resume/step 行为已有明确实现。
+- Web 端只应做 runtime edge adapter 和 UI 显示。
+
+参考：
+
+- `/home/meswork/cnc_wams/linuxcnc/src/emc/task/emctaskmain.cc`
+- `/home/meswork/cnc_wams/linuxcnc/src/emc/nml_intf/emc_nml.hh`
+
+## DR-003：Step 必须发送 `EMC_TASK_PLAN_STEP`
+
+决策：Step 不再只执行空 task cycle，必须发送 `EMC_TASK_PLAN_STEP`。
+
+原因：
+
+- LinuxCNC 中单步由 `EMC_TASK_PLAN_STEP`、`single_stepping`、`steppingWait` 等状态控制。
+- 空 cycle 不能表达 operator step command，也不能作为验收依据。
+
+影响：
+
+- task/HAL runtime 增加 `singleStepping` 状态。
+- motion runtime 增加 `EMC_TRAJ_STEP` 支持。
+- Node 测试验证 `singleStepping=true`。
+
+## DR-004：Resume 后是否重启 status loop 由返回状态决定
+
+决策：Resume command 完成后，用 `shouldContinueTaskHalStatusLoop(state, status)` 判断是否恢复轮询。
+
+原因：
+
+- 旧逻辑只看旧 state，可能在已经完成、停止或状态不应继续时重启 loop。
+- LinuxCNC task/HAL status 是更可信的数据来源。
+
+影响：
+
+- 减少旧 status loop 覆盖新命令状态的风险。
+- Pause/Resume 更接近 LinuxCNC task 状态。
+
+## DR-005：Home 在 Web 状态中立即标记 homed
+
+决策：task/HAL HOME dispatch 时，先同步 Web 侧 machine 状态，再异步发送 `EMC_JOINT_HOME`。
+
+原因：
+
+- 前端操作可能快速执行 `HOME -> SET_MODE auto/mdi`。
+- 如果只等异步 task/HAL status 返回，后续 mode command 可能覆盖 Home 状态，导致 Run 或 MDI 被错误阻止。
+- 这是 standalone Web runtime 的异步边界适配，不改变 LinuxCNC Home 命令语义。
+
+影响：
+
+- `allHomed=true` 不会因快速模式切换丢失。
+- task/HAL runtime 仍会收到 `EMC_JOINT_HOME`。
+
+## DR-006：初始化 task/HAL session 时停止旧 status loop
+
+决策：`initializeTaskHalSession()` 开始时停止旧 `taskHalStatusLoop`。
+
+原因：
+
+- session reset 会重置 task/HAL runtime。
+- 旧 status loop 如果继续运行，可能把旧运行状态覆盖到新 session 或 MDI command 上。
+
+影响：
+
+- MDI `M428` 后 `switchkinsType=1` 不会被旧 loop 覆盖。
+- 新 session 状态边界更清晰。
+
+## DR-007：保留 `allHomed` 和 `noForceHoming`
+
+决策：`applyTaskHalStatusPatch()` 在合并 task/HAL status 时保留 Web policy 状态中的 `allHomed` 和 `noForceHoming`。
+
+原因：
+
+- 当前 standalone task/HAL status JSON 不完整表达所有 LinuxCNC homing policy 细节。
+- Web task policy gate 需要这些字段判断 Run/MDI 是否允许。
+
+影响：
+
+- Run gate 不会因为 status patch 丢失 homed/policy 信息而错误阻止。
+
+## DR-008：本轮不做真实硬件控制
+
+决策：只完善 Web/WASM standalone simulation task/HAL 状态，不接入真实硬件。
+
+原因：
+
+- 项目边界明确：Web simulation，不驱动真实硬件。
+- `wasm-port/SKILL.md` 明确 realtime scheduling、driver、native HAL runtime internals 是替换边界。
+
+影响：
+
+- 验收以 WASM/Node/browser simulation 为准。
+- 后续若要硬件级对照，应另建 native LinuxCNC 验收任务。
+
+## DR-009：云端验收另行执行
+
+决策：本轮文档记录本地严格测试证据；云端 `https://82.156.24.101:8092/` 需要部署后单独采集。后续已执行部署和云端取证，见 DR-011。
+
+原因：
+
+- 本轮代码和测试在本地 workspace 完成。
+- 未执行云端部署命令，也未产生云端 job_id/report_id/PDF。
+
+影响：
+
+- 当前功能代码已完成。
+- 云端验收截图/报告已在后续步骤补齐。
+
+## DR-010：按钮流程截图取证独立于 browser smoke
+
+决策：新增 `qa/web-rtcp-5axis-site-test/capture-button-control-evidence.mjs`，不把截图取证逻辑塞进 `gmoccapy_shell_smoke.html`。
+
+原因：
+
+- browser smoke 用于快速回归，职责是发现核心渲染和行为回退。
+- 按钮流程取证会启动 Puppeteer、采集 PNG、分析像素并写 JSON，执行成本和输出体积更大。
+- 独立脚本可以稳定保留 Home/Run/Pause/Resume/Step/Stop 的验收证据，同时不拖慢常规 smoke。
+
+影响：
+
+- BTN-012 的验收入口是独立 QA 命令。
+- 截图和 JSON 报告保存在 `qa/web-rtcp-5axis-site-test/` 下，可用于交付或人工复核。
+
+## DR-011：云端 BTN-011 以同一按钮流程脚本验收
+
+决策：使用参数化后的 `capture-button-control-evidence.mjs` 对 `https://82.156.24.101:8092/` 运行同一套 Home/Run/Pause/Resume/Step/Stop 验收。
+
+原因：
+
+- 同一脚本能保证本地和云端验收标准一致。
+- 云端验收必须包含 job_id、report_id、PDF、截图和 JSON。
+- 云端 machine-file seed 比本地慢，脚本改为轮询 runtime readiness 和 staging 状态，避免 Puppeteer 长 Promise 被回收。
+
+影响：
+
+- BTN-011 已完成。
+- 云端报告为 `PASS`，job_id 为 `btn-20260623091811-c291e49b`。
+
+## DR-012：BTN-013 以 native/source 对照和 host blocker 报告完成
+
+决策：不把当前主机无法运行的 host-native TRT task/HAL runtime 伪装成已通过；BTN-013 的完成产物是 `native-task-hal-comparison-report.json/md`。
+
+原因：
+
+- 默认 phase0 native source/probe gate 和 Web native readiness audit 均通过。
+- opt-in native runtime probe 尝试后失败，`linuxcnc.stderr.log` 显示 LinuxCNC RIP 脚本引用旧绝对路径 `/home/cnc/桌面/cnc_wams/linuxcnc/scripts/rip-environment`。
+- `ldd` 显示当前主机还缺少 `GLIBC_2.38`、`GLIBCXX_3.4.31`、`libpython3.13.so.1.0` 等 native runtime 依赖。
+- 在这些 host 条件未满足前，无法生成真实 native LinuxCNC task 状态转换日志。
+
+影响：
+
+- BTN-013 标记为 `Done-with-blocker`。
+- 本轮仍只声明 Web/WASM simulation boundary 的 task/HAL 行为完成。
+- 真实 host realtime/hardware/external process/tool DB native runtime 仍不提升为完成状态。