Files

148 lines
8.3 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.
# 个人项目、广场与封面接口
先执行[项目建表 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 对象,一期不提供自动垃圾回收。