Files

8.3 KiB
Raw Permalink Blame History

个人项目、广场与封面接口

先执行项目建表 SQL,再部署服务。接口继续使用 {code,message,data,requestId};projectCode、ownerUserCode 等均为业务编码,不返回数据库主键。

1. 前端调用顺序与权限

  1. 完成需求生成,获取状态为 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. 保存、修改与响应

创建请求示例:

{
  "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 返回同一项目结构:

{
  "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 封面

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。

数据库 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 对象,一期不提供自动垃圾回收。