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 权威。
• 当前任务：已完成。
• 下一步：按新需求继续；本专项不重复执行。

R09 / 2026-09-21 / 部件平移与旋转实时同步

• 用户反馈编辑器中的“部件平移”和“部件旋转”改变后，预览中的对应 GLB 部件没有稳定更新。
• 预览同步逻辑新增部件根节点变换步骤：每次状态同步都把 translationMm 转换为米写入导入部件根节点位置，把 rotationDeg 转换为弧度写入根节点姿态；当前选中内部关节时仍变换该关节所属的完整 GLB 部件。
• 轴运动诊断随后在部件装配姿态上叠加，不覆盖编辑器已经设置的部件变换；组合导出的 geometry userData 同步保存平移和旋转值。
• MILL700 输入 X 平移 100 mm、Z 旋转 20° 后，选中关节的世界原点和世界四元数均发生对应变化；8 部件 AC/BC 生产回归输入 X=10 mm、Z=15° 后，预览、导出和应用后的 geometry 分别保存 translationMm[0]=10、rotationDeg[2]=15。
• MGR-16 verified；验收证据 E11。