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

06-决策记录

DR-W6-001：working6 作为 working5 后续深化，不作为未完成补丁

日期：2026-06-27

决策：

• working6 不是修补 working5 未完成项，而是承接 working5 台账中“可选深化方向”。
• 本轮主线聚焦 gmoccapy 文件/宏页面、tool editor 页面、native GTK 未实现页面诊断边界。
• working5 中已完成的 HAL 输入、hard-button、状态机门控、换刀回环和低频 HAL pin 行为不得在 working6 中回退。

原因：

• working5 任务矩阵 W5-001 到 W5-900 已全部完成，并有 EV-W5-900 最终复核证据。
• 文件/宏/tool editor/native GTK 页面属于页面级能力和诊断边界深化，风险面和验收口径不同于 working5 的 HAL pin 细化。

影响：

• working6 需要独立任务矩阵、验收证据和决策记录。
• 后续提交或验收应区分 W5 已闭环行为与 W6 新增页面级诊断行为。

DR-W6-002：未实现 native GTK 页面必须诊断化，不伪装成已实现

日期：2026-06-27

决策：

• 对 gmoccapy 原生存在但 Web 尚未完整实现的页面，先建立 implementation matrix。
• Web UI 可以显示 diagnostic-only 状态、源码对应关系、未实现原因和未来补齐入口。
• 未实现页面按钮和 hard-button pin 不得触发假的成功状态。

原因：

• gmoccapy 原生 GTK 页面和 Web shell 的布局、运行环境、文件系统权限、HAL 交互能力不同。
• 若直接把未实现页面显示为可操作，会误导验收，掩盖仿真边界。

影响：

• UI 和 tests 必须验证 diagnostic-only/unsupported/not configured 等边界文案或结构化状态。
• store 中未实现 action 应返回明确 operator message。

DR-W6-003：文件/宏/tool editor 先按 XYZAB 配置边界建模

日期：2026-06-27

决策：

• 文件页面、宏页面和 tool editor 页面优先按 gmoccapy_XYZAB.ini 当前配置和 Web 仿真能力建模。
• 配置未启用的能力显示为 no config 或 diagnostic-only。
• 真实文件写入、外部 LinuxCNC 进程联动和持久化 tool table 修改不作为初始实现默认目标。

原因：

• 当前 Web 项目是 LinuxCNC/gmoccapy 行为仿真，不是完整桌面 gmoccapy 进程。
• XYZAB 配置的宏、tool sensor、user message 等能力存在明确启用边界。
• 先把边界表达清楚，后续才能安全决定哪些功能升级为可执行。

影响：

• W6-100、W6-110、W6-120 的验收重点是“能力、gate、边界和诊断是否正确”，不是盲目补齐所有 GTK 行为。
• 若后续要启用真实写文件或外部进程，需要新增决策记录和验收任务。

DR-W6-004：XYZAB 宏页按已配置 5 个 [MACROS] 建模

日期：2026-06-27

决策：

• gmoccapy_XYZAB.ini 的 [MACROS] 中 5 个宏必须建模为已配置能力：
  • i_am_lost
  • halo_world
  • jog_around
  • increment xinc yinc
  • go_to_position X-pos Y-pos Z-pos
• Web 通过 GMOCAPY_RUN_MACRO 模拟 _on_btn_macro_pressed()，生成 O<name> call [args] MDI 命令。
• 宏执行必须复用 RUN_MDI gate；未上电、未回零、非 MDI-capable 或解释器忙时拦截。

原因：

• 初始文档把“未配置宏时显示边界”列为需要处理的通用场景，但实际 XYZAB INI 明确配置了 5 个宏。
• gmoccapy 原生 _make_macro_button() 从 INI 读取宏，_on_btn_macro_pressed() 将宏转为 O-word MDI 调用。

影响：

• profile、HAL model、communication model、store、Node/browser tests 均断言 XYZAB 宏 count 为 5。
• Web 不创建 native entry dialog；参数由 dispatch/test 传入，后续如需 UI 参数输入需要单独任务。

DR-W6-005：tool editor 本轮只做诊断和 gate，不写 tool.tbl

日期：2026-06-27

决策：

• Web 记录 tooledit1、tool.tbl、17 把刀、可见 XYZAB 轴和 M6/M61 工具动作边界。
• GMOCAPY_TOOL_EDITOR_ACTION 对 save、add、delete、touch-off 等写操作返回 diagnostic-only/operator message，不修改本地 tool.tbl。
• 工具换刀继续沿用 working5 的 iocontrol-loopback，不重新启用手动 gmoccapy toolchange GUI pins。

原因：

• 原生 gmoccapy tool editor 可以直接写配置目录中的 tool.tbl，但浏览器 Web 仿真没有等价的 LinuxCNC 配置写回权限和进程同步语义。
• 未经单独设计直接写文件会混淆“诊断仿真”和“真实机床配置修改”的边界。

影响：

• 本轮验收关注 tool table 来源、数量、只读边界和换刀语义一致性。
• 后续若要实现真实写回，需要新增持久化设计、备份策略、并发保护和验收任务。

DR-W6-006：hard-button 对 native-only/diagnostic-only 页面使用结构化页面诊断

日期：2026-06-27

决策：

• tbtn_user_tabs、tbtn_setup、btn_touch、btn_tool、tbtn_switch_mode 不再作为普通 Web action 或模式切换伪装执行。
• 这些按钮通过 GMOCAPY_NATIVE_PAGE 更新 gmoccapyGui.activeNativePage、nativePageMode 和 operator message。
• UI 通过 data-gmoccapy-page="matrix" 展示 native GTK 页面实现矩阵。

原因：

• gmoccapy 原生 _button_pin_changed() 会触发当前可见且敏感的 GTK 按钮，但 Web shell 尚未实现完整 setup/user tabs/touch/tool/switchkins 页面。
• 直接把这些按钮映射成其他 Web action 会误表达 native 行为。

影响：

• hard-button 模型仍保留 pin 到 native widget 的源码映射。
• Web 验收明确区分 implemented、partial、diagnostic-only、native-only 页面，避免后续重复争论“未实现页面是否可点击成功”。