Files
vibemake-admin/docs/step-backend-requirements.md
2026-11-03 15:50:13 +08:00

8.1 KiB
Raw Permalink Blame History

STEP 文件管理:接口对接说明

更新日期:2026-11-02。对应前端 vibemake-admin、后端 community-adminapi。

本文依据后端交付的 admin-api(8).md 第 8.4 节整理,替代本文件之前的待实现需求。批次持久化、严格幂等、过期拒绝和绑定冲突检测不属于本期后端能力,前端不再依赖这些假设。接口以交付的后端文档为准。

1. 功能范围

  • 项目详情中,在 URDF 右侧提供 STEP tab,沿用现有后台组件和布局。
  • 一个项目绑定一个 .step / .stp 文件,支持上传、替换、移除绑定和直接下载。
  • 单文件范围为 1–524288000 字节,包含两端(500 MiB);文件本体直传 OSS。
  • STEP 与 URDF、Git 独立,不创建 Git 提交、不改变发布状态;Git 历史浏览不切换 STEP。
  • 管理操作仅面向已 READY 且未删除的项目,沿用既有管理员鉴权。
  • 替换、移除绑定、删除项目均不物理删除 OSS 对象,旧链接仍然可访问。Fork 继承资源引用,之后可分别修改。

不新增 STEP 列表、下载或预览接口。

2. 项目字段和响应层级

interface StepProjectFields {
  stepMainUrl: string | null;  // 当前公开资源地址,也用于直接下载
  stepFileName: string | null; // 原始文件名,保留中文、空格及大小写
  stepSizeBytes: number | null;
}

未绑定时三个字段为 null。前端也兼容旧项目响应暂未包含这些字段的情况。

所有管理 API 使用既有响应包装:

{
  "code": "OK",
  "message": "成功",
  "data": {},
  "requestId": null
}
  • 项目详情 GET /admin-api/projects/{projectCode}:项目对象仍在 data.project。
  • STEP 确认成功:data 直接为完整 ProjectView,不包裹 project。
  • STEP 移除成功:data 为 null。

签名、确认、移除请求使用现有管理端 Bearer Token;OSS 上传和公开资源下载均不携带管理端 Token。

3. 上传签名

POST /admin-api/projects/{projectCode}/step/signature
Content-Type: application/json
Authorization: Bearer <admin-token>

请求:

{
  "files": [
    { "relativePath": "机械臂 装配.STEP", "sizeBytes": 10485760 }
  ]
}

文件规则:

  • files 只允许一个元素;扩展名大小写不敏感。
  • relativePath 是单个原始文件名,最多 1024 字符,不接受目录、反斜杠、冒号和控制字符。
  • sizeBytes 为正整数字节数,最大 524288000。
  • 不根据浏览器 MIME 推断或拒绝 STEP 文件。

返回 data:

interface StepUploadSignature {
  batchCode: string;
  mainRelativePath: string;
  uploadUrl: string;
  expiresAt: string; // 带时区的 ISO 时间,例如 2026-11-02T08:15:00Z
  files: [{
    relativePath: string;
    objectKey: string;
    formFields: Record<string, string>;
  }];
}

签名有效期为 15 分钟,签名响应禁止缓存。relativePath、mainRelativePath 保留原始名称;实际 OSS 对象名称是 model{原始后缀},例如 model.STEP。对象路径和表单字段由服务端生成,前端不自行拼接或改写。

4. OSS 直传

  1. 前端核验签名中的文件数量和原始名称与当前选择一致。
  2. 将 formFields 全部按原值追加到 FormData,包含 Content-Disposition 等字段。
  3. 最后追加 file 字段,内容为所选原文件。
  4. 向 uploadUrl 发起 multipart POST,不添加管理端 Authorization,也不手写 Content-Type / boundary。
  5. OSS 成功后进入确认阶段;签名或上传本身不会修改当前绑定。

原始文件名通过 stepFileName 和签名中的 Content-Disposition 保留,不从资源 URL 末尾的 model.step 猜测原名。OSS Policy 精确限制对象和大小,并禁止覆盖对象。

5. 确认绑定与失败重试

PUT /admin-api/projects/{projectCode}/step
Content-Type: application/json
Authorization: Bearer <admin-token>

请求使用签名返回的 batchCode 和原始文件清单:

{
  "batchCode": "<signature.batchCode>",
  "files": [
    { "relativePath": "机械臂 装配.STEP", "sizeBytes": 10485760 }
  ]
}

返回 data 为完整 ProjectView。前端核验项目编号和 STEP 三个字段后展示成功,并刷新项目详情。

本期后端语义:

  • 不保存上传批次,不比较历史签名清单;仅核验该项目 STEP 目录下对象存在及大小。
  • 每次 PUT 都重新核验并写入,没有严格幂等或绑定冲突检测。
  • 上传签名过期后,已经上传的对象仍可确认。
  • 并发以最后一次成功写入为准;旧请求可在替换或移除后重新绑定旧对象。

前端处理:

  • 签名/上传失败时保留所选文件,允许重新签名上传,不提前修改当前绑定。
  • OSS 成功后,若确认遭遇网络异常、OSS 故障或无效响应,保留原请求,仅手动重试 PUT,不重复上传。
  • 异常后刷新项目状态,不把失败响应视为服务端一定未写入,也不自动重试。
  • 点击“重试绑定”先提示重新写入可能覆盖其他操作;确认后才发送请求,取消不发送。
  • 对象缺失或大小不匹配时丢弃待确认请求,要求重新上传。
  • 重新选文件、清除选择、离开项目后不继续重试旧请求;移除操作也会放弃本地待确认请求。

6. 移除绑定

DELETE /admin-api/projects/{projectCode}/step
Authorization: Bearer <admin-token>

无请求体,成功返回 data: null。界面二次确认后调用,仅清空 STEP 绑定,不删除已上传对象,不修改 URDF。成功后更新展示并刷新项目;失败提示刷新核对当前状态。

7. 直接下载 STEP

当前项目存在 stepMainUrl 时,显示“下载 STEP”,与“移除绑定”并排。

  • 直接通过浏览器原生链接访问 stepMainUrl,不调用管理端下载接口。
  • 使用 stepFileName 设置 download 属性;跨域下载的附件行为及原始文件名以 OSS 返回的 Content-Disposition 为准。
  • 保留新窗口打开方式,避免遗留对象缺少附件响应头时离开管理页面。
  • 不携带管理端 Authorization,不先 fetch / Blob,不将最高 500 MiB 的文件整体读入前端内存。
  • 下载不需要资源服务器允许 JavaScript 跨域读取;上传仍需 OSS 正确配置跨域上传。
  • 替换成功后按钮使用新的资源地址;移除绑定后隐藏下载按钮。历史链接仍可访问是后端既定语义。

8. 实际错误码

HTTP code 前端处理
400 STEP_INVALID_FILE 展示后端错误及 requestId
413 STEP_FILE_TOO_LARGE 展示限额错误,前端选择时也校验 500 MiB
409 STEP_FILE_MISSING 已上传对象不可用,重新签名上传
409 STEP_FILE_SIZE_MISMATCH 已上传对象不可用,重新签名上传
5xx OSS_ERROR / OSS_UNAVAILABLE 若已上传则保留请求,允许手动重试确认
401 既有鉴权错误 沿用管理端登出及登录跳转

其余权限、项目状态、存储和网络异常沿用现有请求层。前端不依赖 STEP_BATCH_EXPIRED、STEP_BATCH_MISMATCH、STEP_BINDING_CHANGED 等旧需求中的批次状态错误。

9. 对应代码与验证

  • src/api/index.ts:uploadStep、confirmStep、removeStep。
  • src/api/request.ts:复用既有 requestAdmin 和 uploadOssFile。
  • src/api/types.ts:STEP 签名、确认请求、项目资源字段类型。
  • src/components/project/StepPanel.tsx:阶段反馈、重试确认、移除和直接下载。
  • src/components/project/StepFilePicker.tsx、stepFiles.ts:单文件选择与限制。
  • tests/step.spec.ts:接口包装/方法/鉴权、multipart 字段顺序、OSS 对象名与原始名、失败重试、签名过期后确认、移除、跨域原生下载及中文文件名。
npx playwright test tests/step.spec.ts
npm run build
npx playwright test

自动化测试拦截管理 API 和 OSS,不对真实环境执行上传、绑定或删除;它验证前端行为与文档契约,不能代替真实环境的接口/OSS 联调。