按关节槽位驱动 13 个五轴案例的三维模型

关节契约扩为槽位制：以 LinuxCNC 联合号标识关节，轴字母降为槽位属性，重复轴（bridge-mill 的两个 Y）、并联杆长（hexapod/pentapod）和被动槽位（max5 第 6 关节）都能表达。v1 规则保持不变并合成 jointOrder，已保存 GLB 与既有测试不受影响。 13 个结构 GLB 由 scripts/generate_physical_case_glbs.mjs 统一重建，可动关节均为按槽位命名的 Group 并写 userData.linuxcncJoint，共 71 个关节，槽位数与运行目录的 joint_count 逐条一致。新增 machine-visual-bindings.json 与纯函数模块，以 machine id 为键：坐标字母不能作键，因为三个案例共用 XYZAB、三个共用 XYZABC。主界面切换案例时自动装载对应模型，失败时保留内置模型并显式提示。消除前端五关节截断：visual 适配器的 joints 改为数组并新增 jointsAuthoritative；allHomed 按 joint_count 判断；面板按 worker 断言的 machine id 查找机型。管理器解锁：坐标与案例下拉以"存在完整视觉绑定"为启用条件，13 案例全部可选；machine-urdf.ts 新增 generic-wasm/1 profile，AC/BC 严格校验路径不变；新增 machine-kinematics-specs.json 保存逐关节限位，INI 未声明的限位保持 null 而不编造。修复三个真实缺陷：构建漏发 woodpecker/gmoccapy/qtdragon 配置目录（ DEFECT-02 根因）；案例切换沿用"装载需要已上电"的门控，导致关机状态下第二次切换被静默拒绝；重复轴机型上 React 列表键冲突。验收：13 案例逐个切换装载成功、槽位键与绑定定义逐一一致、浏览器错误 0； typecheck 与生产构建通过；视觉绑定、GLB 命名、关节契约、投影、store、双画布、运动学规格漂移、11 案例 Worker 闭环、管理器浏览器回归全部通过。证据在 coverage/glb-machine-manager/physical-drive/。 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-30 06:09:12 +08:00
parent af65b69b2c
commit db29ae625f
157 changed files with 11936 additions and 885 deletions
--- a/docs/user-manual/deployment-test.report.json
+++ b/docs/user-manual/deployment-test.report.json
@@ -0,0 +1,364 @@
+{
+  "report_id": "LINUXCNC-WEB-DEPLOYED-MANUAL-TEST",
+  "url": "https://49.232.250.35:58010/",
+  "checked_at": "2026-10-08T10:52:07.892Z",
+  "status": "verified",
+  "passed": 26,
+  "failed": 0,
+  "results": [
+    {
+      "name": "打开线上站点并等待 WASM 会话就绪",
+      "status": "pass",
+      "ms": 20508,
+      "detail": {
+        "title": "LinuxCNC Web/WASM",
+        "canvases": 2,
+        "cases": 13
+      }
+    },
+    {
+      "name": "状态栏、轴位与实时参数由 LinuxCNC WASM 驱动",
+      "status": "pass",
+      "ms": 542,
+      "detail": {
+        "live": "linuxcnc-wasm",
+        "axes": [
+          "0.0000",
+          "0.0000",
+          "0.0000",
+          "0.000",
+          "0.000"
+        ],
+        "status": "Task mode MANUAL Task state STATE_ESTOP_RESET Interpreter INTERP_IDLE Motion mode FREE Motion type 0 Homing IDLE Machine"
+      }
+    },
+    {
+      "name": "Help 菜单可打开 About 对话框",
+      "status": "pass",
+      "ms": 5995,
+      "detail": "LinuxCNC AXIS Web/WASM XYZAC TRT OK"
+    },
+    {
+      "name": "File 菜单把宿主边界项正确置灰",
+      "status": "pass",
+      "ms": 2899,
+      "detail": [
+        true,
+        true
+      ]
+    },
+    {
+      "name": "RTCP 程序库按机型过滤并列出可加载程序",
+      "status": "pass",
+      "ms": 5690,
+      "detail": {
+        "options": 16,
+        "summary": "AC（XYZAC） 程序 当前分类：16 个 可直接加载：9 LinuxCNC 源程序：32 个 · 含案例干运行程序共 45 个",
+        "scopes": [
+          "当前 AC（XYZAC） 机床",
+          "全部 45 个程序"
+        ]
+      }
+    },
+    {
+      "name": "导入机床模型对话框列出内置示例与下载入口",
+      "status": "pass",
+      "ms": 5585,
+      "detail": {
+        "downloads": 4,
+        "summary": "三维机床模型 × 三维机床 内置模型 导入 GLB AC 示例 下载 AC BC 示例 下载 BC AC 示例桁架型 下载 AC桁架型 BC 示例桁架型 下载 BC桁架型 单个 GLB，包含层级模型及 URDF，最大 64 MiB"
+      }
+    },
+    {
+      "name": "三维机床管理四个步骤页签可切换",
+      "status": "pass",
+      "ms": 19399,
+      "detail": [
+        "部件与层级 0 节点 展开 折叠 导入机床或部件后显示 GLB 内部层级。 选择层级节点，配置其唯一自由度。",
+        "跟随数控系统实时关节位置 手动验证（相对物理零点） 层级运动测试 复位 X mm Y mm Z mm A deg C deg 这些输入仅验证",
+        "机床标定 C 轴原点 (mm) X Y Z A 到 C 轴偏置 (mm) X Y Z 机床物理零点（按当前坐标，直线 mm / 旋转 deg",
+        "机床文档 模型名称 设计说明 LinuxCNC 五轴案例库 13 个结构/运动学案例 案例来源于仓库内 LinuxCNC 配置、示例 G 代"
+      ]
+    },
+    {
+      "name": "机床参数对话框显示旋转中心与轴间偏置字段",
+      "status": "pass",
+      "ms": 5161,
+      "detail": 6
+    },
+    {
+      "name": "案例切换到 XYZBC 后机型与轴组同步改变",
+      "status": "pass",
+      "ms": 40918,
+      "detail": {
+        "axes": [
+          "X",
+          "Y",
+          "Z",
+          "B",
+          "C"
+        ],
+        "back": [
+          "X",
+          "Y",
+          "Z",
+          "A",
+          "C"
+        ]
+      }
+    },
+    {
+      "name": "急停复位并可上电",
+      "status": "pass",
+      "ms": 1791,
+      "detail": "Task mode MANUAL Task state STATE_ON Interpreter INTERP_IDLE Motion mode FREE Motion type 0 Homing IDLE Machine sequence"
+    },
+    {
+      "name": "HOME ALL 完成全部关节回零",
+      "status": "pass",
+      "ms": 2910,
+      "detail": "Task mode MANUAL Task state STATE_ON Interpreter INTERP_IDLE Motion mode TELEOP Motion type 0 Homing IDLE Machine sequen"
+    },
+    {
+      "name": "连续 Jog：按住 X 正向位置变化，松手停止",
+      "status": "pass",
+      "ms": 7696,
+      "detail": {
+        "before": "0.0000",
+        "after": "0.9075"
+      }
+    },
+    {
+      "name": "增量 Jog：0.1000 步长按一次步进",
+      "status": "pass",
+      "ms": 6327,
+      "detail": {
+        "before": 0.9075,
+        "after": 0.8075
+      }
+    },
+    {
+      "name": "主轴启停与冷却液开关可用",
+      "status": "pass",
+      "ms": 13600,
+      "detail": {
+        "mistOn": true,
+        "mistOff": true,
+        "live": "Live parameters LinuxCNC WASM Spindle 1.0 rpm Cmd 1.0 rpm / S 0.0 rpm Feed actual 0.0 mm/min Program 0.0 mm/mi"
+      }
+    },
+    {
+      "name": "MDI 指令执行并写入历史",
+      "status": "pass",
+      "ms": 7596,
+      "detail": "G0 X12.5 Y-4 Z0"
+    },
+    {
+      "name": "DRO 视图可切换坐标、显示与单位",
+      "status": "pass",
+      "ms": 6126,
+      "detail": {
+        "rows": 5,
+        "footer": "Units: inch / deg relative / commanded Tick: 144 Hash: fnv1a64:0780"
+      }
+    },
+    {
+      "name": "倍率滑块与预览图层开关可用",
+      "status": "pass",
+      "ms": 4898,
+      "detail": "Jog Speed: 100% Feed Override: 80% Spindle Override: 100% Max Velocity: 100% Rapid Override Unavailable path live limits velocity offsets extents"
+    },
+    {
+      "name": "工具栏『载入精确案例』按钮重新载入当前案例",
+      "status": "pass",
+      "ms": 19213,
+      "detail": "Program: boat-xyzac.ngc"
+    },
+    {
+      "name": "载入案例程序并运行、暂停、继续、停止",
+      "status": "pass",
+      "ms": 38054,
+      "detail": {
+        "running": "Task mode AUTO Task state STATE_ON Interpreter INTERP_READING Motion mode COORD Motion type 0 Homing",
+        "paused": "Task mode AUTO Task state STATE_ON Interpreter INTERP_PAUSED Motion mode COORD Motion type 1 Homing ",
+        "stopped": "Task mode MANUAL Task state STATE_ON Interpreter INTERP_IDLE Motion mode TELEOP Motion type 0 Homing"
+      }
+    },
+    {
+      "name": "RTCP 程序库『加载到控制器』可用",
+      "status": "pass",
+      "ms": 11529,
+      "detail": "程序已加载到 LinuxCNC WASM 控制器"
+    },
+    {
+      "name": "工具栏『打开 G 代码文件』可装载本地 .ngc",
+      "status": "pass",
+      "ms": 3960,
+      "detail": "Program: xyzac-trt.ngc"
+    },
+    {
+      "name": "工具栏『重载当前程序』可用",
+      "status": "pass",
+      "ms": 5257,
+      "detail": "Task mode MANUAL Task state STATE_ON Interpreter INTERP_IDLE Motion mode TELEOP Motion type 0 Homing IDLE Mach"
+    },
+    {
+      "name": "工具栏视图按钮与清除轨迹可用",
+      "status": "pass",
+      "ms": 10442,
+      "detail": {
+        "pressed": "true"
+      }
+    },
+    {
+      "name": "诊断页显示启动资源与门控",
+      "status": "pass",
+      "ms": 3151,
+      "detail": "TASK_READY Tick 324 Hash fnv1a64:8cadf3b1b75faa04 Startup resources Entrypoint: linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt"
+    },
+    {
+      "name": "快捷键 F1 / F3 / F5 生效",
+      "status": "pass",
+      "ms": 5683,
+      "detail": {
+        "estopTriggered": true,
+        "manualSelected": "true",
+        "mdiSelected": "true"
+      }
+    },
+    {
+      "name": "窄视口 390x844 无横向溢出",
+      "status": "pass",
+      "ms": 3884,
+      "detail": {
+        "overflow": 0
+      }
+    }
+  ],
+  "defects": [
+    {
+      "id": "DEFECT-02",
+      "severity": "high",
+      "control": "Simulation case 下拉框中的通用运动学案例",
+      "observed": "xyzab-tdr、max5-maxkins、trivkins-xyzya、hexapod-genhexkins、scorbot-kins 载入后控制器停在 PENDING，电源按钮保持禁用（linuxcnc_wasm_snapshot_pending），此时下拉框无法切回其它案例，只能刷新页面恢复",
+      "expected": "选中案例后可上电、回零并运行其干运行程序",
+      "root_cause": "通用案例运行链在浏览器侧尚未完成：案例的运动学源文件（如 linuxcnc/src/emc/kinematics/trivkins.c、linuxcnc/src/hal/components/xyzab_tdr_kins.comp）没有随前端产物发布，请求返回 404；且会话启动失败后前端不回滚，卡在 pending",
+      "workaround": "当前只使用 XYZAC TRT / XYZBC TRT 两个案例；误选其它案例后刷新浏览器页面"
+    }
+  ],
+  "case_matrix": [
+    {
+      "id": "xyzac-trt",
+      "applied": true,
+      "power": "enabled",
+      "state": "Task mode MANUAL Task state STATE_ESTOP_RESET Interpreter INTERP_IDLE Motion mode FREE Mot",
+      "http_4xx": [],
+      "verdict": "usable"
+    },
+    {
+      "id": "xyzbc-trt",
+      "applied": true,
+      "power": "enabled",
+      "state": "Task mode MANUAL Task state STATE_ESTOP_RESET Interpreter INTERP_IDLE Motion mode FREE Mot",
+      "http_4xx": [],
+      "verdict": "usable"
+    },
+    {
+      "id": "xyzab-tdr",
+      "applied": true,
+      "power": "disabled:linuxcnc_wasm_snapshot_pending",
+      "state": "Task mode PENDING Task state PENDING Interpreter PENDING Motion mode PENDING Motion type -",
+      "http_4xx": [
+        "404 /linuxcnc/src/hal/components/xyzab_tdr_kins.comp"
+      ],
+      "verdict": "loads_but_controller_pending"
+    },
+    {
+      "id": "max5-maxkins",
+      "applied": true,
+      "power": "disabled:linuxcnc_wasm_snapshot_pending",
+      "state": "Task mode PENDING Task state PENDING Interpreter PENDING Motion mode PENDING Motion type -",
+      "http_4xx": [],
+      "verdict": "loads_but_controller_pending"
+    },
+    {
+      "id": "trivkins-xyzya",
+      "applied": true,
+      "power": "disabled:linuxcnc_wasm_snapshot_pending",
+      "state": "Task mode PENDING Task state PENDING Interpreter PENDING Motion mode PENDING Motion type -",
+      "http_4xx": [
+        "404 /linuxcnc/src/emc/kinematics/trivkins.c"
+      ],
+      "verdict": "loads_but_controller_pending"
+    },
+    {
+      "id": "hexapod-genhexkins",
+      "applied": true,
+      "power": "disabled:linuxcnc_wasm_snapshot_pending",
+      "state": "Task mode PENDING Task state PENDING Interpreter PENDING Motion mode PENDING Motion type -",
+      "http_4xx": [
+        "404 /linuxcnc/src/emc/kinematics/genhexkins.c"
+      ],
+      "verdict": "loads_but_controller_pending"
+    },
+    {
+      "id": "scorbot-kins",
+      "applied": true,
+      "power": "disabled:linuxcnc_wasm_snapshot_pending",
+      "state": "Task mode PENDING Task state PENDING Interpreter PENDING Motion mode PENDING Motion type -",
+      "http_4xx": [
+        "404 /linuxcnc/src/emc/kinematics/scorbot-kins.c"
+      ],
+      "verdict": "loads_but_controller_pending"
+    }
+  ],
+  "console_errors": [
+    {
+      "kind": "console",
+      "text": "Failed to load resource: the server responded with a status of 404 (Not Found)"
+    },
+    {
+      "kind": "console",
+      "text": "Failed to load resource: the server responded with a status of 404 (Not Found)"
+    },
+    {
+      "kind": "console",
+      "text": "Failed to load resource: the server responded with a status of 404 (Not Found)"
+    },
+    {
+      "kind": "console",
+      "text": "Failed to load resource: the server responded with a status of 404 (Not Found)"
+    }
+  ],
+  "http_and_request_failures": [
+    "HTTP 404 https://49.232.250.35:58010/linuxcnc/src/hal/components/xyzab_tdr_kins.comp",
+    "HTTP 404 https://49.232.250.35:58010/linuxcnc/src/emc/kinematics/trivkins.c",
+    "HTTP 404 https://49.232.250.35:58010/linuxcnc/src/emc/kinematics/genhexkins.c",
+    "HTTP 404 https://49.232.250.35:58010/linuxcnc/src/emc/kinematics/scorbot-kins.c"
+  ],
+  "screenshots": [
+    "01-main-overview.png",
+    "02-about-dialog.png",
+    "03-file-menu.png",
+    "04-rtcp-program-library.png",
+    "05-machine-import-dialog.png",
+    "06-machine-manager-structure.png",
+    "07-machine-manager-motion.png",
+    "08-machine-manager-calibration.png",
+    "09-machine-manager-files.png",
+    "10-geometry-parameters.png",
+    "11-case-xyzbc.png",
+    "12-manual-homed.png",
+    "13-manual-jog.png",
+    "14-spindle-coolant.png",
+    "15-mdi.png",
+    "16-dro.png",
+    "17-overrides-layers.png",
+    "18-program-running.png",
+    "19-program-paused.png",
+    "22-rtcp-load.png",
+    "23-views-cleared.png",
+    "20-diagnostics.png",
+    "21-mobile-390.png"
+  ]
+}