186 lines
8.1 KiB
Markdown
186 lines
8.1 KiB
Markdown
# 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 联调。
|