148 lines
8.3 KiB
Markdown
148 lines
8.3 KiB
Markdown
# 个人项目、广场与封面接口
|
||
|
||
先执行[项目建表 SQL](project-schema.md),再部署服务。接口继续使用 `{code,message,data,requestId}`;`projectCode`、`ownerUserCode` 等均为业务编码,不返回数据库主键。
|
||
|
||
## 1. 前端调用顺序与权限
|
||
|
||
1. 完成[需求生成](robot-demand-api.md),获取状态为 `ready` 的 `analysisId`。
|
||
2. 调用 `POST /api/projects`,将该值作为 `analysisCode`,保存为当前用户的私有项目。
|
||
3. 需要封面时,用户选择图片或前端对装配预览截图,通过专用封面接口上传。
|
||
4. 发布前必须存在有效封面;有缺件但可预览的方案也可发布,前端保留缺件和校验提示。
|
||
5. 广场列表和详情无需登录;登录后可以 fork 到自己的工作空间,副本默认私有。
|
||
|
||
除两个广场 GET 接口外,所有项目接口都需要 `Authorization: Bearer <token>`。用户归属从认证主体获取,不传用户编码。无 Token 可匿名浏览广场;主动携带无效 Token 时沿用现有鉴权规则返回 401。
|
||
|
||
`GET /api/projects` 即“我的工作空间”。项目装配内容保存后固定,只能修改名称、简介、封面和发布状态;重新拼装后另存一个项目。不提供任意模型文件上传、替换或文件编辑接口。
|
||
|
||
组件禁用只影响新拼装方案和替代候选,不影响已保存项目的独立装配快照及展示。
|
||
|
||
| 方法 | 路径 | 请求 | 用途 |
|
||
| --- | --- | --- | --- |
|
||
| POST | `/api/projects` | 创建 JSON | 保存生成结果 |
|
||
| GET | `/api/projects` | `page`、`size` | 当前用户项目列表 |
|
||
| GET | `/api/projects/{projectCode}` | 无 | 当前用户项目详情 |
|
||
| PATCH | `/api/projects/{projectCode}` | 修改 JSON | 修改名称、简介 |
|
||
| DELETE | `/api/projects/{projectCode}` | 无 | 软删除,返回 `{success:true}` |
|
||
| POST | `/api/projects/{projectCode}/cover` | multipart `file` | 上传或替换封面 |
|
||
| POST | `/api/projects/{projectCode}/publish` | 无 | 发布到广场 |
|
||
| POST | `/api/projects/{projectCode}/unpublish` | 无 | 取消发布 |
|
||
| GET | `/api/plaza/projects` | `page`、`size` | 匿名浏览广场 |
|
||
| GET | `/api/plaza/projects/{projectCode}` | 无 | 匿名查看公开详情 |
|
||
| POST | `/api/plaza/projects/{projectCode}/fork` | 无 | fork 为自己的私有项目 |
|
||
|
||
所有者详情及写操作只能操作自己的项目,即使目标项目公开也不能直接修改。其他用户查看公开项目应使用广场详情接口。无权访问、不存在或已删除的项目返回 404;取消发布后的广场详情及 fork 也返回 404。项目响应设置 `Cache-Control: no-store`。
|
||
|
||
## 2. 保存、修改与响应
|
||
|
||
创建请求示例:
|
||
|
||
```json
|
||
{
|
||
"analysisCode": "DN-22222222222222222222222222222222",
|
||
"projectName": "我的机器人",
|
||
"description": "躯干与右臂装配方案"
|
||
}
|
||
```
|
||
|
||
`analysisCode`、`projectName` 必填,分别最多 64、128 字符;名称不能全为空白。简介可省略或为 null,保存为空字符串,最多 2000 字符。重复保存同一方案会创建独立的新项目。
|
||
|
||
来源必须是当前用户未过期会话的当前已完成版本,且有可预览组件;处理中、失败、被新消息替代、无匹配或 `assembly.status=blocked` 的结果不能保存。服务端读取自己的生成快照,不接受客户端上传自定义装配 JSON。
|
||
|
||
PATCH 请求只接受 `projectName` 和 `description`。字段省略或为 null 时保持原值;简介传 `""` 表示清空,名称不能清空。客户端提交 `snapshot`、`visibility`、`coverRelativePath`、`ownerUserCode` 等额外字段返回 422。
|
||
|
||
创建、详情、修改、上传、发布、取消发布和 fork 返回同一项目结构:
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "success",
|
||
"data": {
|
||
"projectCode": "RP-11111111111111111111111111111111",
|
||
"ownerUserCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
|
||
"projectName": "我的机器人",
|
||
"description": "躯干与右臂装配方案",
|
||
"coverRelativePath": null,
|
||
"coverUrl": null,
|
||
"schemaVersion": "project-v1",
|
||
"matchStatus": "partial",
|
||
"assemblyStatus": "ready",
|
||
"sourceProjectCode": null,
|
||
"visibility": "PRIVATE",
|
||
"publishedAt": null,
|
||
"createdAt": "2026-10-20T02:00:00Z",
|
||
"updatedAt": "2026-10-20T02:00:00Z",
|
||
"snapshot": {
|
||
"status": "partial",
|
||
"rootCategory": "TORSO_0",
|
||
"searchLimited": false,
|
||
"totals": {},
|
||
"unmetRequirements": [],
|
||
"missingParts": [],
|
||
"missingPartGroups": [],
|
||
"requirementChecks": [],
|
||
"assembly": {},
|
||
"components": []
|
||
}
|
||
},
|
||
"requestId": "project-save-001"
|
||
}
|
||
```
|
||
|
||
示例中的 `snapshot` 子数组和对象作结构占位,真实成功项目一定包含非空组件和可预览装配。其 `components`、`assembly`、汇总、缺件及校验字段沿用生成响应 `match` 中的展示结构,可复用现有预览器。快照去除原始对话、需求图片、来源解析/会话信息、内部字段和替代方案列表,不返回 `sourceAnalysisCode`。
|
||
|
||
列表返回 `{items,page,size,total}`;`items` 与项目结构相同,但省略 `snapshot`。`page` 默认 1,`size` 默认 20、范围 1–100。个人列表按 `updatedAt` 倒序,广场按 `publishedAt` 倒序,时间相同按项目编码倒序。
|
||
|
||
## 3. OSS 封面
|
||
|
||
```javascript
|
||
async function uploadProjectCover(token, projectCode, fileOrScreenshotBlob) {
|
||
const form = new FormData();
|
||
form.append("file", fileOrScreenshotBlob, "cover.png");
|
||
const response = await fetch(`/api/projects/${projectCode}/cover`, {
|
||
method: "POST",
|
||
headers: { Authorization: `Bearer ${token}` },
|
||
body: form
|
||
});
|
||
const result = await response.json();
|
||
if (!response.ok) throw result;
|
||
return result.data;
|
||
}
|
||
```
|
||
|
||
不要手动设置 multipart 的 Content-Type。支持 PNG、JPEG、WebP,每张不超过 8MiB,文件内容须与 MIME 一致;文件名由服务端生成,忽略客户端文件名,不接受对象路径或 URL。
|
||
|
||
```text
|
||
数据库 cover_relative_path:
|
||
projects/RP-xxx/covers/uuid.png
|
||
|
||
OSS 对象键(示例测试环境):
|
||
cadworld_dev/projects/RP-xxx/covers/uuid.png
|
||
|
||
响应 coverUrl:
|
||
https://你的OSS或CDN域名/cadworld_dev/projects/RP-xxx/covers/uuid.png
|
||
```
|
||
|
||
配置 `OSS_ACCESS_KEY_ID`、`OSS_ACCESS_KEY_SECRET`、`OSS_REGION`、`OSS_BUCKET`、`OSS_ROOT_PREFIX` 和 `APP_STORAGE_PUBLIC_BASE_URL`。公开访问基址只填写 OSS/CDN 域名或统一基址,不重复附加环境根目录,不能使用管理端下载代理地址。浏览器通过返回的 URL 直接加载图片。
|
||
|
||
后端接收图片并上传 OSS,成功后才更新项目路径;失败保留原封面。数据库关联失败会尝试清理本次新对象,失败日志带项目编码及 requestId,供排查补偿。每次替换都产生新路径,不覆盖旧图片。
|
||
|
||
## 4. 发布、fork 与错误
|
||
|
||
发布成功后 `visibility=PUBLIC`、`publishedAt` 有值;重复发布保留原时间。取消发布后改为 `PRIVATE` 且清空发布时间,再次发布生成新时间。发布时校验快照可预览以及封面对象确实存在。
|
||
|
||
fork 不需要请求体,沿用来源名称和简介,复制独立装配快照,记录 `sourceProjectCode`,新项目归当前用户并默认为私有。封面共享同一不可覆盖的 OSS 对象,替换或删除原项目不影响副本;来源重新发布、修改简介或更换封面也不会自动同步到副本。
|
||
|
||
| HTTP | 业务码 | 含义 |
|
||
| --- | --- | --- |
|
||
| 401 | `UNAUTHORIZED` | 写操作未登录或 Token 失效 |
|
||
| 404 | `PROJECT_NOT_FOUND` | 项目不存在、已删除、无权访问或来源不再公开 |
|
||
| 404 | `DEMAND_NOT_FOUND` | 来源解析不存在、不属于当前用户或会话过期 |
|
||
| 409 | `PROJECT_RESULT_UNAVAILABLE` | 来源未完成、版本已更新或装配结果不可预览 |
|
||
| 409 | `PROJECT_COVER_REQUIRED` | 发布前缺少封面或 OSS 对象已不存在 |
|
||
| 413 | `UPLOAD_TOO_LARGE` / `INVALID_REQUEST` | 封面超过限制;后者由 multipart 请求限制返回 |
|
||
| 422 | `INVALID_PROJECT_COVER` | 空图片、不支持的格式或 MIME 与文件头不一致 |
|
||
| 422 | `INVALID_REQUEST` | JSON 字段、长度或分页参数非法 |
|
||
| 502 | `OSS_*_FAILED` | OSS 上传或对象校验失败 |
|
||
|
||
部署顺序:执行建表 SQL → 配置 OSS 和访问域名 → 部署服务 → 验证保存、封面上传、匿名广场及跨账号 fork。替换封面和软删除项目不立即删除旧 OSS 对象,一期不提供自动垃圾回收。
|