Files
vibemake-admin/README.md
T
2026-11-12 11:07:26 +08:00

9.1 KiB
Raw Blame History

VibeMake 管理后台

React 18 + TypeScript + Vite 6 + Ant Design 5 + React Router 6。对接 community-adminapi(/admin-api)。

环境

环境 前端 后端
本地开发 http://localhost:8091 代理到测试环境后端
测试 https://dev-vibemake-admin.robotquan.com https://dev-vibemake-api.robotquan.com
线上 https://vibemake-admin.robotquan.com https://vibemake-api.robotquan.com

前端在 src/config/environment.ts 按访问域名自动选择接口地址,已知部署域名优先于构建默认值:

  • 本地开发:请求同源 /admin-api,由 Vite dev server 代理(vite.config.ts,目标取 .env.* 中的 VITE_PROXY_TARGET)。
  • dev 网站:dev-vibemake-admin.robotquan.com 请求 https://dev-vibemake-api.robotquan.com/admin-api。
  • 线上网站:vibemake-admin.robotquan.com 请求 https://vibemake-api.robotquan.com/admin-api。
  • 其他部署域名:使用当前构建的 VITE_API_BASE 默认值。

界面环境标记也按网站域名选择,避免同一份静态文件部署到不同域名后显示错误的环境。localhost 本地开发和预览继续请求 /admin-api,使用 Vite 的环境代理。

注意:测试后端 http 会 301 到 https,代理目标必须写 https。

命令

npm install
npm run dev          # 本地开发,代理测试环境后端
npm run dev:prod     # 本地开发,代理线上后端(谨慎)
npm run build:dev    # 构建 dev 服务器静态包,内置 dev 后端地址 -> dist/
npm run build:test   # 构建测试环境包 -> dist/
npm run build:prod   # 构建线上包 -> dist/
npm run preview      # 本地预览构建产物
npm run preview:dev  # 按 dev 配置预览
npm run preview:prod # 按线上配置预览,代理目标为线上后端

部署

dev 更新:执行 npm run build:dev(与 build:test 相同),将 dist/ 内的文件覆盖上传到现有 dev 网站根目录即可。构建产物已内置 dev 后端地址,后端已放行 dev 前端域名的跨域访问,无需新增接口代理。本地开发请使用 npm run dev。

线上更新:执行 npm run build:prod,将 dist/ 内的文件覆盖上传到线上网站根目录。前端会根据线上域名访问线上后端,不需要在前端站点增加 API 反向代理。线上后端需要允许 https://vibemake-admin.robotquan.com 跨域访问(包括 Authorization、Content-Type 及各业务 HTTP 方法);目前实测该来源的预检被后端返回 403 Invalid CORS request,该后端限制不由前端打包控制。

DevTools 中 preflight 是浏览器发送的 OPTIONS 跨域预检,fetch 才是业务请求;它们不是业务执行两次。已知部署域名均直接访问对应后端,正常保留浏览器预检。deploy/ 中的 Nginx API 代理文件仅作为同源部署方式的备用示例,当前域名自动选择方案不需要启用它们。

功能

零件列表支持名称/目录搜索、单个 GLB 自动上传、同路径确认替换及逐行删除;单项增删通过现有整批接口合并保留其他零件。

当前文件/模型上传已对接 admin-api(7) 第 8.3 节:四类资源签名→OSS 原文件上传→确认绑定,成功立即更新社区详情,无需重新发布。行走资源直接选择完整文件夹,不要求 robot.json。旧草稿与分功能构建方案仅保留兼容实现,当前实际接口不提供策略运行校验。详见 当前接口及联调记录。

装配与仿真第一阶段:项目详情可上传整机 GLB、零件 GLB 文件夹、装配步骤 JSON,以及行走表单文件或 ZIP,保存独立草稿并通过构建版本发布。新增接口待后端接入,字段和异步任务完整约定见 模型与演示接口。前端不限制文件大小和机器人型号,后端负责文件完整性与兼容性校验。

装配流程支持可视化制作:新建项目和项目管理中,在“零件模型”选择零件文件夹后点击“制作装配流程”,在三维模型或列表中多选、分组,设置进入方向/距离并添加步骤;支持即时预览、完整流程播放、拖动排序、撤销/重做、复制步骤设置、最终位姿对齐。系统生成 JSON,已有步骤仅通过“高级导入(JSON)”接入,零件直接使用上方零件模型,无需重复上传。原 GLB 字节和材质不变;本地文件上传后自动关联资源编号。尚未上传的流程只保留在本页内存中,可先导出 JSON 备份,后端接入后才能持久保存和发布。

行走资源可直接选择工程文件夹,自动识别基础配置并保留子目录,无需先压缩。行走演示默认采用“四项基础文件+可选功能”表单:配置 JSON、MJCF、实际引用文件、primary ONNX;踢球、转头、起身等逐项勾选和绑定,文件与技能可复用。额外资源保留草稿,发布时确认已通过的功能子集;足球预设来自后端,不要求上传标准足球模型。保留 ZIP 导入与独立的旧版兼容区。新建项目选择的文件和设置会带入管理页;前端不限制大小。新接口适配与联调字段见 接口文档第 12 节。接口未接入时明确提示,不能伪上传、保存或校验。社区播放器能力拆分、实际推理和发布联调尚待后端与前台共同实现。示例位于 public/examples,构建时会包含在 dist 中。

新建项目与项目管理均按“整机模型、零件模型、拼装步骤、行走演示”分区选择文件,整机和零件可以同时保留。新建后直接进入模型页继续上传;管理页上传整机即自动选用,包文件自动读取,普通操作按“上传 → 检查并预览 → 发布到前台”完成,无需手动填写资源编号。

  • 登录 / 退出 / 修改密码(401 自动回登录页并保留返回路径)
  • 用户管理:列表筛选、详情、名下项目、编辑昵称、启用/禁用(不可禁用自己与官方账号)
  • 项目管理:列表筛选、新建(封面 OSS 直传、归属官方或普通用户)、编辑、删除
  • 项目日期:编辑信息支持设置/清空发布时间 publishedAt;项目管理仅按发布时间倒序,创建时间只展示,查询、重置和分页均保留发布时间排序。按上海时间解析与提交,系统 updatedAt 由后端维护。对接既有接口,见 项目日期对接说明。
  • 发布 / 更新发布 / 撤回 / 下架 / 解除下架(发布前确认当前 main SHA,409 冲突需刷新重新确认)
  • 文件:目录浏览、预览(文本/图片)、在线编辑提交、新建文件/目录、删除文件、多文件/文件夹上传(不设独立单文件上限,单次合计 ≤ 500 MiB、最多 500 个文件,含选择、限额与路径预检、进度反馈)、鉴权下载
  • 提交历史,并可只读浏览任一历史版本
  • URDF 目录上传绑定(签名 → 并发 OSS 直传 → 确认)与移除;项目详情和迁移页均不设独立单文件上限、合计 ≤ 500 MiB、最多 500 个文件;按扩展名保留 URDF、模型、材质、贴图及模型数据,过滤代码、文档、配置、隐藏文件和依赖目录,数量/大小限制仅计算待上传资源
    • 项目上传和迁移上传均在签名前按文件清单把 URDF 的 mesh/texture 引用改为相对主文件的真实路径,兼容嵌套 ROS 包、旧来源目录、Windows 路径和唯一的大小写匹配;缺失或歧义资源会阻止签名。签名、OSS 上传和确认使用改写后的同一份文件及字节数,其他资源的目录与内容保持原样。
  • STEP 文件管理:URDF 右侧 STEP tab,支持 .step/.stp 单文件上传(≤ 500 MiB)、替换、移除绑定和直接下载。已按后端文档 §8.4 对接签名、OSS 直传和确认;确认异常保留原请求,手动重试前提示重新写入绑定。下载直接使用 stepMainUrl,不新增接口、不携带管理 Token。详见 STEP 接口对接说明。
  • GitHub 迁移:预检 → 补充信息(可选上传封面、URDF)→ 创建任务并绑定资源 → 3 秒串行轮询阶段 → 检查后手动发布;重复来源跳转已有项目
  • 迁移重试:FAILED、REVIEW 始终提供手动重试入口,不按 canRetry 隐藏;列表点击重试即进入任务确认框,展示 retryMessage,由重试接口判断是否受理;支持 CLEANING 清理阶段,409 后刷新状态,网络异常时先查询确认结果

迁移功能回归

npx playwright install chromium # 首次运行时安装测试浏览器
npm run test:imports
# 或使用本机已安装的 Chrome
PLAYWRIGHT_CHANNEL=chrome npm run test:imports

测试会启动独立的本地 Vite 服务并拦截全部管理 API,不向实际后端发起迁移、清理或发布操作。覆盖重试资格、确认说明、202 轮询恢复、409、网络异常、安全清理提示、页面离开停止轮询,以及重复来源和创建结果不明时的提交保护。