# working1 修复执行记录 D1-D2-D3

生成时间：2026-06-22

## Batch

```text
Batch: working1-implementation-d1-d2-d3
Date: 2026-06-22
Owner: Codex
Problem IDs: D1, D2, D3
Branch: current worktree
Commit: not committed
```

## 1. 修复目标

```text
D1: kinematics worker ready 后，页面自动保持 LinuxCNC source-derived kinematics frame，不被临时 fixture frame 永久覆盖。
D2: 首屏和路径清空后仍显示可见五轴参考机床、坐标轴、旋转轴、刀具/TCP；canvas dataset 和像素测试可验证。
D3: HOME 后执行 task/HAL JOG，DRO/work pose 保持连续增量，不被 task-local/local-zero 轴位覆盖。
```

## 2. 修改文件

| 文件 | 修改内容 | 原因 |
| --- | --- | --- |
| `app/src/state/store.js` | 增加 `desiredFrameSourceMode`、`pendingJogCommand`；调整 async kinematics refresh；新增 `resolveTaskHalAxisPose()` | 分离“期望 frame source”和“当前 frame source”；保护 HOME 后 JOG 坐标连续性 |
| `app/src/main.js` | profile kinematics runtime attach 完成后再次调用 `refreshKinematicsFrame()` | 满足 profile/INI 变更后的自动 frame 刷新要求 |
| `app/src/runtime/linuxcnc-task-hal-runtime.js` | `ui.axisPoseFrame` 标记 JOG 为 `task-local`，非 JOG 为 `work` | 让 store 能区分 task/HAL 轴位坐标系 |
| `app/src/visualization/five-axis-scene.js` | 新增 WebGL 五轴参考机床模型和 2D fallback 参考绘制；路径清空时仍显示 TCP | 修复 3D 预览黑屏/不可见和 fallback 信息不足 |
| `tests/browser/gmoccapy_shell_smoke.html` | 更新 reference model dataset 断言；新增 canvas pixel stats 检查 | 防止只通过 DOM dataset 误判可见性 |
| `tests/node/verify_linuxcnc_task_hal_runtime.mjs` | 增加 HOME 后 JOG X+/Y- 连续性断言 | 覆盖 D3 复现路径 |

## 3. 关键实现说明

```text
状态字段变化:
- desiredFrameSourceMode: 保留用户/运行时希望的 frame source。
- pendingJogCommand: 记录 task/HAL JOG 的 axis、direction、increment、basePose。

核心函数变化:
- buildFrameForState(): 优先读取 desiredFrameSourceMode。
- scheduleAsyncKinematicsRefresh(): 以 desiredFrameSourceMode + runtime loaded 作为刷新条件。
- refreshAsyncKinematicsFrame(): 成功后写回 source/frame/desired 均为 source-derived-kinematics-wasm，失败显示 operatorMessage 并保留重试能力。
- resolveTaskHalAxisPose(): work pose 直接合并，axis delta 累加，pending JOG 用 basePose + increment。

UI/可视化变化:
- WebGL scene 增加 table/base、XYZ axis、A/C rotary ring、tool holder。
- 2D fallback 始终绘制工作台、XYZ 轴、旋转中心、TCP 点。
- canvas dataset 输出 machine-reference-and-toolpath / webgl-five-axis-reference。
```

## 4. LinuxCNC/项目溯源

```text
参考项目文档:
- working1/03-implementation-steps.md
- working1/04-traceability-matrix.md
- docs/traceability-matrix.md

参考 LinuxCNC 边界:
- kinematics frame 仍来自 LinuxCNC kinematics WASM C ABI。
- task/HAL JOG 仍通过 EMC_JOG_INCR 模拟 runtime 执行；UI 只处理坐标系归并，不重写 CNC 运动语义。
- Three.js 只消费 runtime frame/canonical motion/task-HAL feedback，不生成 G-code 或 CNC 语义。
```

## 5. 测试记录

### 5.1 已通过命令

```bash
npm --prefix web-rtcp-5axis-sim-plan/app run build
node web-rtcp-5axis-sim-plan/tests/node/verify_linuxcnc_task_hal_runtime.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_rtcp_store.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_five_axis_session.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_linuxcnc_kinematics_runtime.mjs
bash web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_shell_browser.sh
bash web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_dist_browser.sh
```

### 5.2 关键输出

```text
gmoccapy_static_build=ok
linuxcnc_task_hal_runtime_smoke=ok
rtcp_store_smoke=ok
five_axis_session_smoke=ok
linuxcnc_kinematics_runtime_smoke=ok
gmoccapy_shell_smoke=ok
gmoccapy_dist_smoke=ok
```

### 5.3 未通过/阻塞命令

```bash
npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
```

结果：

```text
前置 kinematics/interpreter/INI/task-HAL 均通过。
失败位置: verify_native_task_hal_audit.mjs -> wasm-port/tests/native/verify_task_hal_phase0.sh
失败原因: verify_task_hal_source_manifest.sh 返回非零，manifest ready=0。
证据: wasm-port/build/task-hal/verify_task_hal_source_manifest.stdout.log
关键字段:
- task_hal_reference_source_ready=0
- task_hal_vendor_source_ready=0
- task_hal_missing_reference_source_count=20
```

该失败属于 native LinuxCNC reference source/probe 前置条件，不是本轮 Web D1/D2/D3 代码回归。

## 6. 回归范围

| 功能 | 是否回归 | 结果 |
| --- | --- | --- |
| D1 kinematics auto refresh | 是 | PASS |
| D2 preview visible | 是 | PASS |
| D3 jog continuity | 是 | PASS |
| POWER/E-STOP/RESET | 是 | PASS via browser smoke |
| MDI M428/M429/M430 | 是 | PASS via browser/node smoke |
| Load/Run/Step/Stop | 是 | PASS via browser smoke |
| Save/Restore Session | 是 | PASS via browser/node smoke |
| Native source manifest/probe | 是 | BLOCKED: missing native reference sources |

## 7. 剩余风险

```text
1. native task/HAL source manifest 仍未 ready，缺少 20 个 native reference source，完整 smoke:node 不能全绿。
2. WebGL reference model 已通过 smoke，但仍建议后续保留人工截图复核首屏和 clear-preview 后视觉效果。
3. task/HAL axisPoseFrame 当前按 JOG/non-JOG 推断；长期方案仍应由 runtime 输出更细的 work/task-local/axisPoseDelta 元数据。
```

## 8. 下一步

```text
Next:
- 补齐或恢复 wasm-port/tools/task-hal-source-manifest.txt 对应的 native LinuxCNC reference sources。
- native source manifest ready 后重跑 npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node。
- 部署到 https://82.156.24.101:8092/ 后重跑 QA 站点测试，更新 Word 测试报告。

Blockers:
- wasm-port/build/task-hal/verify_task_hal_source_manifest.stdout.log 显示 native reference source 缺失。
```