完善 gmoccapy XYZAB 参考功能

work/working4/06-decision-records.md

@@ -0,0 +1,182 @@
+# 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 和测试后再修改该决策。