linuxcncWebWASM/docs/glb-machine/03-推进台账.md

推进台账

R09 / 2026-09-18 / 初学者工件坐标与 G 代码完整讲义

• 用户要求在RTCP课件基础上系统扩充工件坐标：坐标含义、原点和方向确定、G代码逐值解析与运动，整个讲义面向初学者。
• 新增 docs/teaching/rtcp-beginners/，72页A4完整教材，约2.6万正文字符；保留原31页投影概要。新书以坐标尺子入门，区分M/W/J/K/T，再讲工件原点测量、初始方向、G54配准和动态RTCP，最后进入完整程序与实验/答案。
• 核心细化：物理固连工件架与G54偏置表不同；本课G54是零位配准输入，动态方向与原点由运动学继续变换。解释G10 L2/L20、G90/G91、单位、F与其他字的上下文，明确普通坐标旋转和完整刀补不等于自动RTCP。
• 新增六个生成/验证脚本：generate_rtcp_beginner_data.mjs、generate_rtcp_beginner_figures.py、generate_rtcp_beginner_html.py、subset_rtcp_beginner_fonts.py、render_rtcp_beginner_pdf.mjs、verify_rtcp_beginner_pdf.py。
• 数值实测：o=(40,20,10)、BC、P=D=L=0。11个主段、11个额外单位/G54-G55/L20段核对；N10–N90加M2通过实际解释器/TP/WASM执行完成，53个采样，终点与逐行结果一致。M429/M428另按保持物理关节接口核对。
• 图像：9张新增原创坐标图，复用11张旧原创图；72页逐页边界/图片/标题检查和Poppler独立渲染检查。字体同形部首导致复制字符不符的问题，通过按实际字符制作Noto SC子集解决；保留字体许可，严格检查所有72页标题可正确提取。
• 记录能力边界：本项目解释器是功能切片，完整G43/H刀表、G52/G92、任意方向和所有进给模式不在本次全面验收范围；以官方语义讲解时明确区分，未把“解析接受”当成完整实现。
• 验证见E13，文件含目录/书签、HTML源稿、测试数据、教学NGC与复现步骤。未修改运行功能，原本地改动、旧PDF和历史证据保留；未提交/推送。
• 下一步：教材已完整交付，按后续教学内容修订需求推进。

R08 / 2026-09-18 / 五轴与 RTCP 教学 PDF

• 用户要求完善“非RTCP各轴独立”和“RTCP坐标随转台变换、刀尖跟随”的理解，提供图文教学课件。
• 新增 docs/teaching/rtcp-five-axis/：31页16:9中文PDF、可编辑HTML、9张原创原理图、2张无界面控件的桁架模型图、数值报告、目录与逐页验证。
• 明确范围：XYZ加AC或BC；独立驱动不等于不能协调插补；程序坐标须经过单位/增量/零点/刀补；RTCP不仅改变方向，还处理中心/偏置/刀长；模式切换应固定物理关节。加入非RTCP后置计算、TCP/倾斜平面差异、限位与版本化M码说明。
• 生成脚本：generate_rtcp_teaching_data.mjs、generate_rtcp_teaching_figures.py、capture_rtcp_teaching_models.mjs、generate_rtcp_teaching_html.py、render_rtcp_teaching_pdf.mjs、verify_rtcp_teaching_pdf.py。
• 验证 E12：真实WASM十二个姿态正逆解、方向增量/切换算例；31页DOM边界和图片加载检查；Poppler独立渲染所有PDF页并目视检查；PyPDF核验31页、16:9、中文文本、字体自包含、39个书签。
• 中间排版修正：两页接近/越过页脚，调整公式和图形间距后严格边界检查通过；字体检查增加对Chrome嵌入Type3字形程序的正确识别，pdffonts也确认emb=yes。没有改应用功能或覆盖前轮证据。
• 下一步：课件可直接教学，按后续内容修订需求更新。原有本地改动保留，本轮未提交/推送。

R07 / 2026-09-18 / Jog 限位与序列恢复、阴影警告

• 用户截图：XYZBC B=50.2275°，Connection: ERROR / event_sequence_gap。配置 AXIS_B 范围大，但 JOINT_3 上限=50°；连续 Jog 只以坐标限位作为目标，越过关节限位后原生 FK 返回 -702。首次 Worker 复现得到 SIM_STEP: wasm_xyzac_forward_-702。
• 第二层根因：SIM_STEP 执行前把请求的未来 tick 写入事件日志，实际在较早 tick 失败；下一命令发生 tick 回退，未写事件而协议已消费序号，再下一命令出现 sequence_gap。
• wasm-linuxcnc-tp.mjs：对于能直接映射关节的坐标，Jog 临时采用 AXIS/JOINT 限位交集，原生 TP 计算目标和减速，随后恢复正常坐标限位。RTCP 耦合的 XYZ 关节由真实 WASM IK/FK 在每个伺服样本检查；越界则取消剩余轨迹并回到上一个有效样本，发布限位停止而不是继续越界。
• sim-session.mjs：SIM_STEP 完成/失败后写入实际 tick；成功时仍在 checkpoint 前完成事件记录。调度异常时停止运动，并同步协议/任务时钟。sim-scheduler.mjs 中异常保留已尝试 tick，同步 native scheduler，未执行的未来周期不再占用时钟。
• UI 将限位拒绝标为 blocked，与 Worker 连接故障区分；Jog 采样出错显示具体原因。到限位后 JOG_STOP、反向 Jog、SNAPSHOT_REQUEST、checkpoint/恢复均可继续。
• 用户补充控制台截图仅为 PCFSoftShadowMap 弃用提示，与事件故障无关；XyzacMachineView 改为 PCFShadowMap，Chrome 再测 warnings=[]。
• 验证 E11：两机型直接旋转轴50°限位/反向退出、RTCP引发Y接近100mm限位/反向退出、失败后序号及原生事件游标一致、部分tick、无效cycles、checkpoint恢复通过。真实浏览器两机型反复Jog、松开停止、限位后再次运动/画面非空通过；120个精确恢复续跑样本、五轴程序、单步、基础session/scheduler/replay及生产构建通过。
• 旧 test_xyzac_manual_control.mjs 在回零尚未完成时期待 homed_mask=1，旧 test_xyzac_button_constraints.mjs 期待关机优先而得到 not_all_homed；使用只读 HEAD 模块加载器复核也在相同断言失败，保留日志，未修改门控或放宽断言。
• 证据归入 coverage/glb-machine/jog-limits/，不改此前证据、上游、本地trace/图片/临时文件。无 C/WASM 变更，无需重建原生核心。本轮及前轮变更仍未提交/推送。
• 下一步：专项收口；已进入旧序号错误的浏览器会话需刷新，重新导入模型并回零，不能伪造缺失事件来修补旧会话。

R06 / 2026-09-18 / AC、BC 参数化桁架示例

• 用户要求保留 AC/BC 示例，新增 AC/BC 桁架型，结构为底座→X→Y→Z、底座→A/B→C。
• 原 AC/BC 导入示例已经采用双链，但存在 Z→主轴箱固定 link。本轮桁架型独立 profile trt-xyz-gantry/1，七 link、六 joint、五运动轴，tool 直接绑定 Z。原 profile trt-xyz-head/1 与原模型保持。
• generate_glb_machines.mjs 新增四柱桁架、固定纵向 X 轨、属于 X 的整根桁架横梁、属于 Y 的横梁滑座、属于 Z 的滑枕/主轴外形。转台仍独立挂到底座；生成两个新单文件 GLB 及 XML。
• machine-urdf.ts 只对新 profile 放行对应 link/joint 数量和 Z 工具绑定；保留树/单位/轴向/运动学校验。MachineImportPanel 从 manifest 读取四个例子的按钮名和路径，结构文字根据 profile 显示。
• 新增 test_gantry_machine_browser.mjs；原参数编辑测试和五轴程序测试增加可选 GLB_MACHINE_VARIANT/GLB_EVIDENCE_DIR，复用完整原断言。标准校验脚本支持独立证据目录。
• 验证 E10：四个入口和下载、标准 profile 兼容；新模型各分支父子关系、X/Y/Z 分别带动对应外形、底座/转台独立；三类错误新 profile 拒绝；参数应用/INI 保存导入重读保持模型、各18个WASM姿态/刀长、实际 RTCP Jog；每机型41个五轴同时变化采样间隔、42个轨迹投影。四个 GLB 均0错误/警告；重复生成和生产资产一致，原AC/BC字节SHA未变。桌面/手机与类型检查/构建通过。
• 原有本地改动及此前证据保留；本轮独立 coverage/glb-machine/gantry/。无 native C/WASM 变更、无外部模型资产。
• 下一步：任务已验收，无待办；按新目标继续。所有功能改动仍未提交/推送。

R05 / 2026-09-18 / 几何编辑保留导入机床

• 用户发现导入 GLB 后“应用参数”会切回内置机床。根因是 App.applyGeometry 在非导入调用时执行 setImportedMachine(null)，属于 R02 为防止参数脱节制定的旧策略。用户新需求覆盖此策略，新增 GLB-GEO01。
• 修复前 scripts/test_imported_geometry_browser.mjs 明确复现：应用后 GLB hash 从源文件 SHA 变成空串；before.log 保留。
• imported-machine.ts 新增 updateImportedMachineGeometry：验证机型、运行限位/速度及 INI 参数，按节点绑定更新当前有效 URDF 的 A/B、C、work origin，并重新解析校验；支持用户自定义 joint 名称。源 scene、网格、材质、文件名与 SHA 不变。
• buildImportedMachine 的运行克隆使用有效 URDF 设置所有 link 的零位，包括固定 work frame；运动继续采用真实 WASM 关节。App 在 Worker 成功加载配置后提交候选结构；参数预检失败保持旧模型，程序重解析失败则明确报告已应用配置。
• App 资源清理依赖 source scene 是否更换，避免几何对象变更时误释放共享网格。导入详情显示当前参数，并说明源 GLB 未改写。显式机型选择仍卸载旧 GLB。
• 同机型“应用参数”“重新读取 INI”“导入 INI 后应用”均保留模型；重复相同参数不累加位移。对应更新原 GLB 浏览器脚本的 INI 重载预期，保留所有其他断言。
• 验证 E09：AC/BC 的真实 UI 原路径复现、保存/导入/重读、非法输入保留状态、开机门控、机型切换，以及各 18 个不同角度/刀长的 WASM 交叉验证和改参数后实际 RTCP Jog 均通过。原 GLB 全专项、内置参数编辑回归及类型检查/构建通过。
• 测试修正：details 展开状态在 AC→BC 切换时会保留，最初无条件点击反而折叠导致文本断言失败；改为仅在折叠时点击，未放宽内容断言。
• 证据独立在 coverage/glb-machine/geometry-edit/；旧报告保持，不修改源 GLB 或上游/原有本地改动。
• 下一步：本专项已验收，按新需求推进。当前所有本地功能变更仍未提交/推送。

R04 / 2026-09-18 / 空闲 M429/M428 切换刀尖跳动

• 用户截图中 XYZ 坐标保持不变，而 J0/J1/J2 随按钮切换改变，模型真实反映了错误关节值，并非 GLB 层级或显示坐标 bug。新增 TRT-SW01。
• 复现：新增 web/worker/test_trt_switch_stationary.mjs，修复前在 AC、A=4.8675° / C=179.88° 下 M428 将 J0 从 0 改为 47.97481463927447 mm，强断言失败；保留 before.log。
• 根因：SimSession.switchXyzacKinematics() 使用保持旧 pose 并逆解的 select()。改为已有 WASM selectPhysical()，输入当前规划器关节，计算新模式下坐标。随后同步 TP 和解释器。
• wasm-linuxcnc-tp.mjs 的 setPosition 增加可选模式参数，坐标和模式一起更新后才 read，避免中间态把旧坐标交给新模式逆解，尤其接近行程边界时错误越限。默认调用行为保持。
• test_xyzac_trt_case.mjs 保留原坐标同步断言并补充关节不变断言；新增实际浏览器按钮/MDI/后续 Jog 专项。
• 验证 E08：两机型 64 次 Worker 切换、22 次浏览器切换；截图姿态、非零中心/偏置、接近边界、重复模式、M430、空闲 tick、增量/坐标偏置、运行中/非法模式拒绝；实际渲染刀尖不动。原 RTCP Jog、TRT case、单步流程、运行后续和生产构建通过。
• 浏览器测试先等待 MDI 到位，再切回 Manual 刷新控件状态后选择切换按钮；第一次直接等待按钮门控刷新超时，未作为通过证据。
• 证据独立保存 coverage/glb-machine/switching/，未覆盖前轮验收；未修改 native C/WASM 或上游 LinuxCNC。
• 下一步：任务已验收，刷新页面载入新 Worker 后重新导入 GLB 即可体验；本轮及前轮改动均未提交/推送，原有本地保留项不变。

R03 / 2026-09-18 / 预览放大与可拖动设置对话框

• 用户截图显示导入说明和参数表占据预览高度，机床仅剩很小显示区域；新增 GLB-UI01。
• App.tsx 把两个入口合为机床预览顶部紧凑工具条；MachineImportPanel.tsx 与 TrtGeometryPanel.tsx 的表单移入共享 DraggableDialog.tsx。模型画布占据其余高度，不改变左右预览比例。
• 原生 dialog 提供模态隔离；标题栏支持鼠标和触摸拖动、视口边界限制、窗口缩小后回到屏幕内；Esc 关闭、Tab/Shift-Tab 循环、焦点返回。关闭保留参数草稿；应用过程中保留结果显示。开机可打开查看，实际导入/参数编辑仍受原门控限制。
• App 快捷键在对话框打开时跳过机床操作，F1 急停保留，防止 Esc 误触 PROGRAM_ABORT 或 F2 误开机。
• 原有 GLB/参数浏览器脚本只适配打开/关闭对话框步骤；新增 scripts/test_machine_dialog_browser.mjs。证据独立写入 coverage/glb-machine/dialogs/，保留 E02–E06 原报告。
• 验证 E07：2048×859、1440×900、390×844 下机床画布高度分别 351.5、392.5、380 px；占机床面板高度超过 85%；打开对话框画布尺寸不变。拖动、极端边界、触摸、缩屏、焦点、快捷键、草稿、运行门控通过；原参数保存/导入、两机型 GLB 导入和 RTCP Jog 回归通过；类型检查/生产构建通过。
• 中间问题：浏览器原生 Tab 可转到浏览器工具栏，专项断言捕获；补充弹窗内 Tab/Shift-Tab 循环后通过，没有放宽断言。
• 下一步：当前专项所有任务已验收，按新需求推进。所有改动仍未提交/推送，原有本地改动继续保留。

R02 / 2026-09-18 / 实现与验收收口

• 完成解析器 web/react/src/machine-urdf.ts：XML 命名空间、两分支拓扑、正交轴、单位/限位、GLB 自包含/节点绑定/位姿、版本和异常输入校验；推导 AC/BC、rot-point 和 offset。
• 完成模型 scripts/generate_glb_machines.mjs 及 web/react/public/machines/ 的 AC/BC GLB、XML、manifest、许可；底座-XYZ-主轴箱、底座-A/B-C，与原移动工作台模型区分。
• 完成 imported-machine.ts、MachineImportPanel.tsx 和 App/Viewer/styles 接入：文件导入、示例与下载，应用前验证，参数通过 INI/Worker 进入 WASM；真实关节驱动、刀长与程序路径参考、旧资产卸载和资源释放。
• 新增 test_glb_machine_browser.mjs、test_glb_machine_motion.mjs、validate_glb_machines.mjs；原两个浏览器测试只增加可选证据输出目录，不删除断言。
• 验证 E02–E06：42 项拒绝用例、36 个姿态/刀长样本、8 次导入模型 RTCP Jog、两机型各 41 个五轴同时变化的执行间隔、84 个程序执行投影采样；两 GLB 标准校验 0 错误/警告；旧参数编辑与 Jog 回归、桌面/手机、类型检查及构建通过。
• 中间问题：生成器默认导出 matrix，首次被 TRS 校验拒绝；改为导出 TRS，同时解析器接受与 URDF 等价的 matrix。运动程序抽样过疏导致样本数断言失败，改为全量采样，未放宽断言。测试损坏文件时模型保持不变，后续重新加载成功示例后截图。重复生成 public 资产触发 Vite 自动刷新，曾打断一次进行中的浏览器测试；停止资产写入后独立重跑。
• 证据统一在 coverage/glb-machine/；旧 coverage/trt-parametric/ 未改。原有 trace、子模块、临时文件和图片完整保留。
• 边界：本轮 v1 仅支持已声明的 AC/BC TRT 正交双链；运行 INI 仍负责回零/周期等；GLB 当前页面内存保存，刷新重新导入；不宣称任意机床 URDF、碰撞检测或制造商尺寸标定。
• 下一步：本专项矩阵无待办，按新目标扩展或按用户要求保存；未提交/推送本轮新功能。

R01 / 2026-09-18 / 需求与契约

• 按用户最新指令确定两分支结构，建立本目录七份文档。
• 已读取原专项索引/矩阵、现有预览、参数写入和 WASM 运动学链路；保留原有工作区改动。
• 已查阅 glTF、URDF、Three.js 和 LinuxCNC 官方资料，检索网络模型资源；尚未找到可确认满足本契约的可再分发完整 GLB。
• 验证：此阶段仅源码和规范核对，未运行新功能测试。
• 下一步：GLB-02 严格结构解析，随后生成两种模型并接入 UI。