# 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. 项目字段和响应层级 ```ts interface StepProjectFields { stepMainUrl: string | null; // 当前公开资源地址,也用于直接下载 stepFileName: string | null; // 原始文件名,保留中文、空格及大小写 stepSizeBytes: number | null; } ``` 未绑定时三个字段为 `null`。前端也兼容旧项目响应暂未包含这些字段的情况。 所有管理 API 使用既有响应包装: ```json { "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. 上传签名 ```http POST /admin-api/projects/{projectCode}/step/signature Content-Type: application/json Authorization: Bearer ``` 请求: ```json { "files": [ { "relativePath": "机械臂 装配.STEP", "sizeBytes": 10485760 } ] } ``` 文件规则: - `files` 只允许一个元素;扩展名大小写不敏感。 - `relativePath` 是单个原始文件名,最多 1024 字符,不接受目录、反斜杠、冒号和控制字符。 - `sizeBytes` 为正整数字节数,最大 524288000。 - 不根据浏览器 MIME 推断或拒绝 STEP 文件。 返回 `data`: ```ts interface StepUploadSignature { batchCode: string; mainRelativePath: string; uploadUrl: string; expiresAt: string; // 带时区的 ISO 时间,例如 2026-11-02T08:15:00Z files: [{ relativePath: string; objectKey: string; formFields: Record; }]; } ``` 签名有效期为 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. 确认绑定与失败重试 ```http PUT /admin-api/projects/{projectCode}/step Content-Type: application/json Authorization: Bearer ``` 请求使用签名返回的 `batchCode` 和原始文件清单: ```json { "batchCode": "", "files": [ { "relativePath": "机械臂 装配.STEP", "sizeBytes": 10485760 } ] } ``` 返回 `data` 为完整 `ProjectView`。前端核验项目编号和 STEP 三个字段后展示成功,并刷新项目详情。 本期后端语义: - 不保存上传批次,不比较历史签名清单;仅核验该项目 STEP 目录下对象存在及大小。 - 每次 PUT 都重新核验并写入,**没有严格幂等或绑定冲突检测**。 - 上传签名过期后,已经上传的对象仍可确认。 - 并发以最后一次成功写入为准;旧请求可在替换或移除后重新绑定旧对象。 前端处理: - 签名/上传失败时保留所选文件,允许重新签名上传,不提前修改当前绑定。 - OSS 成功后,若确认遭遇网络异常、OSS 故障或无效响应,保留原请求,仅手动重试 PUT,不重复上传。 - 异常后刷新项目状态,不把失败响应视为服务端一定未写入,也不自动重试。 - 点击“重试绑定”先提示重新写入可能覆盖其他操作;确认后才发送请求,取消不发送。 - 对象缺失或大小不匹配时丢弃待确认请求,要求重新上传。 - 重新选文件、清除选择、离开项目后不继续重试旧请求;移除操作也会放弃本地待确认请求。 ## 6. 移除绑定 ```http DELETE /admin-api/projects/{projectCode}/step Authorization: Bearer ``` 无请求体,成功返回 `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 对象名与原始名、失败重试、签名过期后确认、移除、跨域原生下载及中文文件名。 ```bash npx playwright test tests/step.spec.ts npm run build npx playwright test ``` 自动化测试拦截管理 API 和 OSS,不对真实环境执行上传、绑定或删除;它验证前端行为与文档契约,不能代替真实环境的接口/OSS 联调。