Files
2026-11-12 11:07:26 +08:00

83 lines
9.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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。
## 命令
```bash
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。旧草稿与分功能构建方案仅保留兼容实现,当前实际接口不提供策略运行校验。详见 [当前接口及联调记录](docs/model-experiences-api.md)。
装配与仿真第一阶段:项目详情可上传整机 GLB、零件 GLB 文件夹、装配步骤 JSON,以及行走表单文件或 ZIP,保存独立草稿并通过构建版本发布。新增接口待后端接入,字段和异步任务完整约定见 [模型与演示接口](docs/model-experiences-api.md)。前端不限制文件大小和机器人型号,后端负责文件完整性与兼容性校验。
装配流程支持可视化制作:新建项目和项目管理中,在“零件模型”选择零件文件夹后点击“制作装配流程”,在三维模型或列表中多选、分组,设置进入方向/距离并添加步骤;支持即时预览、完整流程播放、拖动排序、撤销/重做、复制步骤设置、最终位姿对齐。系统生成 JSON,已有步骤仅通过“高级导入(JSON)”接入,零件直接使用上方零件模型,无需重复上传。原 GLB 字节和材质不变;本地文件上传后自动关联资源编号。尚未上传的流程只保留在本页内存中,可先导出 JSON 备份,后端接入后才能持久保存和发布。
行走资源可直接选择工程文件夹,自动识别基础配置并保留子目录,无需先压缩。行走演示默认采用“四项基础文件+可选功能”表单:配置 JSON、MJCF、实际引用文件、primary ONNX;踢球、转头、起身等逐项勾选和绑定,文件与技能可复用。额外资源保留草稿,发布时确认已通过的功能子集;足球预设来自后端,不要求上传标准足球模型。保留 ZIP 导入与独立的旧版兼容区。新建项目选择的文件和设置会带入管理页;前端不限制大小。新接口适配与联调字段见 [接口文档第 12 节](docs/model-experiences-api.md#12-行走表单-v3本次后台与后端联调约定待后端实现)。接口未接入时明确提示,不能伪上传、保存或校验。社区播放器能力拆分、实际推理和发布联调尚待后端与前台共同实现。示例位于 public/examples,构建时会包含在 dist 中。
新建项目与项目管理均按“整机模型、零件模型、拼装步骤、行走演示”分区选择文件,整机和零件可以同时保留。新建后直接进入模型页继续上传;管理页上传整机即自动选用,包文件自动读取,普通操作按“上传 → 检查并预览 → 发布到前台”完成,无需手动填写资源编号。
- 登录 / 退出 / 修改密码(401 自动回登录页并保留返回路径)
- 用户管理:列表筛选、详情、名下项目、编辑昵称、启用/禁用(不可禁用自己与官方账号)
- 项目管理:列表筛选、新建(封面 OSS 直传、归属官方或普通用户)、编辑、删除
- 项目日期:编辑信息支持设置/清空发布时间 `publishedAt`;项目管理仅按发布时间倒序,创建时间只展示,查询、重置和分页均保留发布时间排序。按上海时间解析与提交,系统 `updatedAt` 由后端维护。对接既有接口,见 [项目日期对接说明](docs/project-dates-backend-requirements.md)。
- 发布 / 更新发布 / 撤回 / 下架 / 解除下架(发布前确认当前 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 接口对接说明](docs/step-backend-requirements.md)。
- GitHub 迁移:预检 → 补充信息(可选上传封面、URDF)→ 创建任务并绑定资源 → 3 秒串行轮询阶段 → 检查后手动发布;重复来源跳转已有项目
- 迁移重试:`FAILED`、`REVIEW` 始终提供手动重试入口,不按 `canRetry` 隐藏;列表点击重试即进入任务确认框,展示 `retryMessage`,由重试接口判断是否受理;支持 `CLEANING` 清理阶段,409 后刷新状态,网络异常时先查询确认结果
## 迁移功能回归
```bash
npx playwright install chromium # 首次运行时安装测试浏览器
npm run test:imports
# 或使用本机已安装的 Chrome
PLAYWRIGHT_CHANNEL=chrome npm run test:imports
```
测试会启动独立的本地 Vite 服务并拦截全部管理 API,不向实际后端发起迁移、清理或发布操作。覆盖重试资格、确认说明、202 轮询恢复、409、网络异常、安全清理提示、页面离开停止轮询,以及重复来源和创建结果不明时的提交保护。