489 lines
9.9 KiB
Markdown
489 lines
9.9 KiB
Markdown
# 03 程序修复详细步骤
|
||
|
||
生成时间：2026-06-22
|
||
|
||
本文档面向实际编码人员，按问题给出具体修改步骤。执行前建议先创建修复分支。
|
||
|
||
```bash
|
||
git status --short
|
||
git switch -c fix/web-rtcp-5axis-working1
|
||
```
|
||
|
||
## 1. D1：自动挂接 LinuxCNC kinematics frame
|
||
|
||
### Step 1.1 增加期望 frame source 状态
|
||
|
||
文件：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/app/src/state/store.js
|
||
```
|
||
|
||
在 `initialState` 增加字段：
|
||
|
||
```js
|
||
desiredFrameSourceMode: "fixture-ui-only",
|
||
```
|
||
|
||
保留现有：
|
||
|
||
```js
|
||
sourceMode
|
||
frameSourceMode
|
||
```
|
||
|
||
三者语义：
|
||
|
||
```text
|
||
desiredFrameSourceMode: 用户/运行时希望使用的 frame 来源
|
||
frameSourceMode: 当前 rtcpFrame 实际来源
|
||
sourceMode: UI 总体展示来源，可继续跟当前 frame source 同步
|
||
```
|
||
|
||
### Step 1.2 修改 ATTACH_KINEMATICS_RUNTIME
|
||
|
||
位置：
|
||
|
||
```text
|
||
store.js -> case "ATTACH_KINEMATICS_RUNTIME"
|
||
```
|
||
|
||
runtime loaded 时设置：
|
||
|
||
```js
|
||
desiredFrameSourceMode: "source-derived-kinematics-wasm",
|
||
```
|
||
|
||
runtime missing 时设置：
|
||
|
||
```js
|
||
desiredFrameSourceMode: "fixture-ui-only",
|
||
```
|
||
|
||
不要只依赖 `sourceMode` / `frameSourceMode`。
|
||
|
||
### Step 1.3 修改 buildFrameForState
|
||
|
||
当前逻辑大意：
|
||
|
||
```js
|
||
const requestedSourceMode = state.frameSourceMode || state.sourceMode;
|
||
...
|
||
if (requestedSourceMode === "source-derived-kinematics-wasm") {
|
||
if (runtime loaded && !async) {
|
||
...
|
||
} else {
|
||
sourceMode = "fixture-ui-only";
|
||
}
|
||
}
|
||
```
|
||
|
||
建议改为：
|
||
|
||
```js
|
||
const requestedSourceMode =
|
||
state.desiredFrameSourceMode ||
|
||
state.frameSourceMode ||
|
||
state.sourceMode;
|
||
```
|
||
|
||
async runtime 已加载但尚未返回 frame 时，可以临时生成 fixture frame，但必须带上可诊断原因，不要覆盖 desired source。
|
||
|
||
### Step 1.4 修改 setState 写回策略
|
||
|
||
当前 `setState()` 中：
|
||
|
||
```js
|
||
sourceMode: frame.sourceMode,
|
||
frameSourceMode: frame.sourceMode,
|
||
```
|
||
|
||
建议改为：
|
||
|
||
```js
|
||
sourceMode: frame.sourceMode,
|
||
frameSourceMode: frame.sourceMode,
|
||
desiredFrameSourceMode: next.desiredFrameSourceMode || frame.sourceMode,
|
||
```
|
||
|
||
关键点：不要因为临时 fixture frame 把 `desiredFrameSourceMode` 变成 fixture。
|
||
|
||
### Step 1.5 修改 scheduleAsyncKinematicsRefresh
|
||
|
||
当前 guard 不应依赖已解析 frame source：
|
||
|
||
```js
|
||
if (state.frameSourceMode !== "source-derived-kinematics-wasm") return null;
|
||
```
|
||
|
||
改为：
|
||
|
||
```js
|
||
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 成功写回
|
||
|
||
成功后确保：
|
||
|
||
```js
|
||
sourceMode: "source-derived-kinematics-wasm",
|
||
frameSourceMode: "source-derived-kinematics-wasm",
|
||
desiredFrameSourceMode: "source-derived-kinematics-wasm",
|
||
```
|
||
|
||
失败时：
|
||
|
||
```js
|
||
operatorMessage: `LinuxCNC kinematics refresh failed: ${error.message}`
|
||
```
|
||
|
||
并保留 retry 能力。
|
||
|
||
### Step 1.7 修改 main.js 初始化顺序
|
||
|
||
文件：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/app/src/main.js
|
||
```
|
||
|
||
`attachDefaultKinematicsRuntime()` 已调用：
|
||
|
||
```js
|
||
await store.refreshKinematicsFrame(...)
|
||
```
|
||
|
||
修复后保留该调用，并在 profile/INI 变更订阅中，runtime attach 完成后再次刷新：
|
||
|
||
```js
|
||
await attachDefaultKinematicsRuntime(...)
|
||
await store.refreshKinematicsFrame({ operatorMessage: "..." })
|
||
```
|
||
|
||
注意避免无限刷新。可通过 `asyncFrameRefreshSequence` 或 readiness 状态判断。
|
||
|
||
### Step 1.8 D1 测试
|
||
|
||
新增或更新测试：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/tests/browser/gmoccapy_shell_smoke.html
|
||
```
|
||
|
||
或新增：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/tests/browser/kinematics_auto_refresh_smoke.html
|
||
```
|
||
|
||
断言：
|
||
|
||
```js
|
||
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 未定义变量
|
||
|
||
文件：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/app/src/visualization/five-axis-scene.js
|
||
```
|
||
|
||
在 `updateToolpathPreview(preview, state)` 中补齐：
|
||
|
||
```js
|
||
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 增加常驻机床参考模型
|
||
|
||
新增函数：
|
||
|
||
```js
|
||
function createMachineReferenceModel() { ... }
|
||
function updateMachineReferenceModel(preview, state) { ... }
|
||
```
|
||
|
||
推荐对象：
|
||
|
||
```text
|
||
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()` 中：
|
||
|
||
```js
|
||
const machineModel = createMachineReferenceModel();
|
||
scene.add(machineModel.root);
|
||
```
|
||
|
||
在 preview 对象中保存：
|
||
|
||
```js
|
||
machineModel
|
||
```
|
||
|
||
在 `updateToolpathPreview()` 中：
|
||
|
||
```js
|
||
updateMachineReferenceModel(preview, state);
|
||
```
|
||
|
||
### Step 2.3 提高 fallback 可见性
|
||
|
||
在 `renderFallbackPreview()` 中，路径为空也要绘制：
|
||
|
||
```text
|
||
工作台矩形
|
||
XYZ 坐标轴
|
||
旋转中心
|
||
TCP 点
|
||
```
|
||
|
||
要求颜色和尺寸足够明显，避免黑底上不可见。
|
||
|
||
### Step 2.4 强化 canvas dataset
|
||
|
||
`exposePreviewDataset()` 已存在，修复后确保任意路径都稳定输出：
|
||
|
||
```text
|
||
data-three-ready="true"
|
||
data-three-renderer
|
||
data-three-scene-objects
|
||
data-three-path-points
|
||
data-three-tool-execution-marker
|
||
```
|
||
|
||
如果 fallback：
|
||
|
||
```text
|
||
data-three-fallback-reason
|
||
```
|
||
|
||
如果 WebGL：
|
||
|
||
```text
|
||
data-three-renderer="webgl"
|
||
```
|
||
|
||
### Step 2.5 D2 测试
|
||
|
||
新增 pixel 检查：
|
||
|
||
```js
|
||
const stats = canvasPixelStats(canvas)
|
||
assert(stats.nonBlackRatio > 0.02)
|
||
assert(stats.averageLuminance > 5)
|
||
```
|
||
|
||
同时检查：
|
||
|
||
```js
|
||
Number(canvas.dataset.threeSceneObjects) > 0
|
||
canvas.dataset.threeReady === "true"
|
||
```
|
||
|
||
建议覆盖 desktop 和 mobile viewport。
|
||
|
||
## 3. D3：修复 HOME/JOG 坐标连续性
|
||
|
||
### Step 3.1 记录 pending JOG 上下文
|
||
|
||
文件：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/app/src/state/store.js
|
||
```
|
||
|
||
在 `initialState` 增加：
|
||
|
||
```js
|
||
pendingJogCommand: null,
|
||
```
|
||
|
||
在 `case "JOG"` 的 task/HAL runtime 分支，发送命令前记录：
|
||
|
||
```js
|
||
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 增加坐标系元数据
|
||
|
||
文件：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/app/src/runtime/linuxcnc-task-hal-runtime.js
|
||
```
|
||
|
||
在 `ui` 对象中增加：
|
||
|
||
```js
|
||
axisPoseFrame: "task-local",
|
||
```
|
||
|
||
如果 runtime 能确定是 work pose，则写：
|
||
|
||
```js
|
||
axisPoseFrame: "work",
|
||
```
|
||
|
||
如果能计算增量，增加：
|
||
|
||
```js
|
||
axisPoseDelta: { x, y, z, a, b, c }
|
||
```
|
||
|
||
短期不能准确判断时，不要伪装成 work。
|
||
|
||
### Step 3.3 修改 applyTaskHalStatusPatch
|
||
|
||
当前：
|
||
|
||
```js
|
||
const axisPose = clampAxisPoseToProfile({
|
||
...state.axisPose,
|
||
...ui.axisPose,
|
||
}, state.profile);
|
||
```
|
||
|
||
改为单独函数：
|
||
|
||
```js
|
||
const axisPose = resolveTaskHalAxisPose(state, status);
|
||
```
|
||
|
||
建议实现：
|
||
|
||
```js
|
||
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：
|
||
|
||
```js
|
||
pendingJogCommand: null
|
||
```
|
||
|
||
如果 command failed：
|
||
|
||
```js
|
||
pendingJogCommand: null
|
||
```
|
||
|
||
### Step 3.5 HOME 同步
|
||
|
||
HOME 成功后，UI 和 task/HAL runtime 必须同一坐标基准。短期可在 HOME fallback patch 中明确：
|
||
|
||
```js
|
||
axisPose: initialAxisPose
|
||
```
|
||
|
||
task/HAL HOME status 如果返回局部原点，不能覆盖 `initialAxisPose`，除非 status 标记 `axisPoseFrame="work"`。
|
||
|
||
### Step 3.6 D3 测试
|
||
|
||
新增测试步骤：
|
||
|
||
```js
|
||
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 文本：
|
||
|
||
```js
|
||
document.querySelector('[data-region="dro"]').textContent
|
||
```
|
||
|
||
## 4. 本地验证命令
|
||
|
||
建议按顺序执行：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_shell_browser.sh
|
||
```
|
||
|
||
修复后再执行 QA 站点测试脚本或新增等价本地测试。
|
||
|