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