5.0 KiB
5.0 KiB
04 修复溯源矩阵
生成时间：2026-06-22
1. 总体追溯原则
测试问题 -> 证据 -> 本地代码落点 -> 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 模板基础上追加一份记录，例如：
working1-log-2026-06-22-d1.md
working1-log-2026-06-22-d2.md
working1-log-2026-06-22-d3.md
每份记录必须包含：
问题 ID
修改文件
关键代码变更
运行测试
截图/日志证据
剩余风险