cnc_wams/web-rtcp-5axis-sim-plan/working1/working1-log-2026-06-22-d1-d2-d3.md

working1 修复执行记录 D1-D2-D3

生成时间：2026-06-22

Batch

Batch: working1-implementation-d1-d2-d3
Date: 2026-06-22
Owner: Codex
Problem IDs: D1, D2, D3
Branch: current worktree
Commit: not committed

1. 修复目标

D1: kinematics worker ready 后，页面自动保持 LinuxCNC source-derived kinematics frame，不被临时 fixture frame 永久覆盖。
D2: 首屏和路径清空后仍显示可见五轴参考机床、坐标轴、旋转轴、刀具/TCP；canvas dataset 和像素测试可验证。
D3: HOME 后执行 task/HAL JOG，DRO/work pose 保持连续增量，不被 task-local/local-zero 轴位覆盖。

2. 修改文件

文件	修改内容	原因
app/src/state/store.js	增加 desiredFrameSourceMode、pendingJogCommand；调整 async kinematics refresh；新增 resolveTaskHalAxisPose()	分离“期望 frame source”和“当前 frame source”；保护 HOME 后 JOG 坐标连续性
app/src/main.js	profile kinematics runtime attach 完成后再次调用 refreshKinematicsFrame()	满足 profile/INI 变更后的自动 frame 刷新要求
app/src/runtime/linuxcnc-task-hal-runtime.js	ui.axisPoseFrame 标记 JOG 为 task-local，非 JOG 为 work	让 store 能区分 task/HAL 轴位坐标系
app/src/visualization/five-axis-scene.js	新增 WebGL 五轴参考机床模型和 2D fallback 参考绘制；路径清空时仍显示 TCP	修复 3D 预览黑屏/不可见和 fallback 信息不足
tests/browser/gmoccapy_shell_smoke.html	更新 reference model dataset 断言；新增 canvas pixel stats 检查	防止只通过 DOM dataset 误判可见性
tests/node/verify_linuxcnc_task_hal_runtime.mjs	增加 HOME 后 JOG X+/Y- 连续性断言	覆盖 D3 复现路径

3. 关键实现说明

状态字段变化:
- desiredFrameSourceMode: 保留用户/运行时希望的 frame source。
- pendingJogCommand: 记录 task/HAL JOG 的 axis、direction、increment、basePose。

核心函数变化:
- buildFrameForState(): 优先读取 desiredFrameSourceMode。
- scheduleAsyncKinematicsRefresh(): 以 desiredFrameSourceMode + runtime loaded 作为刷新条件。
- refreshAsyncKinematicsFrame(): 成功后写回 source/frame/desired 均为 source-derived-kinematics-wasm，失败显示 operatorMessage 并保留重试能力。
- resolveTaskHalAxisPose(): work pose 直接合并，axis delta 累加，pending JOG 用 basePose + increment。

UI/可视化变化:
- WebGL scene 增加 table/base、XYZ axis、A/C rotary ring、tool holder。
- 2D fallback 始终绘制工作台、XYZ 轴、旋转中心、TCP 点。
- canvas dataset 输出 machine-reference-and-toolpath / webgl-five-axis-reference。

4. LinuxCNC/项目溯源

参考项目文档:
- working1/03-implementation-steps.md
- working1/04-traceability-matrix.md
- docs/traceability-matrix.md

参考 LinuxCNC 边界:
- kinematics frame 仍来自 LinuxCNC kinematics WASM C ABI。
- task/HAL JOG 仍通过 EMC_JOG_INCR 模拟 runtime 执行；UI 只处理坐标系归并，不重写 CNC 运动语义。
- Three.js 只消费 runtime frame/canonical motion/task-HAL feedback，不生成 G-code 或 CNC 语义。

5. 测试记录

5.1 已通过命令

npm --prefix web-rtcp-5axis-sim-plan/app run build
node web-rtcp-5axis-sim-plan/tests/node/verify_linuxcnc_task_hal_runtime.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_rtcp_store.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_five_axis_session.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_linuxcnc_kinematics_runtime.mjs
bash web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_shell_browser.sh
bash web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_dist_browser.sh

5.2 关键输出

gmoccapy_static_build=ok
linuxcnc_task_hal_runtime_smoke=ok
rtcp_store_smoke=ok
five_axis_session_smoke=ok
linuxcnc_kinematics_runtime_smoke=ok
gmoccapy_shell_smoke=ok
gmoccapy_dist_smoke=ok

5.3 未通过/阻塞命令

npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node

结果：

前置 kinematics/interpreter/INI/task-HAL 均通过。
失败位置: verify_native_task_hal_audit.mjs -> wasm-port/tests/native/verify_task_hal_phase0.sh
失败原因: verify_task_hal_source_manifest.sh 返回非零，manifest ready=0。
证据: wasm-port/build/task-hal/verify_task_hal_source_manifest.stdout.log
关键字段:
- task_hal_reference_source_ready=0
- task_hal_vendor_source_ready=0
- task_hal_missing_reference_source_count=20

该失败属于 native LinuxCNC reference source/probe 前置条件，不是本轮 Web D1/D2/D3 代码回归。

6. 回归范围

功能	是否回归	结果
D1 kinematics auto refresh	是	PASS
D2 preview visible	是	PASS
D3 jog continuity	是	PASS
POWER/E-STOP/RESET	是	PASS via browser smoke
MDI M428/M429/M430	是	PASS via browser/node smoke
Load/Run/Step/Stop	是	PASS via browser smoke
Save/Restore Session	是	PASS via browser/node smoke
Native source manifest/probe	是	BLOCKED: missing native reference sources

7. 剩余风险

1. native task/HAL source manifest 仍未 ready，缺少 20 个 native reference source，完整 smoke:node 不能全绿。
2. WebGL reference model 已通过 smoke，但仍建议后续保留人工截图复核首屏和 clear-preview 后视觉效果。
3. task/HAL axisPoseFrame 当前按 JOG/non-JOG 推断；长期方案仍应由 runtime 输出更细的 work/task-local/axisPoseDelta 元数据。

8. 下一步

Next:
- 补齐或恢复 wasm-port/tools/task-hal-source-manifest.txt 对应的 native LinuxCNC reference sources。
- native source manifest ready 后重跑 npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node。
- 部署到 https://82.156.24.101:8092/ 后重跑 QA 站点测试，更新 Word 测试报告。

Blockers:
- wasm-port/build/task-hal/verify_task_hal_source_manifest.stdout.log 显示 native reference source 缺失。