cnc_wams/work/working4/06-decision-records.md

06 决策记录

生成日期：2026-06-26

ADR-001：working3 作为参考输入，不直接作为 runtime 依赖

状态：accepted

决策：

working3 中的 Markdown、CSV 和图标文件是功能完善的参考输入。后续实现时应把需要长期使用的资料复制或转换到 web-rtcp-5axis-sim-plan 内部目录，而不是让应用运行时依赖 work/working3。

原因：

• work/working3 是资料整理目录，不是产品运行目录。
• Web 应用需要稳定的 assets、manifest 和 source map。
• 这样可以在追溯矩阵中明确来源，同时避免后续清理 work/ 时破坏应用。

后续影响：

• 图标必须落到 app/src/assets/gmoccapy-icons/ 或等价目录。
• CSV 必须转换为 JSON manifest 或构建期可解析资产。

ADR-002：不移植 native gmoccapy GTK/Glade runtime

状态：accepted

决策：

Web 项目只参考 gmoccapy 的布局、按钮、互锁和通信模型，不把 gmoccapy.py、GTK、Glade、Python REMAP runtime 直接搬进浏览器。

原因：

• 项目目标是 Web 仿真产品，不是替代 LinuxCNC native GUI。
• 浏览器不能等同 native NML buffer、HAL shared memory 和 Linux realtime thread。
• 当前项目已有原生 HTML/CSS/ES module shell，继续复用成本最低。

后续影响：

• 文档和 UI 必须用 semanticBoundary 说明 Web 模拟边界。
• Python GUI runtime 一直保持 reference only。

ADR-003：gmoccapy_XYZAB 是 trivkins 参考 profile，不是 RTCP proof

状态：accepted

决策：

新增 gmoccapy-xyzab 时，必须标记为 trivkins coordinates=xyzab 的 gmoccapy 参考机型，不得标记为 RTCP/TCP 运动学 proof。

原因：

• gmoccapy_XYZAB.ini 的运动学是 trivkins。
• RTCP/TCP 运动学 proof 当前来自 xyzac-trt、xyzbc-trt 等 source-derived kinematics runtime。
• 把 XYZAB trivkins 误标为 RTCP 会污染验收标准。

后续影响：

• UI 可以显示 XYZAB 轴和 gmoccapy native 启动链路。
• RTCP badge 对该 profile 应显示 not TCP proof 或等价说明，除非后续接入真实 TCP 运动学。

ADR-004：NML/HAL 通信以诊断模型展示，控制仍走 Web store/task policy/runtime

状态：accepted

决策：

Web UI 显示 gmoccapy native 的 NML/HAL 通信路径，但按钮点击仍走现有 store.dispatch、linuxcnc-task-policy、runtime status snapshot。

原因：

• 当前浏览器应用没有 native NML buffer。
• 现有 store/task policy/runtime 已覆盖 RUN、MDI、JOG、HOME、task/HAL status loop。
• 诊断模型能帮助用户理解 native gmoccapy，但不会制造虚假的 native 连接。

后续影响：

• 每个按钮可显示 native equivalent command，例如 STATE_ON、MODE_AUTO、AUTO_RUN。
• 证据中必须区分 native reference 和 Web execution。

ADR-005：按钮图标不能替代按钮语义验收

状态：accepted

决策：

图标接入只算 UI 资产验收。按钮是否正确，必须通过 task policy、store、runtime 和 browser action 证据验收。

原因：

• working3 图标清单只说明图标来源、按钮名、tooltip 和信号线索。
• 真正的执行安全依赖 machine state、mode、interp state、home state、runtime readiness。
• 防止“看起来像 gmoccapy”但控制逻辑不正确。

后续影响：

• 每个核心按钮至少要有 icon 证据和 gate/action 证据。
• browser smoke 应断言 active icon 和 disabled reason。

ADR-006：G-code 执行互锁按三层保护建模

状态：accepted

决策：

RUN/MDI/JOG/HOME 等 gate 按 gmoccapy_XYZAB 文档中的三层保护建模：

1. UI 按钮敏感状态。
2. Action/task policy gate。
3. runtime 或 LinuxCNC source-derived boundary 最终校验。

原因：

• gmoccapy native 本身不是只靠一个按钮判断。
• LinuxCNC 后台会再次拒绝非法命令。
• Web 侧需要给用户可读 blocked reason，同时保持 runtime 校验。

后续影响：

• 测试必须覆盖非法状态和合法状态。
• Stop/Abort 的可用范围应大于 Run/MDI/Jog。

ADR-007：POSTGUI_HALFILE 必须作为顺序约束记录

状态：accepted

决策：

HAL/postgui 诊断中必须记录：gmoccapy_postgui.hal 只能在 gmoccapy.halcomp.ready() 后执行。

原因：

• postgui 文件引用 gmoccapy.* pins，普通 HALFILE 阶段这些 pins 尚不存在。
• 这是 gmoccapy native 启动顺序中的关键边界。
• Web 侧如果展示 HAL model，也要保留这个顺序概念。

后续影响：

• HAL model 中 postgui nets 独立于普通 HALFILE。
• 文档和 UI 不应把 postgui pin 连接混入实时 HAL 启动前阶段。

ADR-008：新增功能必须 evidence-first promotion

状态：accepted

决策：

任何新增功能不能只凭代码合入认定完成，必须补齐 05-acceptance-evidence.md 中对应证据。

原因：

• 当前项目已经形成 Node smoke、browser smoke、QA JSON、截图、PDF/DOCX 的证据链。
• gmoccapy_XYZAB 功能涉及 UI、profile、HAL、NML、gate、图标，多边界容易误判。
• 证据优先可以防止重复做和回归。

后续影响：

• 04-task-matrix.md 中没有证据的任务不得标为 done。
• 文档、代码、测试、报告必须一起更新。

ADR-009：gmoccapy_XYZAB profile 必须阻断 TCP/RTCP 切换

状态：accepted

决策：

gmoccapy-xyzab profile 虽然进入 profile selector，但必须标记 tcpCapable=false、rtcpProof=false，并在 UI 和 store 层阻断 tcp-* kinsType 或 SET_RTCP enabled。

原因：

• gmoccapy_XYZAB.ini 的真实运动学是 trivkins coordinates=xyzab。
• 当前 Web 项目的 source-derived TCP/RTCP proof 来自 xyzac-trt 和 xyzbc-trt。
• 如果 selector 允许 XYZAB reference profile 打开 TCP，会造成“参考配置可运行 RTCP”的误判。

后续影响：

• 侧栏 TCP 按钮在 gmoccapy-xyzab 下应 disabled，并给出 reference-only 原因。
• store.dispatch({ type: "SET_KINS_TYPE", kinsType: "tcp-..." }) 和 SET_RTCP enabled 必须保持防护，即使未来 UI 改动也不能绕过。
• 如果未来接入真实 XYZAB TCP kinematics，应新增独立 runtime proof 和测试后再修改该决策。