# 01 问题复盘

生成时间：2026-06-22

## 1. 输入证据

测试报告：

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

原始自动化结果：

```text
/home/mes123456/cnc_wams/qa/web-rtcp-5axis-site-test/output/site-test-report.json
```

截图目录：

```text
/home/mes123456/cnc_wams/qa/web-rtcp-5axis-site-test/screenshots/
```

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

### 现象

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

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

但 RTCP frame 仍显示：

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

手动执行：

```js
await window.webRtcp5AxisSimulation.refreshKinematicsFrame()
```

后可立即切换为：

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

### 影响

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

### 涉及代码

```text
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；随后又把：

```js
frameSourceMode: frame.sourceMode
```

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

`scheduleAsyncKinematicsRefresh()` 又依赖：

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

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

## 3. D2：3D 预览不可见

### 现象

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

相关截图：

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

### 影响

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

### 涉及代码

```text
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 坐标连续性异常

### 现象

稳定复核结果：

```text
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 视觉反馈都可能被错误坐标污染。

### 涉及代码

```text
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：

```js
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` 经稳定态复核均可执行：

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

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