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

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 仍不提升为完成状态。