11 KiB
CAD World Management
React + TypeScript 管理后台,保留组件库、用户管理和操作日志。使用黑色配色及 CAD World 标识。
组件库已经接入新版 /admin-api,不再使用本地组件数据库。新增组件只必填单个 STEP/STP 文件;URDF 文件夹、名称、分类及其余表单信息均选填。编辑时已保存的 STEP 满足必填要求,可只更新表单,或单独替换 STEP / URDF。未填数值保存为 null,显式填写 0 则保留 0。选择 URDF 时仍须提供可解析的完整文件夹。组件编码由后端签名接口分配,不能手动修改。
右侧“零件描述 / 基本信息”通过 Tab 切换,默认展示零件描述表单;基本信息只读展示 URDF 文件点位。零件描述展示名称、零件分类、自由度、材质、功能、形状、大小、扭矩、质量和描述。选择符合命名规则的 URDF 后分类从主文件名自动识别;未选择或无法识别时分类可手动填写,也可留空。选择 URDF 时名称默认使用主文件名(去掉扩展名),允许手动修改或清空;编码只交由后端生成,不展示编码输入框。质量单位为 kg,扭矩单位为 N·m,均可为 0。列表按服务端分页,关键词搜索名称或编码,分类精确筛选;默认按最近更新排序。
运行
零件描述底部新增 BOM 清单:下载 .xlsx 模板、导入 Excel、预览和清空。解析结果随保存请求的 bomList 数组提交,按照最新接口支持保存和详情回填;其他已有 JSON 结构原样保留,详见 BOM 字段约定。
需要 Node.js 22.12 或以上。
npm install
npm run dev
访问 http://127.0.0.1:8091。开发服务监听 0.0.0.0,同一局域网可通过本机 IP 加端口 8091 访问。浏览器局域网 HTTP 地址也可生成请求编号、读取 STEP 和 URDF,不依赖仅安全上下文可用的 SHA-256 API。
vite.config.ts 将 /admin-api 代理至 https://dev-cadworld-api.robotquan.com,例如组件查询转发至 https://dev-cadworld-api.robotquan.com/admin-api/components?page=1&size=10,路径和查询参数保持不变。可通过 ADMIN_API_TARGET 环境变量覆盖,例如 http://127.0.0.1:8992。
上传使用接口文档规定的“后端签名、浏览器直传 OSS、后端校验入库”:直接使用签名响应中的 uploadUrl 和 uploadFields,不硬编码存储 Bucket,不经过 Vite 上传代理。开发、preview 和正式构建使用相同上传逻辑。OSS 必须允许页面实际来源的 POST 跨域请求;当前 OSS CORS 仍未配置完成,上传处于待验收状态,不能视为可上线。
正式部署使用 npm run build 生成的 dist,由静态 Web 服务托管。../shared/api-origin.ts 按页面域名选择 API:dev-cadworld-admin.robotquan.com 直连 https://dev-cadworld-api.robotquan.com,cadworld-admin.robotquan.com 直连 https://cadworld-api.robotquan.com;本机/局域网保留 Vite 开发代理。线上网页站点无需配置 /admin-api 代理,后端需允许对应网站的 CORS,OSS 另需允许实际上传来源。完整部署与验收要求见 docs/deployment.md。
目前文档没有认证或短信接口,登录继续保留约定的临时前端行为:填写手机号和验证码即可进入,获取验证码自动填入 123456。后台操作人由服务端配置决定,与前端填写手机号无关。
上传时读取 URDF 点位
上传页右侧依次为“零件描述”和“基本信息”,默认打开零件描述,选择文件不会强制切换标签。基本信息按文件顺序只读列出全部 joint,不提供坐标系选择或安装配置,原样读取名称、类型、父子 Link、origin XYZ(m)/RPY(rad),以及文件显式提供的轴向和关节限制。不会把普通 Link、visual/inertial origin 当作安装点,不推断安装用途,不添加配对关系,不改写文件。选择 URDF 时解析结果随保存请求的 urdfInfo 字段提交;未提供 URDF 时为 null。替换 URDF 时同步更新,未替换时保留详情 JSON。缺失属性展示为“文件未定义”,只读信息不补默认坐标。
悬停或键盘聚焦点位时,在 URDF 预览里高亮文件定义的位置;离开后移除标记,切换零件描述时清空高亮。标记独立存在于预览场景,不挂载到原始模型,不修改坐标、材质、层级或上传字节。自由度、功能、形状、大小和扭矩分别使用独立字段 degreesOfFreedom、functionDescription、shape、size、torqueNm;材质、质量和描述分别保存为 material、massKg 和 description。自由度为 0 至 2147483647 的整数,扭矩为 N·m 数值,质量和扭矩均校验最多 12 位整数及 6 位小数。编辑时回填固定字段,已保存的历史扩展数据保留,页面不提供自定义字段编辑入口。
悬停点位时相机平滑转向该点并居中,从模型中心朝点位的方向取景仅用于浏览,不表示安装朝向或配对关系。手动拖动/缩放立即接管相机。预览使用自由轨迹球旋转,可越过顶部、查看底部,不显示地面网格;右下角直接使用 Three.js 官方 ViewHelper,随相机实时变化,点击坐标轴可切换视角,不向文件添加坐标系。
STEP 的 OCCT 解析、三角化及法线计算在独立 Web Worker 中执行,结果通过可转移缓冲区返回;主线程分批创建预览网格。解析期间 URDF 选择、预览切换与表单操作保持可用。文件选择窗口有重复打开保护,取消或选中后恢复;离开页面或替换 STEP 时会终止旧解析任务。Worker 由 Vite 打包,WASM 随 dist/vendor 部署,无需额外服务。
STEP 和 URDF 统一使用中性灰色预览材质,颜色、金属度和粗糙度一致。显示副本与原模型共享几何,但使用独立材质,原始材质、文件颜色和上传字节保持不变;副本保留各材质槽、透明度、可见性和模型变换,卸载时仅释放副本材质。
统一预览使用中性补光、主方向光和 ACES 色调映射,避免过曝;主光阴影范围随模型尺寸适配,显示孔位和凹槽的遮挡层次。使用背面投影及随模型尺寸适配的法线偏移,减少 STEP 表面的自阴影条纹;不修改几何或安装坐标。
坐标信息独立于网格读取,三维预览失败时仍可查看已解析的内容。替换、移除 URDF 时同步刷新或清空;编辑已有组件时进入点位标签会按需读取已保存的 URDF。
后台使用窗口内布局,标题、操作栏和分页保持可见。上传页及文件检查页左右面板等高,预览随剩余空间缩放,长表单、点位和列表只在各自内部滚动。窄屏改为上下排列,在工作区内滚动,不撑高整页。
URDF 文件检查
登录后连续点击左上角 Logo 三次进入 /assembly-test,不增加侧边栏菜单。页面默认加载随构建部署的躯干与 H-DOF0-R 原始 URDF/网格样例,不依赖本机 Downloads,也不上传文件或写入后端。
通过文件标签分别查看原始模型及文件里的 joint/origin 信息,也可更换完整 URDF 文件夹。前端不指定安装点配对、父子关系、旋转、间距或坐标轴对齐规则,不合并两份没有定义跨文件安装关系的 URDF。机械人员负责在文件中定义正确的安装关系;修改后重新导入即可按新文件读取。
完整显示文件定义的全部 visual 和子零件;统一灰色仅应用于显示副本,原始材质/颜色数据保留。不改网格坐标或模型根位姿,视图适应只调整相机。没有显式定义的点位属性显示“文件未定义”,不补造坐标值。读取 URDF 时遵循文件格式语义加载模型内部结构,不加入业务安装规则。退出时释放三维资源。
验证
npm test
npm run check
npm run build
npm run format:check
结构
src/pages/ComponentCatalogPage.tsx:服务端分页、搜索、分类筛选、删除及列表/卡片视图。src/pages/ComponentUploadPage.tsx:双资源上传、模型预览、两组表单和版本冲突处理。src/application/component-upload.ts:单签名授权、4 路并发 OSS 上传、续签及上传重试。src/application/component-gateway.ts:组件 CRUD 与按需资源下载。src/pages/UsersPage.tsx、src/pages/ActivityPage.tsx:用户管理与通用操作日志。src/pages/AssemblyTestPage.tsx:隐藏 URDF 原文件检查页;不进行跨零件安装推断。docs/admin-api.md:本次采用的接口文档。docs/architecture.md、docs/verification.md:架构及本次验证结果。docs/deployment.md:正式环境网络、OSS CORS 与上线验收。
旧接口库、选面选孔、接口绑定、姿态计算、BREP 服务、封面、ZIP 导入、备份、IndexedDB 草稿及旧上传会话逻辑已从这个独立后台项目移除。其他目录中的原项目未修改。
URDF 零件与接口的命名、识别和保存约定见 命名规则。新建或替换 URDF 时按主文件名识别类型及左右,通过现有 basicFields 保存,原始安装坐标保持不变。
选择可识别的 URDF 后零件分类与文件识别结果统一(如 torso_0、arm_l),只读展示并作为 category 保存;其他情况分类可编辑或留空。列表分类建议使用同一套匹配键,通过后端已有 category 参数精确筛选。历史未规范命名的已保存文件保留原分类,替换 URDF 后按新命名自动识别。
坐标一致性回归(2026-10-14)
后台上传解析和模型预览保留文件内的 origin XYZ/RPY、内部层级及网格位置,不自动把头或其他零件转正。urdfInfo 保存相对 parent/link 的原始坐标;前台读取完整 URDF 后累计到组件根节点再对齐。新增联合测试验证前台装配与后台预览内部坐标一致,包括多级父节点、非零旋转、倒置安装点、完整坐标系重合及原文件内容不变。
STEP 必填、其他选填(2026-10-14)
页面、表单校验和直传流程已支持仅 STEP。实测开发后端仍返回 422,要求 componentName、category、urdfObjectKeys 非空,因此服务器仍需同步放开这三项约束及无 URDF 的资源入库逻辑。前端不会填造名称、分类或 URDF 引用来绕过服务端校验。具体返回和同步要求见 ../releases/后台STEP必填-后端同步说明.txt。87 项自动化测试及生产构建通过;未向真实后端上传或创建测试零件。
模型下载(2026-10-14)
STEP、URDF 和网格从 https://linkerbot.oss-cn-beijing.aliyuncs.com 直接下载,按接口返回对象键拼接,不再经过组件资源下载接口。本地及线上使用相同规则,保留对象键里的环境目录。业务 API 按页面域名选择环境,OSS 上传仍由后端签名授权。