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 到目标目录：

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

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

```text
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 根路径改为目标项目命名空间：

```text
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：

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

8. 新增目标项目 Node smoke：

```text
tests/node/verify_xyzbc_trt_web_app.mjs
```

9. 创建工作文档：

```text
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 对标功能：

```text
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`：

```bash
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：

```bash
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 对应验证：

```bash
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 验证：

```bash
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 对比证据：

```bash
/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
```

输出：

```text
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. 补充刀具预览路径和刀具执行路径采集：

```text
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 = 20`。
- 采集脚本可保留原始高频/低频轨迹，但写入对比 JSON 的曲线必须重采样到 20ms。
- 预览路径从 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 规则：

```json
{
  "pathComparison": {
    "samplePeriodMs": 20,
    "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 字段：

```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：

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

默认 URL：

```text
http://127.0.0.1:4174/
```