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

推进台账

R03 / 2026-09-20 / 管理器 GLB 预览亮度修复

• 用户反馈三维机床管理器导入 GLB 后模型太黑。
• 根因：管理器使用 MeshStandard/Physical PBR 材质，但独立编辑场景没有环境贴图、输出色彩空间和色调映射，高金属度部件几乎只能反射黑色背景。
• 修复：增加 RoomEnvironment → PMREM 工作室环境、sRGB 输出、ACES Filmic tone mapping、1.45 专用曝光，并增加半球光、环境光、暖主光、冷补光和轮廓光；背景和网格提升为中性工作区灰色。
• 原 GLB 的 color、metalness、roughness 和纹理不改写；运行模型材质也不受影响。
• 使用仓库根目录 /home/mes006/linuxcncWebWASM/MILL700-U_1.glb 实测：9,418,852 bytes，SHA-256 bf37130681cc6462412e52744519516e8ade2a3212dd69153c0b1b3e415bcf66；132 节点、126 网格、最大层级深度 6，110 个高金属度材质。
• E05 浏览器验收通过，截图显示原有 MILL700 层级模型在管理器中可辨识；报告和截图位于 coverage/glb-machine-manager/mill700/。
• 当前任务：MGR-10 已验证，等待保存和发布。

R04 / 2026-09-20 / Z-up 机床坐标映射

• 用户要求将 Three.js 管理器坐标调整为 Z 轴朝上的机床坐标系。
• 固定映射：Machine(x,y,z) -> Three(x,z,-y)，保持右手系；机床 XY 作为默认地面网格，机床 Z 对应 Three.js 竖直方向。
• 管理器部件平移、局部原点、组合运行场景、原点辅助和 TransformControls 统一使用该映射；TransformControls 使用机床坐标代理，拖动结果反算为机床坐标。
• MILL700 重新验收通过，蓝色 Z 轴在截图中竖直，浏览器错误为 0。MGR-11 verified。

R05 / 2026-09-20 / GLB 层级树、拖放与节点原点

• 三维机床管理器右侧改为 WAI-ARIA tree，数据直接来自 GLTFLoader 的 Object3D.children，不按节点名称猜测父子关系。
• 树默认只展开根层级，可逐层展开；节点行显示名称和相对父节点的局部原点摘要。选择节点后在编辑区显示精确 XYZ 毫米坐标。
• 拖动 GLB 根树名到另一 GLB 根节点，修改部件 parentId；拖动同一 GLB 内部节点，记录稳定源路径到目标源路径的覆盖。循环、无效路径和跨 GLB 内部拖放明确拒绝。
• 层级覆盖应用在预览克隆和组合导出，原始导入 scene、节点、几何、材质和原始变换不修改。
• MILL700 验证 132 节点、126 网格、深度 6 的树显示；选择 MILL700-A-主轴-JT2 得到父级局部原点 X=-3.969, Y=-204.276, Z=405.633 mm；内部节点拖放及八部件根节点拖放通过。
• 为避免大模型选择卡顿，树选择只更新坐标面板；预览使用共享只读几何/材质的节点克隆，层级变更后才重建变换树。MGR-12 verified。

R06 / 2026-09-20 / WebGL framebuffer 稳定性

• 用户截图显示 texImage2D width or height out of range、glRenderbufferStorageMultisample 超限和 framebuffer zero-size 连续错误，导致层级管理界面不稳定。
• MILL700 三张纹理实际为 1024x1024、1604x1205、1604x1205，不是纹理超限；风险来自特定 GPU、DPR 和 DevTools 短视口组合下的多重采样 drawing buffer。
• 管理器 WebGL renderer 关闭 MSAA，读取 MAX_RENDERBUFFER_SIZE、MAX_TEXTURE_SIZE 和 MAX_VIEWPORT_DIMS，按 90% 安全边界及最多 4096² 像素动态降低 DPR；宽高不足 2px 时暂停 resize/render。
• 发布 render-state、实际 pixel ratio、buffer size 和 GPU 上限诊断；context lost 后停止动画循环，避免重复 framebuffer 错误刷屏。
• 模拟页面 1154x220、DPR 3：CSS 656x655、drawing buffer 984x982、GPU 上限 8192，控制台警告/错误 0。MILL700 层级树及 AC/BC 生产回归通过。MGR-13 verified。

R07 / 2026-09-20 / 删除与层级运动验证

• 新增“删除导入模型”，删除后释放源场景资源、移除装配引用、树节点和预览。
• 任意 GLB 根/内部树节点可绑定 base、X、Y、Z、tool、A/B、C、work 角色；角色徽标显示在树节点上。同一角色唯一绑定。
• 新增层级运动测试输入：XYZ 为 mm，A/B/C 为 deg。预览恢复节点导入基准后施加输入，发布测试姿态及每个角色的 local/world position、local/world quaternion。
• MILL700 实测：主轴 JT1/JT2/JT3 绑定 XYZ，输入 10/20/30 mm 后局部坐标分别增加 0.01/0.02/0.03 m；工作台 JT1/JT2 绑定 A/C，输入 15°/45° 后局部旋转严格变化 15°/45°，C 世界坐标随 A 父级变化。
• 删除 MILL700 后 part-count=0、树节点=0。整个运动测试期间 WebGL context generation 始终为 1，没有因输入或树操作重建 renderer。
• 生产 8 部件 AC/BC 应用、导出和程序运动回归通过，warning/error=0。MGR-14 verified。

R08 / 2026-09-20 / 选中关节局部坐标系

• 用户明确每个层级节点是独立关节模型，必须显示该关节自己的局部坐标系。
• 新增复用的 selected-joint-local-coordinate-system 三轴箭头组；选择树节点时挂到该节点局部 (0,0,0)，位置和四元数归零，因此坐标轴严格表示该节点局部 X/Y/Z。X 红、Y 绿、Z 蓝，箭头长度按整机包围盒自适应。
• 切换节点时只把辅助轴移到新节点，不重建 renderer；节点随轴输入运动时坐标轴同步继承自身和父链变换。
• MILL700 选择 MILL700-A-主轴-JT2 验证 selected-joint=<part>:<path> 和 selected-joint-axes=local-xyz，浏览器错误为 0。MGR-15 verified。

R02 / 2026-09-20 / 部件装配、标定、应用与验收完成

• 新增 machine-manager.ts：通用自包含 GLB 部件加载、SHA-256、深复制、八角色和两条机械链校验、AC/BC URDF 生成、组合场景、底座/整机 userData、组合哈希。
• 新增 MachineManagerPanel.tsx：机床预览区“三维机床管理”按钮、可拖动大对话框、独立 Three.js 预览、批量部件导入、角色/父级、显隐、原点辅助、数值平移/旋转、TransformControls、C 原点、A/B 偏置和物理零点编辑。
• 新增“导出组合 GLB”；导出的新文件包含 linuxcnc.machine/1 URDF，以及整机场景和底座节点上的 linuxcnc.machine-manager/1 标定 userData。
• 接入 App 原有 LOAD_WORKSPACE + PROGRAM_LOAD 事务。配置和程序应用成功后替换机床；失败候选被释放。关机且空闲门控、程序重解析和回零要求保持。
• buildImportedMachine 按 WASM joint - physicalZero 驱动 X/Y/Z/A或B/C，刀长、路径和 RTCP 仍来自 Worker/WASM；有效 INI 参数同步回运行克隆的底座 userData。
• 浏览器 E01/E02 覆盖 8 个独立 GLB、原点/变换、导出、AC 应用、同一部件切 BC、BC 五轴程序、物理零点、非法层级和生产包。无浏览器错误。
• 旧五轴整机回归重新通过：AC/BC 各 41 个五轴同时变化 tick、42 个样本，坐标误差低于 2.5e-16 视图单位。
• gltf-validator 当前未安装，因此没有重跑旧 Khronos 校验器；旧四个示例 GLB 未修改，历史 coverage/glb-machine/gltf-validation.report.json 仍为 verified。本专项生成并下载的组合 GLB 已由浏览器 GLTFExporter 完成往返导出。
• MGR-01 至 MGR-09 全部完成。下一步按用户体验反馈扩展草稿持久化、部件库或任意新运动学 profile；不自动扩大到碰撞/动力学。

R01 / 2026-09-20 / 专项建立与实现启动

• 用户要求在机床预览区新增“三维机床管理”对话框，覆盖部件级 GLB 导入、层级、原点、姿态、RTCP 几何参数、物理零点和控制坐标对应。
• 核对现有 docs/glb-machine、MachineImportPanel、严格 URDF 解析、buildImportedMachine 和 WASM 关节投影。现有能力只支持已经包含完整层级与 URDF 的整机 GLB，本轮扩展为部件装配编辑器。
• 建立本目录 01–06 和 README；新增 MGR-01 至 MGR-09 任务链。
• 决定复用 linuxcnc.machine/1 结构：管理器生成合法场景和 URDF，现有 INI/Worker/WASM 继续作为运动和 RTCP 权威。
• 当前任务：已完成。
• 下一步：按新需求继续；本专项不重复执行。

R10 / 2026-09-21 / 部件节点相对父级变换

• 更正 R09（63f726d）：上一轮错误地让内部节点输入移动整个 GLB 根。用户要求编辑当前选中节点，原 R09 的根节点验收不足以证明内部关节编辑正确。

• 用户明确要求“部件平移”和“部件旋转”修改当前选中节点相对其父节点的位置和姿态。

• 根节点继续使用部件级 translationMm、rotationDeg；GLB 内部节点使用稳定源路径保存到 nodeTransforms[path]。输入值是当前节点的父级局部位置（mm）和 XYZ 欧拉姿态（deg），旋转中心是节点自身原点。

• 预览克隆、组合导出和应用运行场景统一应用同一组局部节点变换；父节点运动时子节点继承，编辑子节点不会错误移动整个 GLB 根部件。

• 拖放内部节点后保存当前局部姿态并重新计算新的父级局部姿态，保持拖放前的世界姿态。

• MILL700 选择 MILL700-A-主轴-JT3，输入 X=120 mm、RZ=25° 后，节点局部位置和四元数分别变为 0.120 m 和 25°；8 部件 AC/BC 生产回归、导出和应用继续通过。

• MILL700 补充断言：JT3 局部 Z 减少 44 mm 时 JT2 与兄弟滑轨不动、JT4 同步移动；RZ=25° 时 JT3 原点不动、JT4 绕该原点运动；父链预先旋转 20°，位移仍按父坐标系计算。切换选择和重开对话框保留输入；带编辑姿态的门节点换父级后世界姿态不变且能继续编辑。

• MGR-16 verified；验收证据 E12。

R11 / 2026-09-21 / 单自由度关节与控制器映射

• 每个节点固定或只绑定一个 XYZABC 轴；父级 x/y/z 方向和 ±1 可配，平移/旋转类型及单位由数控轴确定。旧自由位置/姿态编辑改成单值关节输入。
• 新增 machine-joints.ts：版本化节点与控制器映射、严格校验、零姿态驱动；预览与运行共用。
• makeJointAssembly 保留已有模型层级，支持 MILL700 单文件配置完整五轴后应用；新配置不再要求八个独立 GLB。
• 实际床身节点、控制底座和场景写入关节 JSON，兼容原 URDF 与机床几何 userData。导出显式 Scene extras；GLB 重导入恢复轴绑定、方向、物理零点和标定。
• App 快照接入对话框实时跟随；运行模型通过实际 WASM 关节名映射驱动，并发布同 tick 的轴输入/模型变换诊断。
• 大型关节模型运行关闭 MSAA 和实时阴影，减轻软件 WebGL 绘制开销。
• 数学/JSON 校验、八部件 AC/BC 回归与完整 MILL700 AC/BC 实时/导出往返验证均通过；每机型 8 个不同 tick，五个轴均变化，浏览器 warning/error=0。MGR-17 verified；证据 E13。

R12 / 2026-09-21 / 工程化工作台体验

• 三维管理器改为固定预览区 + 独立编辑区：结构与关节、运动验证、机床标定三个页签；窄窗口和矮窗口保持底部操作区可见。

• 增加节点搜索、展开/折叠、选择后滚动定位、XYZABC 轴绑定总览和整机/选中/正视/俯视按钮。

• 增加 30 步撤销/重做；删除、导入、轴绑定、方向、物理零点、标定和显隐变化都进入草稿历史。实时跟随锁定编辑，退出后恢复编辑。

• 数值输入支持空值/非法值标红，错误不会写入状态；AC/BC 禁止沿倾转轴的非法偏置；批量导入失败保持现有装配。

• 单自由度输入提供步长 0.1/1/10 和本轴归零，所有运动仍使用父级方向和物理零点。

• E14 工作台浏览器验收通过：搜索、总览定位、撤销/重做、错误输入、标定校验、视图、删除恢复、导入失败保护、实时锁定和 1440/1154/720 视口无溢出。

• 最终 AC/BC 完整回归分别通过，各 8 个动态 tick；线上 E14 工作台回归通过。已发布 a7233bc，资源 index-nddrUCCV.js。

R13 / 2026-09-21 / 对话框选择机床类型与保存整机

• 设计机型从外部控制面板属性改为草稿字段，标题、轴总览、绑定选项、标定与运动输入统一使用所选设计类型。顶部按选择类型→配置结构→验证标定→保存 GLB 引导。
• AC/BC 切换只清理不适用的 A/B 轴绑定，保留模型层级、XYZ/C 和标定，并提示重新配置、核对；整个切换可撤销/重做。外部工作区切换不再改写草稿。
• 打开已保存完整机床作为单一文档事务，自动恢复文件中的机型、关节、层级、物理零点、RTCP 参数；原草稿可撤销恢复。普通 GLB 部件导入仍为追加。
• 保存入口改为“保存机床模型 GLB”，使用 inspectMachineGlb 和 32 MiB 限制校验结果，确保标准导入器可读取；成功消息提示去控制面板“导入机床模型”加载。
• E15 针对跨机型闭环测试通过：在 AC 控制器下设计 BC、切换撤销、保存、重新打开、控制面板标准导入自动识别 BC。MILL700 两机型实测通过，分别 8 个同时五轴运动 tick、浏览器 warning/error=0。保存两份完整 GLB 验收示例；MGR-19 verified。

R14 / 2026-09-21 / 机型与 G 代码匹配

• 根因：模型导入/管理器应用经 applyGeometry 更换工作区后，仍使用旧 programText/programPath 重载，导致 BC 运行 AC 程序。
• 跨机型时在工作区提交前准备目标机型 catalog 默认程序，验证资源和轴兼容性；提交后同步程序编辑器、路径、预览和 Worker。同机型保留兼容自定义程序。
• 新增共享 programMachineMismatch：检查文件机型标识和有效块中的不支持 A/B 轴字，忽略注释、命名参数、O 标签及表达式内部。通用三轴程序继续可用，不改写 A/B 指令。
• Worker 在 PROGRAM_LOAD 以及 RUN/STEP/RESUME 检查源程序与展开子程序；覆盖绕过 UI 和旧恢复程序。门控缓存源文本/机型/路径，避免每帧重复扫描大程序。
• E16 本地验证通过：AC→BC、BC→AC、管理器应用、错轴文件/编辑器拒绝、同机型保留、自定义程序与正确 BC 运行。11 个可加载 RTCP 目录程序、程序替换和单步回归通过。