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

186 lines
8.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.
# 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 <admin-token>
```
请求:
```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<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. 确认绑定与失败重试
```http
PUT /admin-api/projects/{projectCode}/step
Content-Type: application/json
Authorization: Bearer <admin-token>
```
请求使用签名返回的 `batchCode` 和原始文件清单:
```json
{
"batchCode": "<signature.batchCode>",
"files": [
{ "relativePath": "机械臂 装配.STEP", "sizeBytes": 10485760 }
]
}
```
返回 `data` 为完整 `ProjectView`。前端核验项目编号和 STEP 三个字段后展示成功,并刷新项目详情。
本期后端语义:
- 不保存上传批次,不比较历史签名清单;仅核验该项目 STEP 目录下对象存在及大小。
- 每次 PUT 都重新核验并写入,**没有严格幂等或绑定冲突检测**。
- 上传签名过期后,已经上传的对象仍可确认。
- 并发以最后一次成功写入为准;旧请求可在替换或移除后重新绑定旧对象。
前端处理:
- 签名/上传失败时保留所选文件,允许重新签名上传,不提前修改当前绑定。
- OSS 成功后,若确认遭遇网络异常、OSS 故障或无效响应,保留原请求,仅手动重试 PUT,不重复上传。
- 异常后刷新项目状态,不把失败响应视为服务端一定未写入,也不自动重试。
- 点击“重试绑定”先提示重新写入可能覆盖其他操作;确认后才发送请求,取消不发送。
- 对象缺失或大小不匹配时丢弃待确认请求,要求重新上传。
- 重新选文件、清除选择、离开项目后不继续重试旧请求;移除操作也会放弃本地待确认请求。
## 6. 移除绑定
```http
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 对象名与原始名、失败重试、签名过期后确认、移除、跨域原生下载及中文文件名。
```bash
npx playwright test tests/step.spec.ts
npm run build
npx playwright test
```
自动化测试拦截管理 API 和 OSS,不对真实环境执行上传、绑定或删除;它验证前端行为与文档契约,不能代替真实环境的接口/OSS 联调。