cnc_wams/web-rtcp-5axis-sim-plan/working1/01-problem-review.md

01 问题复盘

生成时间：2026-06-22

1. 输入证据

测试报告：

/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/web-rtcp-5axis-site-test-report-2026-06-22.docx

原始自动化结果：

/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/site-test-report.json

截图目录：

/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/screenshots/

2. D1：RTCP/运动学边界未自动挂接

现象

页面稳定加载后，内部运行时已经加载 LinuxCNC kinematics worker：

kinematicsRuntimeReadiness.loaded=true
semanticBoundary=linuxcnc_kinematics_wasm_c_abi
sourceMode=source-derived-kinematics-wasm

但 RTCP frame 仍显示：

state.sourceMode=fixture-ui-only
state.frameSourceMode=fixture-ui-only
frameBoundary=fixture_frame_ui_plumbing_not_linuxcnc_kinematics_proof

手动执行：

await window.webRtcp5AxisSimulation.refreshKinematicsFrame()

后可立即切换为：

state.sourceMode=source-derived-kinematics-wasm
frameBoundary=linuxcnc_kinematics_wasm_c_abi

影响

• 首屏 RTCP/TCP 姿态并非自动来自 LinuxCNC source-derived kinematics。
• 界面 Boundary ready 可能显示 ready，但 RTCP frame 仍在 fixture 边界，诊断信息不一致。
• 用户和测试脚本都会误判当前仿真语义边界。

涉及代码

app/src/main.js
  attachDefaultKinematicsRuntime()

app/src/state/store.js
  ATTACH_KINEMATICS_RUNTIME
  setState()
  buildFrameForState()
  scheduleAsyncKinematicsRefresh()
  refreshAsyncKinematicsFrame()

app/src/runtime/rtcp-frame.js
  buildRtcpFrame()

初步根因

当前 setState() 在异步 worker kinematics runtime 已加载但 frame 尚未刷新时，会通过 buildFrameForState() 生成 fixture frame；随后又把：

frameSourceMode: frame.sourceMode

写回 state。这样本来期望进入 LinuxCNC kinematics 的请求状态被 fixture 结果覆盖。

scheduleAsyncKinematicsRefresh() 又依赖：

state.frameSourceMode === "source-derived-kinematics-wasm"

当 frameSourceMode 已被覆盖成 fixture-ui-only 后，自动刷新不再触发。手动调用 refreshKinematicsFrame() 能成功，说明底层 worker 能用，问题在自动刷新状态机。

3. D2：3D 预览不可见

现象

首屏、程序运行、本地 G-code 导入、Audit 后截图中，左侧预览区均为黑底，未观察到五轴机床、刀具或刀路可见对象。

相关截图：

01-home.png
04-run-state.png
05-local-program-opened.png
06-after-audit.png

影响

• 五轴/RTCP 仿真最重要的视觉反馈缺失。
• 用户无法通过界面验证 TCP 点、刀轴、程序轨迹和执行轨迹。
• 不满足项目文档中“Three.js 视口非空，能显示机床、刀具、刀路”的第一版完成定义。

涉及代码

app/src/visualization/five-axis-scene.js
  renderFiveAxisScene()
  createScene()
  updateToolpathPreview()
  renderFallbackPreview()
  exposePreviewDataset()

app/src/ui/gmoccapy-shell.js
  renderPreview()

app/src/styles/gmoccapy.css
  preview/canvas 尺寸和布局

初步根因

需要重点检查两类问题：

1. updateToolpathPreview() 内部使用了 fitPoints、fitKey，但当前函数片段中未看到局部定义。若实际执行进入 WebGL 分支，可能触发运行时异常并降级或中断渲染。
2. 当前 WebGL scene 只添加了路径线、tool marker、tool axis，没有明确的机床基准模型、工作台、旋转轴、坐标轴等常驻对象。即使路径为空或颜色很暗，用户也应看到基础机床对象。

另外，fallback 分支必须在无 WebGL 或 WebGL 初始化失败时仍绘制明显对象，而不是仅写一个很小的文字提示。

4. D3：HOME 后 JOG 坐标连续性异常

现象

稳定复核结果：

after HOME:
  X=43, Y=-32.15, Z=-11.306

after JOG X+:
  X=1, Y=0, Z=0

after JOG Y-:
  X=1, Y=-1, Z=0

影响

• DRO 中的手动移动不连续。
• 操作员会误以为机床从 HOME 坐标突然跳到任务/HAL 局部原点。
• 会话恢复、手动定位、RTCP 视觉反馈都可能被错误坐标污染。

涉及代码

app/src/state/store.js
  HOME
  JOG
  TASK_HAL_STATUS_APPLIED
  applyTaskHalStatusPatch()

app/src/runtime/linuxcnc-task-hal-runtime.js
  normalize/readStatus 输出的 ui.axisPose

app/src/state/linuxcnc-task-policy.js
  JOG/HOME gate

初步根因

当前启用 task/HAL runtime 后，JOG 走 task/HAL command path。applyTaskHalStatusPatch() 会把 runtime status 中的 ui.axisPose 直接覆盖 UI state：

const axisPose = clampAxisPoseToProfile({
  ...state.axisPose,
  ...ui.axisPose,
}, state.profile);

但 task/HAL runtime 返回的 ui.axisPose 看起来是 task-local 或 motion-local 坐标，初始值从 0 开始，并非当前 UI DRO/HOME 坐标系。因此 JOG 后坐标被另一套坐标系覆盖。

5. 非缺陷说明

以下现象在复核后不作为缺陷记录：

1. 页面初始数秒内 Task/HAL 和 machine-file staging 从 pending 过渡到 ready/staged，属于异步启动暂态。
2. M428/M429/M430 经稳定态复核均可执行：

M428 -> kins=tcp-xyzac, rtcp=on
M429 -> kins=identity, rtcp=off
M430 -> kins=userk, rtcp=off

3. Open 本地 G-code 使用 programSource=operator-file，这是当前实现命名，不是功能失败。