# 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 和测试后再修改该决策。