Add RTCP simulation QA updates

2026-06-22 09:30:27 -04:00
parent 61e2fe8441
commit ea8e10031b
51 changed files with 10008 additions and 178 deletions
--- a/web-rtcp-5axis-sim-plan/working/01-rtcp-toolpath-problem-review.md
+++ b/web-rtcp-5axis-sim-plan/working/01-rtcp-toolpath-problem-review.md
@@ -0,0 +1,119 @@
+# 01 RTCP 刀具轨迹问题复盘
+
+生成时间：2026-06-22
+
+## 1. 测试来源
+
+专项测试脚本：
+
+```text
+qa/web-rtcp-5axis-site-test/capture-toolpath-preview-cases.mjs
+```
+
+专项报告：
+
+```text
+qa/web-rtcp-5axis-site-test/output/web-rtcp-5axis-toolpath-preview-report-2026-06-22.docx
+```
+
+原始数据：
+
+```text
+qa/web-rtcp-5axis-site-test/output/toolpath-preview-cases.json
+```
+
+## 2. 失败现象
+
+失败场景：
+
+```text
+06-running-rtcp-toolpath
+```
+
+失败前证据：
+
+```text
+05-vendored-impeller-toolpath:
+threeRtcpState=on
+pathPoints=1498
+executedPathPoints=1
+programSource=linuxcnc-vendored-5axis-gcode
+programExecution.summary.switchkinsEventCount=2
+switchkinsCodes=M428,M429
+```
+
+失败时证据：
+
+```text
+06-running-rtcp-toolpath:
+threeRtcpState=off
+state.rtcpState=off
+state.kinsType=identity
+programRuntimeFeedbackSource=linuxcnc-task-motion-hal-wasm
+```
+
+## 3. 影响
+
+该问题影响 G-code 执行时的刀具轨迹可信度：
+
+```text
+1. 预览路径显示程序已经进入 TCP/RTCP 区间。
+2. RUN 后 task/HAL 状态把 kinsType 回退到 identity。
+3. canvas 上的 TCP/刀轴/RTCP 状态与程序 switchkins 语义不一致。
+4. 操作者可能误判当前刀具姿态和五轴 RTCP 执行状态。
+```
+
+## 4. 根因定位
+
+代码落点：
+
+```text
+web-rtcp-5axis-sim-plan/app/src/state/store.js
+```
+
+原逻辑：
+
+```js
+const kinsType = kinsTypeFromSwitchkinsTypeValue(state, ui.switchkinsType);
+```
+
+问题：
+
+```text
+task/HAL runtime status.ui.switchkinsType=0 时，store 直接解析为 identity。
+但当前 activeLine 对应的 interpreter/canonical motion 仍处于 M428 后的 TCP 区间。
+因此 task/HAL status 覆盖了程序语义。
+```
+
+## 5. 正确边界
+
+整改原则：
+
+```text
+1. 不在可视化层硬编码 RTCP。
+2. 不用 JavaScript 重新解释 G-code。
+3. 优先消费 LinuxCNC interpreter 已输出的 canonical motion switchkins 信息。
+4. task/HAL status 非零 switchkinsType 可直接采用。
+5. task/HAL status 为 0 时，必须结合当前 activeLine 的 program motion 判断是否仍在 TCP 区间。
+```
+
+## 6. 修复目标
+
+目标状态：
+
+```text
+预览态:
+threeRtcpState=on
+state.kinsType=tcp-xyzac
+
+RUN 后:
+threeRtcpState=on
+state.kinsType=tcp-xyzac
+programRuntimeFeedbackSource=linuxcnc-task-motion-hal-wasm
+```
+
+同时，当程序执行到 M429/identity 区间时，仍允许正确回退：
+
+```text
+activeLine 对应 motion.switchkinsType=0 -> kinsType=identity, rtcpState=off
+```
--- a/web-rtcp-5axis-sim-plan/working/02-rtcp-toolpath-remediation-steps.md
+++ b/web-rtcp-5axis-sim-plan/working/02-rtcp-toolpath-remediation-steps.md
@@ -0,0 +1,189 @@
+# 02 RTCP 刀具轨迹整改完善程序详细步骤
+
+生成时间：2026-06-22
+
+## 1. 修改目标
+
+针对专项测试发现的运行态 RTCP 回退问题，整改 `TASK_HAL_STATUS_APPLIED` 状态合并逻辑。
+
+## 2. 修改文件
+
+```text
+web-rtcp-5axis-sim-plan/app/src/state/store.js
+web-rtcp-5axis-sim-plan/tests/node/verify_rtcp_store.mjs
+```
+
+## 3. 程序修改步骤
+
+### Step 3.1 替换 task/HAL kinsType 解析入口
+
+位置：
+
+```text
+store.js -> applyTaskHalStatusPatch()
+```
+
+将原逻辑：
+
+```js
+const kinsType = kinsTypeFromSwitchkinsTypeValue(state, ui.switchkinsType);
+```
+
+替换为：
+
+```js
+const kinsType = resolveTaskHalKinsType(state, status, activeLine);
+```
+
+目的：
+
+```text
+让 task/HAL status 和 interpreter/canonical motion 的 switchkins 语义共同参与 kinsType 解析。
+```
+
+### Step 3.2 增加 resolveTaskHalKinsType()
+
+新增函数：
+
+```js
+function resolveTaskHalKinsType(state, status, activeLine) {
+  const ui = status?.ui || {};
+  const numeric = Number(ui.switchkinsType);
+  if (Number.isFinite(numeric) && numeric !== 0) {
+    return kinsTypeFromSwitchkinsTypeValue(state, numeric);
+  }
+
+  const programKinsType = kinsTypeFromProgramActiveLine(state, activeLine);
+  if (programKinsType) {
+    return programKinsType;
+  }
+
+  return kinsTypeFromSwitchkinsTypeValue(state, ui.switchkinsType);
+}
+```
+
+判定规则：
+
+```text
+1. task/HAL switchkinsType 非 0:
+   直接采用 task/HAL 状态。
+
+2. task/HAL switchkinsType 为 0:
+   查询当前 activeLine 对应的 program motion。
+
+3. program motion 有 switchkins 语义:
+   采用 program motion 的 kinsType。
+
+4. program motion 无 switchkins 语义:
+   回退到 task/HAL status 解析结果。
+```
+
+### Step 3.3 增加 activeLine 到 program motion 的映射
+
+新增函数：
+
+```js
+function kinsTypeFromProgramActiveLine(state, activeLine) {
+  const motion = programMotionAtOrBeforeLine(state, activeLine)
+    || state.programExecution?.motion?.[clampMotionIndex(state, state.programExecutionMotionIndex)];
+  return kinsTypeFromProgramMotion(state, motion);
+}
+```
+
+新增函数：
+
+```js
+function programMotionAtOrBeforeLine(state, activeLine) {
+  const motion = state.programExecution?.motion;
+  if (!Array.isArray(motion) || motion.length === 0) return null;
+  const line = Number(activeLine);
+  if (!Number.isFinite(line)) return null;
+  let candidate = null;
+  for (const item of motion) {
+    const itemLine = Number(item?.line);
+    if (!Number.isFinite(itemLine)) continue;
+    if (itemLine > line) break;
+    candidate = item;
+  }
+  return candidate;
+}
+```
+
+目的：
+
+```text
+用当前 task/HAL activeLine 找到最近的 canonical motion，
+再复用已有 kinsTypeFromProgramMotion() 解析 M428/M429/M430 语义。
+```
+
+### Step 3.4 保持已有 program motion 解析函数不变
+
+继续复用：
+
+```js
+function kinsTypeFromProgramMotion(state, motion) { ... }
+function resolveProgramKinsType(state, requestedKinsType) { ... }
+function kinsTypeFromSwitchkinsType(state, switchkinsType) { ... }
+```
+
+不要新增 G-code 字符串解析。
+
+### Step 3.5 增加 node 回归测试
+
+位置：
+
+```text
+web-rtcp-5axis-sim-plan/tests/node/verify_rtcp_store.mjs
+```
+
+新增测试数据：
+
+```text
+motion line 5: switchkinsType=1, kinsType=tcp
+motion line 20: switchkinsType=0, kinsType=identity
+```
+
+新增断言：
+
+```text
+当 task/HAL status activeLine=5 且 ui.switchkinsType=0:
+  state.kinsType 必须保持 tcp-xyzac
+  state.rtcpState 必须保持 on
+
+当 task/HAL status activeLine=20 且 ui.switchkinsType=0:
+  state.kinsType 必须为 identity
+  state.rtcpState 必须为 off
+```
+
+### Step 3.6 更新专项测试报告
+
+重新运行：
+
+```bash
+node qa/web-rtcp-5axis-site-test/capture-toolpath-preview-cases.mjs
+node qa/web-rtcp-5axis-site-test/generate-toolpath-preview-docx-report.mjs
+```
+
+期望：
+
+```text
+06-running-rtcp-toolpath -> PASS
+threeRtcpState=on
+```
+
+## 4. 不允许的修复方式
+
+```text
+1. 不允许在 five-axis-scene.js 中强制显示 RTCP on。
+2. 不允许在 canvas dataset 中伪造 threeRtcpState。
+3. 不允许直接忽略 task/HAL status。
+4. 不允许重新用字符串扫描 G-code 推断 M428/M429。
+```
+
+## 5. 后续完善建议
+
+```text
+1. task/HAL runtime 长期应输出更准确的 switchkins source metadata。
+2. programExecutionMotionIndex 可进一步按 activeLine 同步，提高当前段高亮精度。
+3. 专项测试可增加执行到 M429 后 RTCP off 的端到端截图。
+```
--- a/web-rtcp-5axis-sim-plan/working/03-rtcp-toolpath-test-record.md
+++ b/web-rtcp-5axis-sim-plan/working/03-rtcp-toolpath-test-record.md
@@ -0,0 +1,74 @@
+# 03 RTCP 刀具轨迹整改测试记录
+
+生成时间：2026-06-22
+
+## 1. 修改摘要
+
+```text
+问题: G-code RUN 后 RTCP 从 on 回退到 off。
+根因: TASK_HAL_STATUS_APPLIED 直接采用 task/HAL status.ui.switchkinsType=0。
+修复: task/HAL switchkinsType 为 0 时，按 activeLine 查询 programExecution.motion 的 switchkins 语义。
+```
+
+## 2. 修改文件
+
+| 文件 | 修改内容 |
+| --- | --- |
+| `app/src/state/store.js` | 新增 `resolveTaskHalKinsType()`、`kinsTypeFromProgramActiveLine()`、`programMotionAtOrBeforeLine()` |
+| `tests/node/verify_rtcp_store.mjs` | 增加 task/HAL status 与 program motion switchkins 合并回归测试 |
+| `qa/web-rtcp-5axis-site-test/capture-toolpath-preview-cases.mjs` | 专项截图测试已保留运行态 RTCP 检查 |
+| `qa/web-rtcp-5axis-site-test/generate-toolpath-preview-docx-report.mjs` | 专项 Word 报告生成 |
+
+## 3. 验证命令
+
+```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_linuxcnc_task_hal_runtime.mjs
+bash web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_shell_browser.sh
+node qa/web-rtcp-5axis-site-test/capture-toolpath-preview-cases.mjs
+node qa/web-rtcp-5axis-site-test/generate-toolpath-preview-docx-report.mjs
+```
+
+## 4. 验证结果
+
+```text
+gmoccapy_static_build=ok
+rtcp_store_smoke=ok
+linuxcnc_task_hal_runtime_smoke=ok
+task_hal_machine_file_smoke=ok
+switchkins_remap_hal_sync_smoke=ok
+browser_task_hal_worker_smoke=ok
+gmoccapy_shell_smoke=ok
+```
+
+专项测试：
+
+```text
+total=6
+PASS=6
+FAIL=0
+06-running-rtcp-toolpath threeRtcpState=on
+```
+
+Word 报告校验：
+
+```text
+unzip -t qa/web-rtcp-5axis-site-test/output/web-rtcp-5axis-toolpath-preview-report-2026-06-22.docx
+No errors detected
+```
+
+## 5. 证据文件
+
+```text
+qa/web-rtcp-5axis-site-test/output/toolpath-preview-cases.json
+qa/web-rtcp-5axis-site-test/output/web-rtcp-5axis-toolpath-preview-report-2026-06-22.docx
+qa/web-rtcp-5axis-site-test/screenshots/toolpath-preview-cases/06-running-rtcp-toolpath.png
+```
+
+## 6. 回归结论
+
+```text
+整改后，G-code RUN 状态下 task/HAL runtime feedback 不再把程序 switchkins TCP 区间错误回退到 identity/off。
+刀具预览、TCP 球、刀轴线、长路径、执行轨迹、rapid/feed 分层和 RTCP 状态在专项测试中全部通过。
+```
--- a/web-rtcp-5axis-sim-plan/working/README.md
+++ b/web-rtcp-5axis-sim-plan/working/README.md
@@ -0,0 +1,35 @@
+# working 整改文档索引
+
+生成时间：2026-06-22
+
+本目录记录针对“刀具预览与 G-code 执行刀具轨迹专项测试”发现问题的整改方案、程序修改步骤和验证证据。
+
+## 文件清单
+
+| 文件 | 用途 |
+| --- | --- |
+| `01-rtcp-toolpath-problem-review.md` | 记录专项测试问题、现象、影响和代码落点 |
+| `02-rtcp-toolpath-remediation-steps.md` | 面向程序员的详细整改完善步骤 |
+| `03-rtcp-toolpath-test-record.md` | 整改后测试命令、结果和证据路径 |
+
+## 本轮问题结论
+
+专项测试 `06-running-rtcp-toolpath` 发现：
+
+```text
+预览态: RTCP=on, kinsType=tcp-xyzac
+G-code RUN 后: canvas dataset threeRtcpState=off, state.kinsType=identity
+```
+
+根因：
+
+```text
+TASK_HAL_STATUS_APPLIED 使用 task/HAL status.ui.switchkinsType=0 直接覆盖了 interpreter/canonical motion 已解析出的程序 switchkins 状态。
+```
+
+整改后：
+
+```text
+6 个刀具预览/G-code 轨迹专项场景全部 PASS。
+运行态 threeRtcpState 保持 on。
+```