8.1 KiB
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 直传
- 前端核验签名中的文件数量和原始名称与当前选择一致。
- 将
formFields全部按原值追加到FormData,包含 Content-Disposition 等字段。 - 最后追加
file字段,内容为所选原文件。 - 向
uploadUrl发起 multipart POST,不添加管理端 Authorization,也不手写 Content-Type / boundary。 - 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 联调。