# 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 的端到端截图。
```