cnc_wams/web-rtcp-5axis-sim-plan/docs/traceability-matrix.md

5 轴数控系统 Web 仿真实现追溯文档

生成时间：2026-06-20 CST

1. 目的

本文件用于追溯后续实现中的每个主要功能来自哪里、参考了哪些 LinuxCNC 源文件/配置/图片、属于什么边界、如何验证。

追溯原则：

界面形态可参考 LinuxCNC Python GUI；
CNC 语义必须来自 LinuxCNC source/WASM/source-derived boundary；
浏览器代码只负责 UI、状态编排、文件会话、可视化和调用边界；
任何 fixture 或 UI-only 结果不得冒充 LinuxCNC runtime proof。

2. 总体追溯表

功能	Web 实现位置	LinuxCNC 参考	边界分类	验证方式
gmoccapy 风格 shell	app/src/ui/gmoccapy-shell.ts	docs/src/gui/images/gmoccapy_5_axis.png, configs/sim/gmoccapy/gmoccapy_XYZAC.ini	UI reference	browser shell smoke
大号 DRO	app/src/ui/gmoccapy-dro-panel.ts	gmoccapy 5 axis screenshot, LinuxCNC DRO conventions	UI rendering of runtime state	DOM smoke + state smoke
右侧模式按钮栏	app/src/ui/gmoccapy-status-sidebar.ts	gmoccapy screenshot	UI action dispatch	browser button/action smoke
底部运行控制	app/src/ui/gmoccapy-bottom-controls.ts	gmoccapy/AXIS run controls	UI action dispatch	playback smoke
G-code 当前行	app/src/ui/gmoccapy-gcode-panel.ts	AXIS/gmoccapy program display	LinuxCNC output rendering	active-line smoke
上电/急停/复位/模式操作	app/src/state/store.js, app/src/ui/gmoccapy-shell.js	gmoccapy/AXIS operator workflow	browser UI runtime fixture	node smoke + browser operator smoke
JOG/MDI 操作	app/src/state/store.js, app/src/ui/gmoccapy-shell.js	AXIS Manual/MDI workflow	browser UI runtime fixture	node smoke + browser operator smoke
G-code 文件加载	app/src/ui/gmoccapy-shell.js, app/src/state/store.js	AXIS/gmoccapy open program workflow	file text staging only, not LinuxCNC interpreter proof	node smoke + browser operator smoke
程序执行当前行显示	app/src/state/store.js, app/src/ui/gmoccapy-shell.js	AXIS/gmoccapy current line display	fixture line playback until LinuxCNC interpreter is connected	node smoke + browser operator smoke
刀具预览	app/src/ui/gmoccapy-shell.js, app/src/visualization/five-axis-scene.js	gmoccapy/vismach tool display	visualization/runtime state display	browser operator smoke
3D 五轴预览	app/src/visualization/five-axis-scene.js	qtvismach_5axis_gantry.png, lib/python/vismach.py	visualization	canvas nonblank smoke
Vismach transform tree	app/src/visualization/machine-model.ts	lib/python/vismach.py, src/hal/user_comps/vismach/*.py	visualization from GUI reference	scene graph smoke
xyzac-trt profile	app/src/profiles/xyzac-trt.js	configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini	source/config reference	profile boundary node smoke
xyzac-trt source reference map	app/src/profiles/source-reference-map.js	xyzac-trt.ini, xyzac-trt.xml, switchkins_postgui.hal, xyzac-trt_cmds.hal, xyzac-trt-kins.c, trtfuncs.c, switchkins.c	profile/source map only, not runtime proof	profile boundary node smoke
xyzbc-trt profile	app/src/profiles/xyzbc-trt.ts	configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini	source/config reference	profile node smoke
SWITCHKINS panel	app/src/panel-schema/xyzac-trt-pyvcp.js	xyzac-trt.xml, switchkins_postgui.hal	UI/HAL binding reference	profile boundary node smoke + browser DOM smoke
M428/M429/M430 state	app/src/profiles/xyzac-trt.js, app/src/panel-schema/xyzac-trt-pyvcp.js	remap_subs/428remap.ngc, 429remap.ngc, 430remap.ngc	LinuxCNC remap/source reference only until runtime adapter is connected	profile boundary node smoke
LinuxCNC boundary adapter	app/src/runtime/linuxcnc-boundary-adapter.js	LinuxCNC interpreter/kinematics WASM future adapter point	adapter entrypoint only, runtime not connected	profile boundary node smoke + browser DOM smoke
Five-axis kinematics	core/linuxcnc_kinematics_wasm	trtfuncs.c, xyzac-trt-kins.c, xyzbc-trt-kins.c, 5axiskins.c	LinuxCNC source-derived WASM	Node roundtrip smoke
RTCP/TCP frame	app/src/runtime/rtcp-frame.js	LinuxCNC kinematics output + canonical events	fixture frame plumbing until kinematics WASM is ready	RTCP/store node smoke + browser DOM smoke
OPFS session	app/src/runtime/session-*	current wasm-port/runtime/opfs	host-side persistence	save/restore smoke

3. 源文件追溯清单

UI 图片

linuxcnc/docs/src/gui/images/gmoccapy_5_axis.png
linuxcnc/docs/src/gui/images/qtvismach_5axis_gantry.png
linuxcnc/docs/src/gui/images/axis.png
linuxcnc/docs/src/gui/images/axis-pyvcp.png
linuxcnc/docs/src/gui/images/qtdragon.png
linuxcnc/docs/src/gui/images/qtdragon_hd.png

本项目副本：

assets/reference/linuxcnc-gui/

Python GUI

src/emc/usr_intf/axis/scripts/axis.py
lib/python/vismach.py
src/hal/user_comps/vismach/5axisgui.py
src/hal/user_comps/vismach/xyzac-trt-gui.py
src/hal/user_comps/vismach/xyzbc-trt-gui.py
configs/sim/gmoccapy/gmoccapy_XYZAC.ini
configs/sim/qtvcp_screens/qtdragon/README

使用方式：

UI/visualization reference only

5 轴配置

configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini
configs/sim/axis/vismach/5axis/bridgemill/5axis.ini
configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.ini

PyVCP/HAL

configs/sim/axis/vismach/5axis/bridgemill/5axis.xml
configs/sim/axis/vismach/5axis/bridgemill/5axis_postgui.hal
configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.xml
configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.xml
configs/sim/axis/vismach/5axis/table-rotary-tilting/switchkins_postgui.hal
configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.xml
configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr-postgui.hal

5 轴运动学源码

src/emc/kinematics/trtfuncs.c
src/emc/kinematics/xyzac-trt-kins.c
src/emc/kinematics/xyzbc-trt-kins.c
src/emc/kinematics/5axiskins.c
src/emc/kinematics/switchkins.c
src/emc/kinematics/switchkins.h
src/emc/kinematics/userkfuncs.c
src/emc/kinematics/kins_util.c

4. 边界状态

边界	当前状态	说明
gmoccapy UI style	ready	可直接 Web 化
Three.js preview	implemented_basic_canvas_scene	已显示基础五轴机床、刀具/TCP marker、刀轴、刀路，并消费 rtcpFrame
LinuxCNC interpreter WASM	existing_project_capability	可参考 wasm-port 现有 SDK
LinuxCNC 5-axis kinematics WASM	node_proof_ready	createLinuxCncKinematicsSdk({ moduleId: "xyzac-trt" }) 已由 web adapter 加载，Node smoke 验证 forward/inverse frame
RTCP frame UI plumbing	implemented_fixture_and_kinematics_wasm	fixture fallback 仍为 linuxCncKinematicsReady=false；Node kinematics proof 为 source-derived-kinematics-wasm / linuxcnc_kinematics_wasm_c_abi
Operator workflow	implemented_fixture_only	上电/急停/复位/模式/JOG/MDI/G-code 加载/当前行显示已闭环；执行仍是 fixture line playback
LinuxCNC boundary adapter	kinematics_runtime_connected_node	web-rtcp-5axis-linuxcnc-boundary-adapter 可区分 kinematics-only ready 与 interpreter/remap missing
PyVCP/HAL panel schema	implemented_reference_only	xyzac-trt-switchkins-pyvcp 已整理 SWITCHKINS 控件与 HAL nets；不执行 native HAL
Python GUI runtime	not_ported	只参考，不运行
Python remap runtime	blocked	不在第一版实现
tool DB runtime	blocked	不在第一版实现
external user-M process	blocked	不在第一版实现
native hard realtime	out_of_scope	Web 仿真不实现

5. 每批开发追溯记录模板

后续每批完成后追加：

Batch:
Date:
Files changed:
Feature:
LinuxCNC references:
Boundary:
Tests:
Result:
Remaining risk:
Next:

6. 首批追溯记录

Batch: M0-docs-preparation
Date: 2026-06-20 CST
Files changed:
  README.md
  docs/implementation-plan.md
  docs/technical-roadmap.md
  docs/program-implementation-guide.md
  docs/development-continuation.md
  docs/traceability-matrix.md
  docs/linuxcnc-python-gui-reference.md
  docs/linuxcnc-gui-reference-gallery.md
Feature:
  完成 5 轴数控系统 Web 仿真程序开发前准备文档。
LinuxCNC references:
  gmoccapy_5_axis.png
  qtvismach_5axis_gantry.png
  axis.py
  vismach.py
  xyzac-trt.ini
  xyzbc-trt.ini
  trtfuncs.c
  5axiskins.c
Boundary:
  docs_only
Tests:
  git diff --check -- web-rtcp-5axis-sim-plan
Result:
  ready_for_M1_web_shell_gmoccapy
Remaining risk:
  尚未实现 app 代码；LinuxCNC kinematics WASM ABI 尚未建立。
Next:
  M1-web-shell-gmoccapy

7. M1 追溯记录

Batch: M1-web-shell-gmoccapy
Date: 2026-06-20 CST
Files changed:
  .gitignore
  app/index.html
  app/package.json
  app/tsconfig.json
  app/scripts/build-static.mjs
  app/src/main.js
  app/src/state/store.js
  app/src/ui/gmoccapy-shell.js
  app/src/styles/gmoccapy.css
  tests/browser/gmoccapy_shell_smoke.html
  tests/browser/verify_gmoccapy_shell_browser.sh
Feature:
  实现 gmoccapy 5 轴风格 Web shell，并补齐 M1 build gate。
LinuxCNC references:
  docs/src/gui/images/gmoccapy_5_axis.png
  docs/src/gui/images/qtvismach_5axis_gantry.png
  configs/sim/gmoccapy/gmoccapy_XYZAC.ini
Boundary:
  ui_reference_only
  sourceMode=fixture-ui-only
Tests:
  npm --prefix web-rtcp-5axis-sim-plan/app run build
  web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_shell_browser.sh
  git diff --check -- web-rtcp-5axis-sim-plan
Result:
  gmoccapy_static_build=ok
  gmoccapy_shell_smoke=ok
Remaining risk:
  M1 shell/build gate 已闭环；Three.js 真实场景、LinuxCNC interpreter/WASM、5 轴 kinematics ABI 仍未接入。
Next:
  M2-state-and-controls

8. M2 追溯记录

Batch: M2-state-and-controls
Date: 2026-06-20 CST
Files changed:
  app/package.json
  app/src/profiles/xyzac-trt.js
  app/src/runtime/rtcp-frame.js
  app/src/state/store.js
  app/src/ui/gmoccapy-shell.js
  app/src/styles/gmoccapy.css
  tests/node/verify_rtcp_store.mjs
  tests/browser/gmoccapy_shell_smoke.html
  docs/development-continuation.md
  docs/traceability-matrix.md
Feature:
  实现 gmoccapy store/control 链路，并加入 RTCP fixture frame plumbing。
  Run/Step 会推进 fixture motion frame；TCP/IDENTITY 会切换 RTCP on/off；
  DRO、preview badge 和 info diagnostics 显示 TCP pose、tool axis vector、frame readiness。
  Preview view/Fit/Clear、Rapid/Feed override、Spindle override、Flood/Mist、
  Reload/Home/Full 已接入 store action，并由 node/browser smoke 覆盖。
LinuxCNC references:
  configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
  configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.xml
  configs/sim/axis/vismach/5axis/table-rotary-tilting/switchkins_postgui.hal
  src/emc/kinematics/xyzac-trt-kins.c
  src/emc/kinematics/trtfuncs.c
Boundary:
  sourceMode=fixture-ui-only
  semanticBoundary=fixture_frame_ui_plumbing_not_linuxcnc_kinematics_proof
  linuxCncKinematicsReady=false
  promotionAllowed=false
Tests:
  npm --prefix web-rtcp-5axis-sim-plan/app run build
  npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
  npm --prefix web-rtcp-5axis-sim-plan/app run smoke
Result:
  gmoccapy_static_build=ok
  rtcp_store_smoke=ok
  gmoccapy_shell_smoke=ok
Remaining risk:
  RTCP 当前是 UI/runtime frame plumbing，不是 LinuxCNC/source-derived kinematics WASM proof；
  Three.js 仍是 SVG placeholder，M3 需要接入真实 canvas scene 并消费 rtcpFrame。
Next:
  M3-threejs-preview

9. M3 追溯记录

Batch: M3-threejs-preview
Date: 2026-06-21 CST
Files changed:
  app/src/vendor/three/three.module.js
  app/src/vendor/three/three.core.js
  app/src/visualization/five-axis-scene.js
  app/src/ui/gmoccapy-shell.js
  tests/browser/gmoccapy_shell_smoke.html
  docs/development-continuation.md
  docs/traceability-matrix.md
Feature:
  将 preview 区域从占位内容升级为 Three.js WebGL canvas。
  场景显示基础五轴工作区、工作台、刀具/TCP marker、刀轴和刀路；
  tool marker 消费 store 的 tcpPose，刀轴消费 toolAxisVector，RTCP on/off 影响可见刀轴长度和姿态数据。
LinuxCNC references:
  docs/src/gui/images/qtvismach_5axis_gantry.png
  lib/python/vismach.py
  src/hal/user_comps/vismach/xyzac-trt-gui.py
Boundary:
  visualization_only
  sourceMode=fixture-ui-only
  semanticBoundary=fixture_frame_ui_plumbing_not_linuxcnc_kinematics_proof
Tests:
  npm --prefix web-rtcp-5axis-sim-plan/app run build
  npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
  npm --prefix web-rtcp-5axis-sim-plan/app run smoke
Result:
  gmoccapy_static_build=ok
  rtcp_store_smoke=ok
  gmoccapy_shell_smoke=ok
Remaining risk:
  Three.js 当前消费 fixture frame；五轴运动学仍未接入 LinuxCNC/source-derived WASM。
Next:
  M4-profile-and-linuxcnc-boundary

10. M4 追溯记录

Batch: M4-profile-and-linuxcnc-boundary
Date: 2026-06-21 CST
Files changed:
  app/package.json
  app/src/profiles/xyzac-trt.js
  app/src/profiles/source-reference-map.js
  app/src/panel-schema/xyzac-trt-pyvcp.js
  app/src/runtime/linuxcnc-boundary-adapter.js
  app/src/state/store.js
  app/src/ui/gmoccapy-shell.js
  tests/node/verify_rtcp_store.mjs
  tests/node/verify_profile_boundary.mjs
  tests/browser/gmoccapy_shell_smoke.html
  docs/development-continuation.md
  docs/program-implementation-guide.md
  docs/traceability-matrix.md
Feature:
  建立 `xyzac-trt` profile/source reference map、PyVCP/HAL SWITCHKINS panel schema
  和 LinuxCNC boundary adapter 接入点。store/UI 暴露 boundary readiness，
  并明确保持 `linuxCncKinematicsReady=false`、`promotionAllowed=false`。
  本批后续已进一步按 LinuxCNC `xyzac-trt.ini`、`xyzac-trt_cmds.hal`、
  `switchkins_postgui.hal`、`xyzac-trt.tbl`、`428/429/430remap.ngc` 显式整理
  DISPLAY/RS274NGC/TRAJ、axis/joint limits、HALCMD feedback/offset nets、
  HALUI MDI commands、tool table 和 remap IO 约束，使 M4 在 source-aligned
  profile/schema/adapter 层面完整闭环。
LinuxCNC references:
  configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
  configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.xml
  configs/sim/axis/vismach/5axis/table-rotary-tilting/switchkins_postgui.hal
  configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt_cmds.hal
  configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/428remap.ngc
  configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/429remap.ngc
  configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/430remap.ngc
  src/emc/kinematics/xyzac-trt-kins.c
  src/emc/kinematics/trtfuncs.c
  src/emc/kinematics/switchkins.c
Boundary:
  sourceMapBoundary=profile_source_map_only_not_runtime_proof
  panelSchemaBoundary=pyvcp_hal_schema_reference_only
  adapterBoundary=adapter_entrypoint_only_runtime_not_connected
  linuxCncKinematicsReady=false
  promotionAllowed=false
Tests:
  npm --prefix web-rtcp-5axis-sim-plan/app run build
  npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
  npm --prefix web-rtcp-5axis-sim-plan/app run smoke
Result:
  gmoccapy_static_build=ok
  rtcp_store_smoke=ok
  profile_boundary_smoke=ok
  gmoccapy_shell_smoke=ok
Remaining risk:
  Adapter 目前只是接入点；尚未连接 LinuxCNC interpreter/kinematics WASM ABI。
Next:
  linuxcnc_kinematics_wasm_abi

11. M5 追溯记录

Batch: M5-operator-program-workflow
Date: 2026-06-21 CST
Files changed:
  app/src/state/store.js
  app/src/ui/gmoccapy-shell.js
  app/src/styles/gmoccapy.css
  tests/node/verify_rtcp_store.mjs
  tests/browser/gmoccapy_shell_smoke.html
  docs/development-continuation.md
  docs/traceability-matrix.md
Feature:
  补齐 operator workflow：上电、急停、AUTO/MANUAL/JOG/MDI、复位、
  本地 G-code 文件加载、刀具预览、程序执行当前行显示和高亮。
LinuxCNC references:
  gmoccapy operator workflow
  AXIS program loading/current-line workflow
  vismach tool preview conventions
Boundary:
  operatorWorkflowBoundary=browser_ui_runtime_fixture
  gcodeLoadBoundary=file_text_staging_only
  programExecutionBoundary=fixture_line_playback_not_linuxcnc_interpreter
  linuxCncKinematicsReady=false
  promotionAllowed=false
Tests:
  npm --prefix web-rtcp-5axis-sim-plan/app run build
  npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
  npm --prefix web-rtcp-5axis-sim-plan/app run smoke
Result:
  gmoccapy_static_build=ok
  rtcp_store_smoke=ok
  profile_boundary_smoke=ok
  gmoccapy_shell_smoke=ok
Remaining risk:
  程序执行仍是 fixture line playback；下一步必须接 LinuxCNC interpreter/WASM 或
  source-derived kinematics WASM，才能把执行来源升级为 LinuxCNC-owned。
Next:
  linuxcnc_interpreter_or_kinematics_wasm_execution_source

12. M6 追溯记录

Batch: M6-linuxcnc-kinematics-frame-proof
Date: 2026-06-21 CST
Files changed:
  app/package.json
  app/src/runtime/linuxcnc-kinematics-runtime.js
  app/src/runtime/linuxcnc-boundary-adapter.js
  app/src/runtime/rtcp-frame.js
  app/src/state/store.js
  tests/node/verify_linuxcnc_kinematics_runtime.mjs
  tests/node/verify_rtcp_store.mjs
  tests/node/verify_profile_boundary.mjs
  docs/program-implementation-guide.md
  docs/development-continuation.md
  docs/traceability-matrix.md
Feature:
  将 RTCP frame/boundary adapter 从 fixture-only 接到
  createLinuxCncKinematicsSdk({ moduleId: "xyzac-trt" })。
  新增 web runtime adapter，只加载共享 wasm-port SDK 并返回 LinuxCNC
  forward/inverse 结果；frame builder 使用 forward.pose 和 inverse.joints
  生成 source-derived kinematics frame。
LinuxCNC references:
  wasm-port/runtime/sdk/src/linuxcnc-kinematics.js
  wasm-port/build/wasm/kinematics/linuxcnc_xyzac_trt_kinematics.wasm
  src/emc/kinematics/xyzac-trt-kins.c
  src/emc/kinematics/trtfuncs.c
  src/emc/kinematics/switchkins.c
Boundary:
  sourceMode=source-derived-kinematics-wasm
  semanticBoundary=linuxcnc_kinematics_wasm_c_abi
  linuxCncKinematicsReady=true
  kinematicsFramePromotionAllowed=true
  fullLinuxCncProgramExecutionReady=false
  browserFallback=fixture-ui-only
Tests:
  npm --prefix web-rtcp-5axis-sim-plan/app run build
  npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
  npm --prefix web-rtcp-5axis-sim-plan/app run smoke
Result:
  gmoccapy_static_build=ok
  linuxcnc_kinematics_runtime_smoke=ok
  rtcp_store_smoke=ok
  profile_boundary_smoke=ok
  gmoccapy_shell_smoke=ok
Remaining risk:
  Browser path still runs fixture fallback because kinematics WASM asset copy/worker
  is not wired into app/src/main.js. Program RUN/STEP still advances fixture lines;
  LinuxCNC interpreter/remap/planner execution is not promoted.
Next:
  browser_kinematics_wasm_asset_worker_or_interpreter_execution_source