cnc_wams/web-rtcp-5axis-sim-plan/working1/03-implementation-steps.md

03 程序修复详细步骤

生成时间：2026-06-22

本文档面向实际编码人员，按问题给出具体修改步骤。执行前建议先创建修复分支。

git status --short
git switch -c fix/web-rtcp-5axis-working1

1. D1：自动挂接 LinuxCNC kinematics frame

Step 1.1 增加期望 frame source 状态

文件：

web-rtcp-5axis-sim-plan/app/src/state/store.js

在 initialState 增加字段：

desiredFrameSourceMode: "fixture-ui-only",

保留现有：

sourceMode
frameSourceMode

三者语义：

desiredFrameSourceMode: 用户/运行时希望使用的 frame 来源
frameSourceMode: 当前 rtcpFrame 实际来源
sourceMode: UI 总体展示来源，可继续跟当前 frame source 同步

Step 1.2 修改 ATTACH_KINEMATICS_RUNTIME

位置：

store.js -> case "ATTACH_KINEMATICS_RUNTIME"

runtime loaded 时设置：

desiredFrameSourceMode: "source-derived-kinematics-wasm",

runtime missing 时设置：

desiredFrameSourceMode: "fixture-ui-only",

不要只依赖 sourceMode / frameSourceMode。

Step 1.3 修改 buildFrameForState

当前逻辑大意：

const requestedSourceMode = state.frameSourceMode || state.sourceMode;
...
if (requestedSourceMode === "source-derived-kinematics-wasm") {
  if (runtime loaded && !async) {
    ...
  } else {
    sourceMode = "fixture-ui-only";
  }
}

建议改为：

const requestedSourceMode =
  state.desiredFrameSourceMode ||
  state.frameSourceMode ||
  state.sourceMode;

async runtime 已加载但尚未返回 frame 时，可以临时生成 fixture frame，但必须带上可诊断原因，不要覆盖 desired source。

Step 1.4 修改 setState 写回策略

当前 setState() 中：

sourceMode: frame.sourceMode,
frameSourceMode: frame.sourceMode,

建议改为：

sourceMode: frame.sourceMode,
frameSourceMode: frame.sourceMode,
desiredFrameSourceMode: next.desiredFrameSourceMode || frame.sourceMode,

关键点：不要因为临时 fixture frame 把 desiredFrameSourceMode 变成 fixture。

Step 1.5 修改 scheduleAsyncKinematicsRefresh

当前 guard 不应依赖已解析 frame source：

if (state.frameSourceMode !== "source-derived-kinematics-wasm") return null;

改为：

if (state.desiredFrameSourceMode !== "source-derived-kinematics-wasm") return null;
if (!state.kinematicsRuntime?.loaded) return null;
if (!isAsyncKinematicsRuntime(state.kinematicsRuntime)) return null;

如果当前 frame 已经 ready 且 activeLine/axisPose/kinsType 未变化，可继续跳过刷新。

Step 1.6 修改 refreshAsyncKinematicsFrame 成功写回

成功后确保：

sourceMode: "source-derived-kinematics-wasm",
frameSourceMode: "source-derived-kinematics-wasm",
desiredFrameSourceMode: "source-derived-kinematics-wasm",

失败时：

operatorMessage: `LinuxCNC kinematics refresh failed: ${error.message}`

并保留 retry 能力。

Step 1.7 修改 main.js 初始化顺序

文件：

web-rtcp-5axis-sim-plan/app/src/main.js

attachDefaultKinematicsRuntime() 已调用：

await store.refreshKinematicsFrame(...)

修复后保留该调用，并在 profile/INI 变更订阅中，runtime attach 完成后再次刷新：

await attachDefaultKinematicsRuntime(...)
await store.refreshKinematicsFrame({ operatorMessage: "..." })

注意避免无限刷新。可通过 asyncFrameRefreshSequence 或 readiness 状态判断。

Step 1.8 D1 测试

新增或更新测试：

web-rtcp-5axis-sim-plan/tests/browser/gmoccapy_shell_smoke.html

或新增：

web-rtcp-5axis-sim-plan/tests/browser/kinematics_auto_refresh_smoke.html

断言：

await waitUntil(() => window.webRtcp5AxisSimulation.getState().sourceMode === "source-derived-kinematics-wasm")
assertText('[data-rtcp-diagnostic="boundary"]', 'linuxcnc_kinematics_wasm_c_abi')
assertText('[data-rtcp-diagnostic="kinematics-ready"]', 'ready')

2. D2：修复 3D 预览可见性

Step 2.1 修复 updateToolpathPreview 未定义变量

文件：

web-rtcp-5axis-sim-plan/app/src/visualization/five-axis-scene.js

在 updateToolpathPreview(preview, state) 中补齐：

const toolPosition = executionToolPosition(state, previewPoints);
const fitPoints = collectFitPoints(previewPoints, executedPoints, currentSegmentPoints, toolPosition);
const fitKey = [
  previewPoints.length,
  executedPoints.length,
  currentSegmentPoints.length,
  previewSourceMode(state),
  state.programExecutionMotionIndex || 0,
  state.programExecutionSampleIndex || 0,
].join(":");

确保 updateToolExecutionMarker() 使用同一个 toolPosition。

Step 2.2 增加常驻机床参考模型

新增函数：

function createMachineReferenceModel() { ... }
function updateMachineReferenceModel(preview, state) { ... }

推荐对象：

grid/table base: dark gray plane/box
X axis: red line
Y axis: green line
Z axis: blue line
rotary ring: cyan/yellow ring
tool holder: small cylinder/cone
TCP marker: existing sphere

在 createScene() 中：

const machineModel = createMachineReferenceModel();
scene.add(machineModel.root);

在 preview 对象中保存：

machineModel

在 updateToolpathPreview() 中：

updateMachineReferenceModel(preview, state);

Step 2.3 提高 fallback 可见性

在 renderFallbackPreview() 中，路径为空也要绘制：

工作台矩形
XYZ 坐标轴
旋转中心
TCP 点

要求颜色和尺寸足够明显，避免黑底上不可见。

Step 2.4 强化 canvas dataset

exposePreviewDataset() 已存在，修复后确保任意路径都稳定输出：

data-three-ready="true"
data-three-renderer
data-three-scene-objects
data-three-path-points
data-three-tool-execution-marker

如果 fallback：

data-three-fallback-reason

如果 WebGL：

data-three-renderer="webgl"

Step 2.5 D2 测试

新增 pixel 检查：

const stats = canvasPixelStats(canvas)
assert(stats.nonBlackRatio > 0.02)
assert(stats.averageLuminance > 5)

同时检查：

Number(canvas.dataset.threeSceneObjects) > 0
canvas.dataset.threeReady === "true"

建议覆盖 desktop 和 mobile viewport。

3. D3：修复 HOME/JOG 坐标连续性

Step 3.1 记录 pending JOG 上下文

文件：

web-rtcp-5axis-sim-plan/app/src/state/store.js

在 initialState 增加：

pendingJogCommand: null,

在 case "JOG" 的 task/HAL runtime 分支，发送命令前记录：

setState({
  pendingJogCommand: {
    axis,
    direction,
    increment,
    basePose: state.axisPose,
    createdAtLine: state.activeLine,
  },
  operatorMessage: `task/HAL jog ${axis.toUpperCase()} ...`,
})

注意现有代码直接调用 runTaskHalCommandSequence()，需要避免两次 setState 引发顺序混乱。可把 pending context 作为 runTaskHalCommandSequence() 的 options 传入，最终在 command started patch 中写入。

Step 3.2 给 task/HAL status 增加坐标系元数据

文件：

web-rtcp-5axis-sim-plan/app/src/runtime/linuxcnc-task-hal-runtime.js

在 ui 对象中增加：

axisPoseFrame: "task-local",

如果 runtime 能确定是 work pose，则写：

axisPoseFrame: "work",

如果能计算增量，增加：

axisPoseDelta: { x, y, z, a, b, c }

短期不能准确判断时，不要伪装成 work。

Step 3.3 修改 applyTaskHalStatusPatch

当前：

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

改为单独函数：

const axisPose = resolveTaskHalAxisPose(state, status);

建议实现：

function resolveTaskHalAxisPose(state, status) {
  const ui = status?.ui || {};
  if (ui.axisPoseFrame === "work") {
    return clampAxisPoseToProfile({ ...state.axisPose, ...ui.axisPose }, state.profile);
  }

  if (ui.axisPoseDelta) {
    return addAxisDelta(state.axisPose, ui.axisPoseDelta, state.profile);
  }

  if (state.pendingJogCommand && isJogStatus(status)) {
    const { axis, direction, increment, basePose } = state.pendingJogCommand;
    return clampAxisPoseToProfile({
      ...basePose,
      [axis]: Number(basePose[axis] || 0) + direction * increment,
    }, state.profile);
  }

  if (!ui.axisPoseFrame && wouldResetNonZeroPoseToLocalZero(state.axisPose, ui.axisPose)) {
    return state.axisPose;
  }

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

Step 3.4 清理 pending JOG

TASK_HAL_STATUS_APPLIED 后，如果使用了 pending JOG：

pendingJogCommand: null

如果 command failed：

pendingJogCommand: null

Step 3.5 HOME 同步

HOME 成功后，UI 和 task/HAL runtime 必须同一坐标基准。短期可在 HOME fallback patch 中明确：

axisPose: initialAxisPose

task/HAL HOME status 如果返回局部原点，不能覆盖 initialAxisPose，除非 status 标记 axisPoseFrame="work"。

Step 3.6 D3 测试

新增测试步骤：

power on
manual
home
capture X/Y/Z
jog X+
assert X === previousX + jogIncrement
assert Y/Z unchanged
jog Y-
assert Y === previousY - jogIncrement
assert X/Z unchanged

同时验证 DRO 文本：

document.querySelector('[data-region="dro"]').textContent

4. 本地验证命令

建议按顺序执行：

npm --prefix web-rtcp-5axis-sim-plan/app run build
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
node web-rtcp-5axis-sim-plan/tests/node/verify_linuxcnc_task_hal_runtime.mjs

如果项目已有 browser smoke：

web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_shell_browser.sh

修复后再执行 QA 站点测试脚本或新增等价本地测试。