# 04 修复溯源矩阵

生成时间：2026-06-22

## 1. 总体追溯原则

```text
测试问题 -> 证据 -> 本地代码落点 -> LinuxCNC/项目参考 -> 修复项 -> 验收项
```

任何修复都不能只修改 UI 文案掩盖问题，必须让 runtime state、DOM diagnostics、截图和自动化断言一致。

## 2. 问题到修复追溯表

| 问题 ID | 测试证据 | 本地代码落点 | LinuxCNC/项目参考 | 修复项 | 验收项 |
| --- | --- | --- | --- | --- | --- |
| D1 | `sourceMode=fixture-ui-only`，`frameBoundary=fixture_frame_ui_plumbing_not_linuxcnc_kinematics_proof`，但 `kinematicsRuntimeReadiness.loaded=true` | `app/src/state/store.js` `ATTACH_KINEMATICS_RUNTIME`、`setState()`、`scheduleAsyncKinematicsRefresh()`、`refreshAsyncKinematicsFrame()`；`app/src/main.js` `attachDefaultKinematicsRuntime()` | `docs/traceability-matrix.md` 中 `Five-axis kinematics`、`RTCP/TCP frame`；LinuxCNC `xyzac-trt-kins.c`、`xyzbc-trt-kins.c`、`trtfuncs.c` | 分离 `desiredFrameSourceMode` 与当前 `frameSourceMode`，异步 worker ready 后自动刷新 frame | 首屏 8 秒内 `sourceMode=source-derived-kinematics-wasm`，DOM boundary 为 `linuxcnc_kinematics_wasm_c_abi` |
| D2 | 截图中 preview 黑屏，无可见机床/刀路；canvas dataset 不稳定 | `app/src/visualization/five-axis-scene.js` `createScene()`、`updateToolpathPreview()`、`renderFallbackPreview()`、`exposePreviewDataset()`；`app/src/ui/gmoccapy-shell.js` `renderPreview()` | `docs/implementation-plan.md` 5.4 Visualization/Playback；LinuxCNC `lib/python/vismach.py`、5-axis vismach GUI screenshots | 修复未定义变量，加入常驻机床模型，fallback 绘制明显对象，增加 pixel smoke | canvas 非空，`data-three-ready=true`，`sceneObjects>0`，截图可见机床/刀路/TCP |
| D3 | HOME 后 `X=43/Y=-32.15/Z=-11.306`，JOG X+ 后跳到 `X=1/Y=0/Z=0` | `app/src/state/store.js` `JOG`、`HOME`、`applyTaskHalStatusPatch()`；`app/src/runtime/linuxcnc-task-hal-runtime.js` status `ui.axisPose` | LinuxCNC task/motion command model：`EMC_JOG_INCR`、`EMC_JOINT_HOME`；项目 `linuxcnc-task-policy.js` | 为 task/HAL axis pose 增加坐标系元数据，pending jog context，防止局部坐标覆盖 work pose | HOME 后 JOG X+/Y- 基于当前 DRO 连续增减 |

## 3. 文件级追溯

| 文件 | 当前职责 | 本次修复关注点 | 需要新增测试 |
| --- | --- | --- | --- |
| `app/src/main.js` | app 启动、runtime attach、profile 变更订阅 | kinematics runtime attach 后可靠触发 frame refresh | browser smoke 检查首屏 kinematics ready |
| `app/src/state/store.js` | 全局状态机、RTCP frame、task policy、运行控制 | desired/current frame source 分离；JOG 坐标连续性；task/HAL status 坐标解析 | node store test + browser operator workflow |
| `app/src/runtime/rtcp-frame.js` | RTCP frame 构建和边界标识 | 确认 source-derived frame 输出 diagnostics 明确 | RTCP frame source smoke |
| `app/src/visualization/five-axis-scene.js` | Three.js/fallback 预览渲染 | 可见机床模型、fallback 非空、dataset 稳定 | canvas pixel smoke |
| `app/src/runtime/linuxcnc-task-hal-runtime.js` | task/HAL runtime adapter 和 status normalize | `axisPoseFrame` / `axisPoseDelta` 输出 | task/HAL JOG status test |
| `app/src/state/linuxcnc-task-policy.js` | LinuxCNC task mode/state gate | 一般不需要改；作为 JOG/HOME gate 参考 | 维持现有 gate tests |

## 4. 测试证据追溯

| 证据文件 | 用途 |
| --- | --- |
| `qa/web-rtcp-5axis-site-test/output/web-rtcp-5axis-site-test-report-2026-06-22.docx` | 人类可读测试报告和截图 |
| `qa/web-rtcp-5axis-site-test/output/site-test-report.json` | 自动化原始 findings、state、console、request 数据 |
| `qa/web-rtcp-5axis-site-test/screenshots/01-home.png` | 首屏预览黑屏和初始界面证据 |
| `qa/web-rtcp-5axis-site-test/screenshots/04-run-state.png` | Run 后预览仍不可见证据 |
| `qa/web-rtcp-5axis-site-test/screenshots/05-local-program-opened.png` | 本地程序导入后预览仍不可见证据 |
| `qa/web-rtcp-5axis-site-test/screenshots/06-after-audit.png` | Audit 后预览仍不可见证据 |

## 5. LinuxCNC 参考追溯

| 能力 | LinuxCNC 参考 | Web 边界 |
| --- | --- | --- |
| TRT kinematics | `src/emc/kinematics/trtfuncs.c`、`xyzac-trt-kins.c`、`xyzbc-trt-kins.c` | 只能通过 source-derived WASM frame 使用 |
| switchkins | `src/emc/kinematics/switchkins.c`、`switchkins.h` | `M428/M429/M430` 和 kins type UI |
| task/JOG/HOME | `src/emc/task/emctaskmain.cc`、`src/emc/nml_intf/emc.hh` | Web task policy + task/HAL WASM simulation |
| vismach visual model | `lib/python/vismach.py`、5-axis vismach configs/xml | Three.js scene graph reference，不移植 Python runtime |

## 6. 后续修复批次记录要求

每一批修复完成后，在 `06-work-log-template.md` 模板基础上追加一份记录，例如：

```text
working1-log-2026-06-22-d1.md
working1-log-2026-06-22-d2.md
working1-log-2026-06-22-d3.md
```

每份记录必须包含：

```text
问题 ID
修改文件
关键代码变更
运行测试
截图/日志证据
剩余风险
```