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

06-决策记录

DR-W5-001：以 gmoccapy_XYZAB 执行流程作为本轮验收主线

日期：2026-06-26

决策：

• 本轮不只验证图形 RTCP 轨迹，而是按 LinuxCNC 启动、INI/HAL、task/NML、interpreter、gmoccapy UI 通信和互锁全链路推进。

原因：

• 用户指定的基准文件覆盖了 gmoccapy_XYZAB.ini 五轴仿真从启动到界面通信的完整执行流程。
• 若只看轨迹显示，容易遗漏回零、状态机、换刀、主轴到速、冷却、UI gate 等数控系统仿真关键行为。

影响：

• 任务矩阵按 LinuxCNC 行为拆分。
• 任何实现修改都需要补充对应测试或验收证据。

DR-W5-002：模式按钮门控前移到 SET_MODE 和 UI disabled 状态

日期：2026-06-26

决策：

• Web 侧 SET_MODE 统一按 LinuxCNC/gmoccapy 状态门控。
• STATE_OFF 或未上电时，Manual/Jog/MDI/Auto 都禁止切换。
• STATE_ON 但未全轴回零且 NO_FORCE_HOMING = 0 时，只允许 Manual/Jog，禁止 MDI/Auto。
• 回零后 MDI/Auto 恢复可用；Auto 解释器非 idle 时仍禁止离开 Auto。

原因：

• LinuxCNC gmoccapy.py 的 on_hal_status_state_off() 会禁用 rbt_manual、rbt_mdi、rbt_auto。
• on_hal_status_state_on() 先只启用 rbt_manual，退出设置页时也明确区分“未回零只 Manual 可用”和“已回零三种模式可用”。
• 旧 Web 实现主要在 RUN 和 RUN_MDI 时拦截，模式按钮本身仍可点击，不符合 gmoccapy 的按钮敏感状态。

影响：

• app/src/state/linuxcnc-task-policy.js 成为模式切换和执行动作的统一互锁入口。
• app/src/ui/gmoccapy-shell.js 侧边模式按钮使用同一 gate 输出 disabled、data-command-ready 和 aria-disabled。
• Node 和浏览器测试增加下电、未回零、已回零三个阶段的断言。

DR-W5-003：XYZAB 换刀按 POSTGUI iocontrol 回环建模，不实现手动换刀弹窗

日期：2026-06-26

决策：

• gmoccapy-xyzab profile 和 gmoccapyHalModel 将 M6/M61 换刀执行路径标记为 iocontrol-loopback。
• manualGmoccapyPinsConnected = false，用于说明 gmoccapy.toolchange-change、gmoccapy.toolchange-changed、gmoccapy.toolchange-number 在该配置中没有作为活动 HAL net 接入。
• UI 只显示换刀 HAL 诊断，不弹出 gmoccapy 手动换刀确认流程。

原因：

• gmoccapy_postgui.hal 在 GUI HAL pins 创建后执行 unlinkp iocontrol.0.tool-change、unlinkp iocontrol.0.tool-changed、unlinkp iocontrol.0.tool-prep-number。
• 同一文件里连接 gmoccapy.toolchange-* 的手动换刀 nets 保持注释状态。
• 活动换刀完成路径是 net tool-change-loop iocontrol.0.tool-change => iocontrol.0.tool-changed，与 core_sim_XYZAB.hal 的仿真换刀回环语义一致。

影响：

• HAL/profile 诊断现在能区分“存在 gmoccapy toolchange pins”与“此配置没有把这些 pins 接入手动换刀流程”。
• verify_gmoccapy_hal_model.mjs、verify_gmoccapy_xyzab_profile.mjs、verify_profile_boundary.mjs 和浏览器 smoke 均覆盖该换刀语义。

DR-W5-004：外部 HAL hard-button pin 使用显式映射，不依赖 Web DOM 顺序

日期：2026-06-26

决策：

• Web 侧将 gmoccapy.h-button.*、gmoccapy.v-button.* 建模为显式 pin 到 Web action/selector 的映射。
• GMOCAPY_HARDWARE_BUTTON action 只模拟 rising edge；falling edge 忽略；可执行 pin 复用原有 Web action 和 linuxcnc-task-policy gate。
• Web DOM 使用 data-gmoccapy-hal-pin、data-gmoccapy-native-panel、data-gmoccapy-native-button-index 标记原生 hard-button 对应关系，而不是依赖当前页面按钮的 DOM 顺序。
• 未实现的 native 页面按钮，如 tbtn_setup、btn_touch、btn_tool、tbtn_switch_mode，只保留诊断映射，不伪装成已实现控制。

原因：

• LinuxCNC gmoccapy.py 的 _button_pin_changed() 只响应 pin 为 true 的 rising edge。
• _get_child_button() 按当前 notebook 页或 vbtb_main 的可见非 label 子控件位置查找按钮，并在目标不敏感时忽略。
• gmoccapy.glade 中 vbtb_main 的原生顺序是 tbtn_estop、tbtn_on、rbt_manual、rbt_mdi、rbt_auto、tbtn_user_tabs、tbtn_setup，Web shell 右侧还包含 reset/TCP 等非原生布局控件，直接用 DOM 顺序会误表达 native 语义。

影响：

• gmoccapy-xyzab panel schema 修正 Estop/Power/Manual/MDI/Auto 的 v-button pin 顺序。
• HAL model、communication model、store、UI DOM 和浏览器 smoke 都能追踪 hard-button pin 到 Web action/gate 的行为。
• 未完成的 optional-stop、blockdelete、ignore-limits 等 pin 仍作为后续独立任务处理。

DR-W5-005：HAL input pin 按 gmoccapy 回调语义建模，不按名称直连

日期：2026-06-27

决策：

• Web 侧新增 GMOCAPY_HAL_PIN action，用于模拟外部 HAL 输入 pin 对 gmoccapy GUI 状态和命令的影响。
• gmoccapy.ignore-limits 设置 chk_ignore_limits 等效状态，active 时记录 command.override_limits() 请求语义。
• gmoccapy.optional-stop 不直连 optional stop，而是按源码 _optional_blocks() 驱动 tbtn_optional_blocks，也就是 block delete。
• gmoccapy.blockdelete 不直连 block delete，而是按源码 _blockdelete() 调用 command.set_optional_stop()。
• override counts 只有对应 *.count-enable 为 true 时才调整滑块；否则只同步 counts 基线。
• override direct-value 只有对应 *.analog-enable 为 true 时才接管滑块；reset pins 只响应 true/rising edge。

原因：

• gmoccapy.py 中 optional-stop pin 连接 _optional_blocks()，该回调设置 tbtn_optional_blocks，随后 on_tbtn_optional_blocks_toggled() 调用 command.set_block_delete()。
• gmoccapy.py 中 blockdelete pin 连接 _blockdelete()，该回调调用 command.set_optional_stop()。
• _on_counts_changed()、_on_analog_value_changed() 和 _reset_override() 明确要求 enable/rising-edge 条件；gmoccapy_XYZAB.pref 给出本配置默认 scale：feed/rapid/spindle 为 1，jog velocity 为 140.4。
• 如果按 pin 名称直接连同名 Web 状态，会掩盖 gmoccapy 原生回调的交叉行为和 enable 条件。

影响：

• app/src/state/store.js 新增 gmoccapyGui 状态与 GMOCAPY_HAL_PIN 分发。
• gmoccapyHalModel 和 gmoccapyCommunicationModel 现在显式记录 operator input pins、override pins、enable 规则和 reset 规则。
• UI override 面板提供 ignore limits、block delete、optional stop 和 100% reset 控件，诊断区显示 operator input 与 override input 语义。
• Node 和浏览器 smoke 均覆盖 HAL input/override 语义，防止后续把交叉 pin 改成同名直连。

DR-W5-006：jog 与消息 HAL pin 按 gmoccapy 回调边界建模

日期：2026-06-27

决策：

• gmoccapy.jog.axis.jog-*-plus/minus 作为按下/释放电平输入处理：pin true 触发 jog pressed，pin false 触发 jog released。
• gmoccapy.jog.jog-inc-N 只响应 true/rising edge；jog-inc-0 表示 continuous jog，jog-inc-1..5 映射 gmoccapy_XYZAB.ini 的 [DISPLAY] INCREMENTS。
• gmoccapy.jog.turtle-jog 作为 level-driven 状态记录，不伪装成 Web 普通倍率按钮。
• gmoccapy.delete-message 只在 true 时执行删除消息语义，falling edge 忽略。
• gmoccapy.warning-confirm 作为 warning dialog 轮询确认 pin 记录 level，不强行制造不存在的 Web modal 流程。

原因：

• gmoccapy.py 中 _on_pin_jog_changed() 明确在 pin true 时调用 _on_btn_jog_pressed()，在 pin false 时调用 _on_btn_jog_released()；这与 hard-button 的 rising-edge-only 语义不同。
• _on_pin_incr_changed() 对 not pin.get() 直接 return，因此 jog increment pin 只响应 true；_make_jog_increments() 会把 continuous 的 rbt_0 放在第一位，get_increments() 再把 INI 的 5 个增量值追加到后面。
• _del_message_changed() 只在 pin true 时删除 alert 或最后一条 notification；dialogs.warning_dialog() 每 100ms 轮询 warning-confirm pin 来接受活动 warning dialog。
• 如果把这些 pin 当作普通 Web click 或同名状态直连，会混淆 gmoccapy 源码中 “硬按钮”、“jog pin”、“message pin” 三类不同输入边界。

影响：

• GMOCAPY_HAL_PIN 现在覆盖 jog axis press/release、jog increment selection、turtle jog、delete-message 和 warning-confirm。
• HAL model 和 communication model 现在能分别呈现 hard-button、operator/override input、jog input、message input 的不同语义。
• UI 诊断增加 HAL jog 和 HAL messages，浏览器 smoke 通过 DOM 和公开 dispatch 验证这些语义。

DR-W5-007：低频 settings/tool/user-message HAL pins 按配置启用边界建模

日期：2026-06-27

决策：

• gmoccapy.unlock-settings 作为 level-driven settings input pin 记录；默认 gmoccapy_XYZAB.pref 为 unlock_way=use，所以 Web 中默认只记录 pin level，不把 setup 锁定或解锁。
• 当测试显式模拟 HAL unlock 模式时，unlock-settings 才按 pin level 控制 setupSensitive，对应源码 _on_unlock_settings_changed() 对 rbt_hal_unlock 的条件判断。
• gmoccapy.probeheight、gmoccapy.blockheight、gmoccapy.toolmeasurement、gmoccapy.searchvel、gmoccapy.probevel 作为 tool measurement HAL_OUT pins 记录，不伪装成外部 HAL 输入。
• 当前 gmoccapy_XYZAB.ini 没有 [TOOLSENSOR]，所以 profile、HAL model 和 UI 诊断明确自动测刀默认禁用，而不是暴露为可操作流程。
• 动态 gmoccapy.messages.* pins 只在 INI 存在 MESSAGE_* 配置时创建；当前 XYZAB 没有这些配置，所以 Web 对 messages.* dispatch 返回“未配置”的明确 operator message。

原因：

• gmoccapy.py 中 _on_unlock_settings_changed() 会先检查初始化状态，再检查 rbt_hal_unlock 或 user mode；未选择 HAL unlock 时 pin 变化不应改变 setup 页面可用性。
• _check_toolmeasurement() 需要有效 [TOOLSENSOR] 数据；缺少探针配置时会显示禁用提示、关闭 chk_use_tool_measurement 并使其不敏感。
• on_chk_use_tool_measurement_toggled()、on_spbtn_probe_height_value_changed()、on_btn_block_height_clicked() 都是 GUI/prefs 侧写 HAL_OUT pins，不是外部 HAL 驱动 GUI 的输入边界。
• _init_user_messages() 只有从 INI 读到 user messages 才创建 messages.<pinname>、messages.<pinname>-waiting、messages.<pinname>-response；当前 gmoccapy_XYZAB.ini 没有 MESSAGE_* 项。

影响：

• gmoccapy-xyzab profile 补齐 settings/tool measurement/toolchange confirm 相关 pins，并记录 no [TOOLSENSOR] 与 no MESSAGE_* 原因。
• HAL model 和 communication model 能展示 settings input、tool measurement HAL_OUT、dynamic user message 三类不同边界。
• Store 和浏览器 smoke 覆盖 unlock-settings 默认忽略、HAL unlock level 控制、blockheight 诊断记录和 messages.* 未配置提示。