Add RTCP simulation QA updates

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

@@ -0,0 +1,212 @@
+# 01 问题复盘
+
+生成时间：2026-06-22
+
+## 1. 输入证据
+
+测试报告：
+
+```text
+/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/web-rtcp-5axis-site-test-report-2026-06-22.docx
+```
+
+原始自动化结果：
+
+```text
+/home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/site-test-report.json
+```
+
+截图目录：
+
+```text
+/home/meswork/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`，这是当前实现命名，不是功能失败。
+