# 个人项目、广场与封面接口 先执行[项目建表 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 时沿用现有鉴权规则返回 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 对象,一期不提供自动垃圾回收。