完善五轴 RTCP 仿真与验证资料

work/working7/06-决策记录.md

@@ -0,0 +1,135 @@
+# 06 决策记录
+
+生成日期：2026-06-27
+
+## W7-D01 以操作手册作为测试拆解主线
+
+决定：本轮测试功能按《Web RTCP 五轴联动数控系统仿真界面操作手册》的章节拆分，不按代码目录或历史工作目录重新命名功能。
+
+原因：
+
+- 手册是用户指定输入。
+- 手册章节直接对应操作者工作流，便于后续人工测试、截图和报告复用。
+- 任务矩阵可以防止后续再次重复拆分主界面、开机、AUTO、MDI 等相同功能。
+
+## W7-D02 R01 阶段不修改业务代码
+
+决定：W7-R01 只新增 `work/working7` 文档并执行现有验证命令，不改 `web-rtcp-5axis-sim-plan/app` 或测试脚本。
+
+原因：
+
+- 用户要求是“测试方法写入 working7”，不是新增功能或修复缺陷。
+- 当前 build、Node smoke、browser smoke 均已通过，没有发现必须在本轮修复的失败。
+- 工作区已有未提交改动，避免混入无关业务变更。
+
+## W7-D03 现有自动化作为基线证据
+
+决定：以 `npm run build`、`npm run smoke:node`、`npm run smoke` 作为本轮基线验收命令。
+
+原因：
+
+- 这些命令是项目 `app/package.json` 中已有正式入口。
+- Node smoke 覆盖 runtime、policy、session、RTCP、gmoccapy HAL 和 gate。
+- 浏览器 smoke 覆盖真实 DOM、按钮视觉状态、canvas 和 dist 页面。
+
+## W7-D04 人工手册步骤不等同于全部已截图验收
+
+决定：对手册中的人工流程，本轮写清测试方法；只有已跑命令和既有 QA 报告作为当前证据。
+
+原因：
+
+- 本轮没有重新生成逐步骤截图/PDF。
+- 直接把“方法已写入”说成“全部人工截图已验收”会造成证据口径不准确。
+- 后续如需要新截图/PDF，可按 `02-程序测试开发完善详细步骤.md` 和 `04-任务矩阵.md` 继续推进。
+
+## W7-D05 保留 Web 仿真安全边界
+
+决定：所有 POWER、HOME、RUN、JOG、MDI、主轴和冷却测试均按 Web 仿真状态验收，不声明真实机床控制能力。
+
+原因：
+
+- 项目 README 和操作手册都说明浏览器不替代 LinuxCNC 实时内核。
+- Node smoke 输出也明确 `hardware_drive=0`、`host_realtime_kernel=0`、`promotion_scope=web_simulation_only`。
+- 这是验收文档中必须保留的安全边界。
+
+## W7-D06 区分 RTCP proof 和 gmoccapy reference profile
+
+决定：`xyzac-trt`、`xyzbc-trt` 用于 RTCP/TCP source-derived WASM 证明；`gmoccapy-xyzab` 只作为 `trivkins` reference-only profile 测试 gmoccapy 操作和 HAL 语义。
+
+原因：
+
+- `gmoccapy-xyzab` 来自 `gmoccapy_XYZAB.ini`，使用 `trivkins coordinates=xyzab`。
+- 操作手册也说明 reference-only profile 可能禁用 TCP 切换并显示原因。
+- 混淆这两个边界会导致错误验收结论。
+
+## W7-D07 后续新增证据必须有编号
+
+决定：后续新增截图、PDF、JSON 或脚本时，先在任务矩阵新增 `W7-Txx` 编号，再写入证据。
+
+原因：
+
+- 可避免“同一功能多轮重复测试但状态不清”。
+- 可让 README、推进台账、证据文件保持一致。
+- 便于按 job_id、report_id、截图路径追溯。
+
+## W7-D08 新增 working7 专项 QA 脚本补齐方法就绪项
+
+决定：新增 `qa/web-rtcp-5axis-site-test/capture-working7-manual-flow-evidence.mjs`，用本地静态服务和 headless Chrome 生成 JSON、PDF 和截图证据。
+
+原因：
+
+- W7-R01 已完成手册测试方法归档，但 W7-T06、W7-T08、W7-T09、W7-T11 仍是 `method-ready`。
+- 既有 QA 报告可以引用，但不是按 working7 手册流程和本轮日期生成。
+- 专项脚本可重复执行，能把 POWER/HOME、AUTO/MANUAL、JOG、MDI、倍率/HAL、主轴/冷却、Save/Restore 和诊断证据集中到同一个 report_id。
+- 该脚本本身只增加 QA 证据；专项证据基于当前源码执行，当前源码包含前序 AUTO/MANUAL 模式切换与 titlebar 稳定性修正。
+
+## W7-D09 working7 证据引用当前源码状态
+
+决定：working7 的最终验收记录引用当前工作区源码状态，不把前序 `store.js`、`gmoccapy-shell.js` 和浏览器 smoke 修正错误归入 working7 新增业务功能。
+
+原因：
+
+- `store.js` 修正确保 Task/HAL 模式切换时保留已上电、已回零和目标模式状态，这是 AUTO/MANUAL 手册流程成立的前置稳定性修正。
+- `gmoccapy-shell.js` 修正确保 titlebar profile selector 和当前行节点在普通状态刷新时不被重挂载，便于浏览器自动化稳定复测。
+- `gmoccapy_shell_smoke.html` 已增加对应回归断言，working7 专项 QA 在这些前序修正之上生成 JSON/PDF/截图证据。
+- working7 本轮收尾动作是证据复核、报告重跑和文档同步，不再扩大业务运行逻辑范围。
+
+## W7-D10 使用全量 evidence 脚本作为最终验收主证据
+
+决定：新增 `capture-working7-full-functional-evidence.mjs`，作为 W7-T17 的最终主证据；旧的 `capture-working7-manual-flow-evidence.mjs` 保留为手册流程交叉证据。
+
+原因：
+
+- 用户要求验证“所有按钮、程序执行、刀具预览、实时路径、G-code 执行过程、机床轴值、仿真界面右侧按钮”，旧脚本只覆盖手册主流程，不足以证明全量按钮矩阵。
+- 全量脚本记录 73 个实际动作、19 张截图、JSON、Markdown 和 PDF，能按 job_id/report_id 复查。
+- 旧脚本继续保留，可以防止全量脚本过宽时遗漏手册主线。
+
+## W7-D11 Task/HAL 下 JOG/MDI 需要保留 Web 可视执行结果
+
+决定：在 Task/HAL 状态应用链路中增加 `preserveAxisPose` 和 `preserveMachine`，JOG/MDI 发送 Task/HAL 命令后保留 Web 侧 axisPose、DRO、mode 和 idle 状态。
+
+原因：
+
+- Task/HAL runtime 当前主要提供 simulation feedback，不一定会在单次 JOG/MDI 命令后返回 Web UI 需要的最终轴值。
+- 用户验证的是 Web 仿真界面的可见执行过程，点击 JOG/MDI 后 DRO 和 axisPose 必须稳定反映操作者刚执行的动作。
+- 保留字段只作用于明确的 Web 命令回写，不改变自动程序运行时的 Task/HAL feedback 主链路。
+
+## W7-D12 初始主轴、冷却和速度采用安全关闭状态
+
+决定：首屏初始状态改为主轴停止、冷却关闭、当前速度为 0。
+
+原因：
+
+- 未上电状态下主轴/冷却显示 active 会和 gate 语义冲突。
+- 安全关闭状态更符合机床 UI 的默认预期。
+- 浏览器 smoke 和 working7 evidence 均已更新为该语义。
+
+## W7-D13 资源路径 404 不作为可接受噪声保留
+
+决定：修正 favicon、INI loader、machine-file staging、dist 复制和 reference-only kinematics 跳过逻辑，使最终 evidence 报告中 console/network/page error 均为 0。
+
+原因：
+
+- 404 fallback 虽不一定影响功能，但会降低验收报告可信度。
+- source 模式和 dist 模式应各自使用明确有效路径，不依赖失败后回退。
+- `gmoccapy-xyzab` 是 reference-only profile，不应尝试 source-derived kinematics runtime。