cnc_wams/web-rtcp-5axis-sim-plan/working/02-rtcp-toolpath-remediation-steps.md

02 RTCP 刀具轨迹整改完善程序详细步骤

生成时间：2026-06-22

1. 修改目标

针对专项测试发现的运行态 RTCP 回退问题，整改 TASK_HAL_STATUS_APPLIED 状态合并逻辑。

2. 修改文件

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 解析入口

位置：

store.js -> applyTaskHalStatusPatch()

将原逻辑：

const kinsType = kinsTypeFromSwitchkinsTypeValue(state, ui.switchkinsType);

替换为：

const kinsType = resolveTaskHalKinsType(state, status, activeLine);

目的：

让 task/HAL status 和 interpreter/canonical motion 的 switchkins 语义共同参与 kinsType 解析。

Step 3.2 增加 resolveTaskHalKinsType()

新增函数：

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);
}

判定规则：

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 的映射

新增函数：

function kinsTypeFromProgramActiveLine(state, activeLine) {
  const motion = programMotionAtOrBeforeLine(state, activeLine)
    || state.programExecution?.motion?.[clampMotionIndex(state, state.programExecutionMotionIndex)];
  return kinsTypeFromProgramMotion(state, motion);
}

新增函数：

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;
}

目的：

用当前 task/HAL activeLine 找到最近的 canonical motion，
再复用已有 kinsTypeFromProgramMotion() 解析 M428/M429/M430 语义。

Step 3.4 保持已有 program motion 解析函数不变

继续复用：

function kinsTypeFromProgramMotion(state, motion) { ... }
function resolveProgramKinsType(state, requestedKinsType) { ... }
function kinsTypeFromSwitchkinsType(state, switchkinsType) { ... }

不要新增 G-code 字符串解析。

Step 3.5 增加 node 回归测试

位置：

web-rtcp-5axis-sim-plan/tests/node/verify_rtcp_store.mjs

新增测试数据：

motion line 5: switchkinsType=1, kinsType=tcp
motion line 20: switchkinsType=0, kinsType=identity

新增断言：

当 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 更新专项测试报告

重新运行：

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

期望：

06-running-rtcp-toolpath -> PASS
threeRtcpState=on

4. 不允许的修复方式

1. 不允许在 five-axis-scene.js 中强制显示 RTCP on。
2. 不允许在 canvas dataset 中伪造 threeRtcpState。
3. 不允许直接忽略 task/HAL status。
4. 不允许重新用字符串扫描 G-code 推断 M428/M429。

5. 后续完善建议

1. task/HAL runtime 长期应输出更准确的 switchkins source metadata。
2. programExecutionMotionIndex 可进一步按 activeLine 同步，提高当前段高亮精度。
3. 专项测试可增加执行到 M429 后 RTCP off 的端到端截图。