# 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.*` 未配置提示。
