cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/working/02-项目程序开发详细步骤.md

02-项目程序开发详细步骤

步骤

1. 读取 doc/xyzbc-trt-runtime-files.md，确认 LinuxCNC 进程、INI、PyVCP、POSTGUI HAL、Vismach、remap、tool table、parameter file 的运行关系。
2. 读取 wasm-port/AGENTS.md 和 wasm-port/SKILL.md，确认必须复用 LinuxCNC 源码语义，Web 只做 UI/OPFS/运行边界适配。
3. 检查 wasm-port 是否包含 xyzbc-trt：确认 SDK、probe、vendored configs、remap harness 已覆盖。
4. 复制参考 Web app 到目标目录：

web-rtcp-5axis-xyzbc-trt-sim-plan/app
web-rtcp-5axis-xyzbc-trt-sim-plan/tests

5. 将目标 app 默认机型改为 xyzbc-trt：

app/src/state/store.js
app/src/profiles/index.js
app/src/runtime/linuxcnc-kinematics-runtime.js
app/src/runtime/linuxcnc-kinematics-worker-client.js
app/src/main.js

6. 将 OPFS/session/tool-db 根路径改为目标项目命名空间：

web-rtcp-5axis-xyzbc-trt-sim-plan/machines
web-rtcp-5axis-xyzbc-trt-sim-plan/sessions
web-rtcp-5axis-xyzbc-trt-sim-plan/tool-db

7. 为 xyzbc-trt profile 增加默认机器文件 staging：

machineFileStaging: {
  defaultProgramFilename: "xyzbc_switchkins.ngc",
  wasmDir: "/work/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt",
}

8. 新增目标项目 Node smoke：

tests/node/verify_xyzbc_trt_web_app.mjs

9. 创建工作文档：

working/01-项目功能内容.md
working/02-项目程序开发详细步骤.md
working/03-推进台账.md
working/04-任务矩阵.md
working/05-验收证据.md
working/06-决策记录.md
working/07-全量对标追踪矩阵.md
working/README.md

10. 按 07-全量对标追踪矩阵.md 继续补齐 Web 对标功能：

AXIS 等效界面
PyVCP/POSTGUI HAL 等效连接
basic_sim task/HAL 等效运行
Vismach xyzbc-trt-gui.py 等效 3D 模型
Ngcgui/remap 子程序全集 staging 和执行
TRAJ/AXIS/JOINT 限制、速度、单位和 override
tool table/tool offset 对 kinematics 和模型的双向影响
native/Web JSON 全字段对比

11. 切换 native 真实执行基线到 /home/mes123456/cnc_wams/linuxcnc：

test -x /home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment
test -x /home/mes123456/cnc_wams/linuxcnc/bin/axis
test -x /home/mes123456/cnc_wams/linuxcnc/bin/xyzbc-trt-gui
test -f /home/mes123456/cnc_wams/linuxcnc/rtlib/xyzbc-trt-kins.so
test -f /home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini

验收要求：

• 上述文件存在后，native 采集脚本统一使用 /home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment。
• 真实执行命令的 INI 必须是 /home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini。
• Web 界面布局、状态流、switchkins 逻辑、Vismach 等效模型、刀具路径和 JSON 字段都以该路径实际执行结果为准。
• /home/mes123456/linuxcnc-master 只能作为历史运行参考，不再作为新的 native evidence 基线。

后续完整验收步骤

1. 生成 WASM artifact：

source /home/mes123456/emsdk/emsdk_env.sh
wasm-port/tools/build_kinematics_wasm.sh
wasm-port/tools/build_wasm_core.sh
wasm-port/tools/build_tp_wasm.sh
wasm-port/tools/build_task_hal_wasm.sh

2. 运行 wasm-port 对应验证：

wasm-port/tests/wasm/node/verify_kinematics_wasm.sh
wasm-port/tests/wasm/node/verify_interp_wasm.sh
wasm-port/tests/wasm/node/verify_task_hal_wasm.sh
wasm-port/tests/browser/verify_interp_browser.sh

3. 运行目标 app 验证：

npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run smoke:node
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run build

4. 生成 native/Web 对比证据：

/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment \
  python3 web-rtcp-5axis-xyzbc-trt-sim-plan/tools/collect-native-xyzbc-trt-evidence.py --run --timeout 90
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:web
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:compare

输出：

web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/native-xyzbc-trt-evidence.json
web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/web-xyzbc-trt-evidence.json
web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/compare-xyzbc-trt-evidence.json

5. 补充刀具预览路径和刀具执行路径采集：

tools/collect-native-xyzbc-trt-evidence.py
tools/collect-web-xyzbc-trt-evidence.mjs
tools/compare-xyzbc-trt-evidence.mjs

实现要求：

• 在 native evidence 中增加 pathSampling、previewPath、executionPath。
• 在 Web evidence 中增加同名字段，字段结构必须与 native 完全一致。
• 统一对比采样周期暂定为 samplePeriodMs = 50。
• 采集脚本可保留原始高频/低频轨迹，但写入对比 JSON 的曲线必须重采样到 50ms。
• 预览路径从 LinuxCNC preview/canon 或 Web preview planner 采集；执行路径从 LinuxCNC stat()/HAL 反馈或 Web task/HAL runtime 采集。
• 每个样本必须包含 sampleIndex、timeMs、line、motionType、activeKinematics、tool、joint、tcp、toolAxis、feed、spindle。
• 对 B/C 旋转轴和 TCP/toolAxis 的计算必须以 xyzbc-trt kinematics/WASM 结果为准，不能用 UI 插值伪造。

6. 补充刀路 compare 规则：

{
  "pathComparison": {
    "samplePeriodMs": 50,
    "previewVsPreview": {},
    "executionVsExecution": {},
    "previewVsExecutionNative": {},
    "previewVsExecutionWeb": {}
  }
}

验收要求：

• compare-xyzbc-trt-evidence.json 中新增 pathComparison。
• checks 中新增 path-preview、path-execution、path-preview-execution-consistency 类别。
• 每类检查至少输出 maxTcpErrorMm、rmsTcpErrorMm、maxJointError、rmsJointError、maxToolAxisAngleDeg、sampleCountDelta、missingSamples。
• 若 native/Web 两侧采样周期不一致，compare 必须直接 fail，并输出实际周期。
• 若 WASM artifact 缺失导致 Web 执行路径无法采集，compare 必须保持 fail/blocker，不能用预览路径替代执行路径。

7. 补充全量对标 JSON 字段：

{
  "startupSequence": [],
  "iniDisplay": {},
  "halNets": [],
  "kinematicsPins": {},
  "axisJointLimits": {},
  "switchkinsTransitions": [],
  "uiEquivalence": {},
  "vismachEquivalent": {},
  "ngcguiSubroutines": [],
  "demoPrograms": []
}

验收要求：

• startupSequence 对标 .desktop -> rip-environment -> linuxcncsvr/rtapi_app/milltask/halui -> basic_sim -> kinematics -> Vismach -> AXIS -> PyVCP -> POSTGUI HAL -> OPEN_FILE。
• halNets 覆盖 motion.switchkins-type、halui.mdi-command-*、pyvcp.*、joint.N.pos-fb、motion.tooloffset.z、xyzbc-trt-kins.*。
• kinematicsPins 覆盖 x-offset=-20、z-offset=-15、x/y/z-rot-point=0、conventional-directions=0、tool-offset。
• axisJointLimits 覆盖 XYZBC 单位、关节数、B/C 角轴限制、TRAJ 速度/加速度。
• uiEquivalence 覆盖 AXIS 主界面的程序区、坐标区、MDI/switchkins、override、工具、状态、预览/执行路径。
• vismachEquivalent 覆盖 xyzbc-trt-gui.py 的模型 pin 和清除轨迹行为。
• ngcguiSubroutines 覆盖 xyzbc_switchkins_sub.ngc、centering.ngc、helix_bc.ngc。
• demoPrograms 覆盖 xyzbc_switchkins.ngc 和 boat-xyzbc.ngc。

8. 启动目标 Web：

cd web-rtcp-5axis-xyzbc-trt-sim-plan/app
npm run dev

默认 URL：

http://127.0.0.1:4174/

当前执行状态：

• 2026-07-05 18:08 EDT 已按上述验收链重新执行 native/Web/compare/build/smoke。
• 最新 native evidence：status=ok、coverage=35/35、executionMode=auto-run。
• 最新 Web evidence：status=ready-for-wasm-runtime、coverage=49/49、blockers=[]。
• 最新 compare：status=pass、checkCount=60、passCount=60、failCount=0、blockers=[]、requiredImprovements=[]。
• 后续任何实现、文档规则、staging 文件、WASM artifact、采集脚本或 UI 行为变更后，都必须重新执行本节第 4 步的 native/Web/compare 证据链，并补跑 npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run build、smoke:node、smoke:browser。

截图真实执行过程修复步骤

9. 针对 working/screenshots/web-simulation-full-process-20260703T051258Z 暴露的问题，页面层新增真实执行过程派生链：

app/src/runtime/axis-preview-path.js
app/src/state/store.js
app/src/ui/axis-shell.js
app/src/styles/axis.css
tests/node/verify_xyzbc_trt_web_app.mjs
tests/browser/xyzbc_trt_browser_smoke.html

实现要求：

• programAxisPreviewPath.samples[] 写入 sourceFile、statement、segmentIndex，样本来源必须是 xyzbc_switchkins_sub.ngc/helix_bc.ngc 展开后的真实源程序。
• store 中新增 programUiExecution，由当前 50ms 样本派生 sourceFile:line、operation、sample index、statement、joint、tcp、toolAxis、machineState。
• RUN/STEP/RUN_FRAME/task-HAL 状态应用必须统一调用样本派生逻辑，不能分别维护刀位、刀轴和当前行。
• state.toolAxisVector 必须从当前样本 toolAxis.i/j/k 派生，Three.js 刀头、刀轴线和 Vismach 刀杆方向共享该向量。
• 程序区必须显示实时执行条，监控面板必须显示当前展开源文件和源行。
• browser smoke 必须断言 DOM dataset、state、canvas data-three-tool-axis 三者一致。