Files
community/docs/vibemake-api.md
T
admin 27f5849657 /admin-api/projects/{projectCode}/uploads/commit
用户端和管理端表单项上限设为 1003,支持每批 500 个文件。
数量超限单独返回 UPLOAD_TOO_MANY_PARTS,补充排查日志。
2026-10-27 13:44:36 +08:00

1496 lines
79 KiB
Markdown
Raw 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.
# Vibemake 前端接口对接文档
供社区列表、项目详情、登录、我的工作区和在线文件编辑页面使用。前端通过 Vibemake 后端完成所有业务操作;登录 Token 是平台 Token,前端不连接 Gitea、不持有 Gitea 凭据。
项目模块和 Java 包名使用 `vibemake`,对外接口路径保持原有命名,包括 `/api/community/**`,前端调用无需调整。
当前支持项目、文件、目录、提交、手动发布、快照 Fork、评论和点赞,以及可配置开启的 Maker AI(聊天问答、查找、创建空项目、Fork)。项目发布后,后续提交只更新工作区,需要再次调用发布接口才更新社区代码。没有服务端草稿保存、独立工作区实体或项目类型表。
## 阅读导航
- [接入约定](#接入约定)
- [接口总览](#接口总览)
- [响应数据结构](#响应数据结构)
- [登录和用户](#登录和用户)
- [类型与项目列表](#类型与项目列表)
- [我的项目管理](#我的项目管理)
- [项目封面与 OSS 直传](#项目封面与-oss-直传)
- [项目 URDF 文件夹](#项目-urdf-文件夹)
- [目录和文件读取](#目录和文件读取)
- [文件编辑与上传提交](#文件编辑与上传提交)
- [社区发布和撤回](#社区发布和撤回)
- [社区详情和 Fork](#社区详情和-fork)
- [评论和点赞](#评论和点赞)
- [Maker AI](#maker-ai)
- [错误码与前端处理](#错误码与前端处理)
- [页面调用顺序](#页面调用顺序)
- [前端请求示例](#前端请求示例)
- [后端人工核对](#后端人工核对)
## 接入约定
### 地址和请求头
本机默认后端地址为 `http://localhost:8993`,接口前缀为 `/api`。实际端口可由 `SERVER_PORT` 或 `PORT` 覆盖,部署环境地址由后端提供。
| 项目 | 约定 |
| --- | --- |
| JSON 请求 | `Content-Type: application/json` |
| 登录凭据 | `Authorization: Bearer <平台 token>`,注意 `Bearer` 的大小写和空格 |
| 上传 | `multipart/form-data`,浏览器使用 FormData,不手动设置 Content-Type |
| 业务标识 | 使用 `projectCode`、`commentCode`、`userCode`,不使用数据库 ID |
| 接口调试 | `/swagger-ui.html` |
| OpenAPI | `/v3/api-docs` |
后端按环境为 `/api/**` 配置跨域白名单,配置项为 `vibemake.cors.allowed-origins`:
| 后端环境 | 允许的前端 Origin |
| --- | --- |
| test(默认) | `https://dev-vibemake.robotquan.com` |
| prod | `https://vibemake.robotquan.com` |
允许 `GET、HEAD、POST、PUT、PATCH、DELETE、OPTIONS`,请求头允许 `Authorization、Content-Type、Accept`,预检缓存 3600 秒。前端继续通过 `Authorization: Bearer <平台 token>` 鉴权,无需设置 `credentials: 'include'`;后端不启用跨域 Cookie 凭据。成功及鉴权、业务错误响应均支持上述来源,并暴露 `X-Request-Id`、`Content-Disposition`、`Retry-After` 响应头。
其他域名、HTTP 来源、非默认端口和另一环境的前端来源均不在默认白名单内。本地开发继续通过前端开发服务器代理 `/api`;部署代理需透传 `Origin`、预检请求及后端 CORS 响应头,避免重复添加跨域头。OSS 直传的跨域规则仍需单独在 Bucket 配置。
### 统一响应
除成功的文件下载和 AI 对话 SSE 外,响应为以下 JSON 结构;SSE 每个事件的 data 也使用此包装。所有成功接口使用 HTTP 200,创建、删除、退出登录也不返回 201 或 204。
```json
{
"code": "OK",
"message": "成功",
"data": null,
"requestId": "44444444444444444444444444444444"
}
```
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| code | string | 成功为 `OK`,失败为业务错误码 |
| message | string | 可用于提示用户,不要通过中文 message 判断错误类型 |
| data | 对象、数组或 null | 成功数据;失败通常为 null,部分仓库错误包含 projectCode |
| requestId | string | 本次请求的排查标识,与响应头 `X-Request-Id` 一致 |
下面标为“data 示例”的代码块只展示 `data`,实际响应仍有上面的包装。示例业务编码和 SHA 均为虚构,调用时必须使用接口返回的真实值。
分页接口的 data 为:
```json
{
"items": [],
"page": 1,
"size": 20,
"total": 0
}
```
`page` 从 1 开始,范围为 1~100000;`size` 默认 20,范围为 1~100。`total` 为数字,不返回额外的 `pages` 字段。空列表是 `items: []`。
### 时间和版本
项目和评论的时间字段按 UTC 保存,JSON 格式为 `2026-10-13T08:30:00`,可能带小数秒,**没有时区后缀**。前端解析这些字段时应按 UTC 处理,再转换成用户时区;不要直接当成本地时间。历史提交的 `authorDate` 来自仓库服务,可带 `Z` 或时区偏移。
Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。几个版本字段的用途不同:
| 字段 | 来源 | 用途 |
| --- | --- | --- |
| commitSha | 目录、文件、提交结果、历史提交 | 读取指定版本;提交结果中的值是新版本 |
| expectedCommitSha | 提交请求 | 编辑或上传所基于的工作区版本,防止覆盖其他提交 |
| publishedCommitSha | 项目详情 | 社区当前发布版本;Fork 时原样提交此值 |
| blobSha | 文件或目录条目 | 文件或目录对应的 Git 对象标识,前端不用它提交文件 |
新建、Fork 和 GitHub 初始化导入的 `projectCode` 为 12 位小写字母和数字,例如 `7m4k9x2p8q6r`。已有 32 位项目编码及链接继续有效。前端将编码作为不透明字符串传递,不截取、不补齐,也不固定要求 32 位;`sourceProjectCode`、AI 的 `previousProjectCodes` 及结果编码同样兼容两种长度,最大长度仍为 32。新注册用户的 `userCode` 同样为 12 位小写字母和数字,历史用户保留原有 32 位编码;登录、用户信息、项目归属、评论作者及封面上传路径均使用真实编码,不假定固定长度。评论编码及 Commit SHA 的规则不变。
项目详情不包含工作区当前 main 的 SHA。进入编辑器、提交或发布前,从工作区目录或文件接口获取 `commitSha`。
## 接口总览
“可选登录”表示匿名也能访问;带有效 Token 时项目响应可返回当前用户的 `liked` 状态。公开接口携带已失效的 Bearer Token 仍会返回 401。
| 方法 | 路径 | 登录 | 成功 data |
| --- | --- | --- | --- |
| GET | `/api/auth/captcha` | 否 | Captcha |
| POST | `/api/auth/login` | 否 | Login |
| POST | `/api/auth/logout` | 是 | null |
| GET | `/api/users/me` | 是 | User |
| GET | `/api/project-types` | 否 | ProjectType[] |
| POST | `/api/uploads/project-covers/signature` | 是 | CoverUploadSignature |
| GET | `/api/workspace/projects` | 是 | PageResult&lt;Project&gt; |
| POST | `/api/workspace/projects` | 是 | Project |
| GET | `/api/workspace/projects/{projectCode}` | 是 | Project |
| PATCH | `/api/workspace/projects/{projectCode}` | 是 | Project |
| DELETE | `/api/workspace/projects/{projectCode}` | 是 | null |
| POST | `/api/workspace/projects/{projectCode}/urdf/signature` | 是 | UrdfUploadSignature |
| PUT | `/api/workspace/projects/{projectCode}/urdf` | 是 | Project |
| DELETE | `/api/workspace/projects/{projectCode}/urdf` | 是 | null |
| GET | `/api/workspace/projects/{projectCode}/tree` | 是 | Tree |
| GET | `/api/workspace/projects/{projectCode}/files` | 是 | ProjectFile 或下载二进制 |
| POST | `/api/workspace/projects/{projectCode}/commits` | 是 | Commit |
| GET | `/api/workspace/projects/{projectCode}/commits` | 是 | PageResult&lt;HistoryEntry&gt; |
| POST | `/api/workspace/projects/{projectCode}/uploads/commit` | 是 | Commit |
| PUT | `/api/workspace/projects/{projectCode}/publication` | 是 | Project |
| DELETE | `/api/workspace/projects/{projectCode}/publication` | 是 | null |
| GET | `/api/community/projects` | 可选 | PageResult&lt;Project&gt; |
| GET | `/api/community/projects/{projectCode}` | 可选 | Project |
| GET | `/api/community/projects/{projectCode}/tree` | 可选 | Tree |
| GET | `/api/community/projects/{projectCode}/files` | 可选 | ProjectFile 或下载二进制 |
| POST | `/api/community/projects/{projectCode}/forks` | 是 | Project |
| GET | `/api/community/projects/{projectCode}/comments` | 可选 | PageResult&lt;Comment&gt; |
| POST | `/api/community/projects/{projectCode}/comments` | 是 | Comment |
| DELETE | `/api/comments/{commentCode}` | 是 | null |
| PUT | `/api/community/projects/{projectCode}/like` | 是 | null |
| DELETE | `/api/community/projects/{projectCode}/like` | 是 | null |
| POST | `/api/community/ai/chat` | 是 | SSE 事件流,见 Maker AI |
## 响应数据结构
以下 TypeScript 类型与当前 JSON 字段对应。项目列表、工作区详情、社区详情、创建、修改、发布和 Fork 共用 Project 结构。
```typescript
/** 无时区后缀,按 UTC 解释。 */
export type UtcDateTime = string;
export interface ApiResponse<T> {
code: string;
message: string;
data: T | null;
requestId: string;
}
export interface PageResult<T> {
items: T[];
page: number;
size: number;
total: number;
}
export interface PublicUser {
userCode: string | null; // 用户记录不可用时可能为 null
nickname: string;
}
export interface User {
userCode: string;
nickname: string;
email: string;
}
export interface Captcha {
captchaCode: string;
image: string; // PNG data URL,可直接作为 img 的 src
expiresIn: number; // 秒
}
export interface Login {
token: string;
tokenType: 'Bearer';
expiresIn: number; // 秒
user: User;
}
export interface ProjectType {
code: string;
name: string;
}
export interface Project {
projectCode: string;
name: string;
description: string;
coverUrl: string | null; // 固定公开 HTTPS 图片地址,支持 OSS/CDN 和外部图片
urdfMainUrl: string | null; // 当前 URDF 主文件公开地址,无资源时为 null
urdfBaseUrl: string | null; // 当前资源包公开目录地址,以 / 结尾,无资源时为 null
projectType: string;
owner: PublicUser;
repoStatus: 'CREATING' | 'READY' | 'FAILED';
publishStatus: 'UNPUBLISHED' | 'PUBLISHED' | 'BLOCKED';
publishedCommitSha: string | null;
publishedAt: UtcDateTime | null;
sourceProjectCode: string | null;
sourceCommitSha: string | null;
sourceRepositoryUrl: string | null; // 在线迁移任务记录的原仓库地址
sourceLicense: string | null; // 原仓库许可证标识,未识别时为 null
likeCount: number;
commentCount: number;
liked: boolean;
createdAt: UtcDateTime;
updatedAt: UtcDateTime;
}
export interface CoverUploadSignature {
uploadUrl: string;
objectKey: string;
coverUrl: string;
expiresAt: UtcDateTime; // 无时区后缀,按 UTC 解释
formFields: Record<string, string>;
}
export interface UrdfFile {
relativePath: string;
sizeBytes: number;
}
export interface UrdfUploadSignature {
batchCode: string;
mainRelativePath: string;
uploadUrl: string;
expiresAt: UtcDateTime; // 无时区后缀,按 UTC 解释
files: Array<{
relativePath: string;
objectKey: string;
formFields: Record<string, string>;
}>;
}
export interface TreeEntry {
path: string; // 从仓库根目录开始的完整相对路径
name: string;
type: string; // 普通目录为 dir,普通文件为 file
size: number; // 字节
blobSha: string;
}
export interface Tree {
commitSha: string;
path: string; // 根目录为 ""
entries: TreeEntry[]; // 当前目录的直接子项
}
export interface ProjectFile {
commitSha: string;
path: string;
blobSha: string;
size: number; // 字节
encoding: 'utf-8' | 'base64';
content: string;
editable: boolean;
}
export interface Commit {
commitSha: string;
message: string;
}
export interface HistoryEntry {
commitSha: string;
message: string;
authorName: string;
authorDate: string; // 仓库服务返回的日期字符串
}
export interface Comment {
commentCode: string;
author: PublicUser;
content: string;
createdAt: UtcDateTime;
}
```
### 项目示例与状态含义
已发布项目的 data 示例:
```json
{
"projectCode": "22222222222222222222222222222222",
"name": "机器人示例项目",
"description": "模型、配置和说明文件",
"coverUrl": "https://images.example.com/vibemake/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png",
"urdfMainUrl": null,
"urdfBaseUrl": null,
"projectType": "GENERAL",
"owner": {
"userCode": "111111111111",
"nickname": "用户_11111111"
},
"repoStatus": "READY",
"publishStatus": "PUBLISHED",
"publishedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"publishedAt": "2026-10-13T08:30:00",
"sourceProjectCode": null,
"sourceCommitSha": null,
"likeCount": 3,
"commentCount": 2,
"liked": false,
"createdAt": "2026-10-13T08:00:00",
"updatedAt": "2026-10-13T08:30:00"
}
```
| 状态或字段 | 前端使用方式 |
| --- | --- |
| repoStatus = CREATING | 仓库初始化未完成,可能需要人工核对;关闭文件读取、提交和发布入口 |
| repoStatus = READY | 仓库已就绪,可进入文件操作;仍需处理版本冲突或写入待核对错误 |
| repoStatus = FAILED | 初始化失败,显示失败状态;仍可修改项目信息或删除项目 |
| publishStatus = UNPUBLISHED | 当前不在社区展示;这是私有项目状态,不是草稿 |
| publishStatus = PUBLISHED | 当前在社区展示 |
| publishStatus = BLOCKED | 管理员下架,不在社区展示;普通撤回不会解除此状态,只有管理员可解除 |
| publishedCommitSha / publishedAt | 撤回后可能仍保留上一次发布值,是否公开必须判断 publishStatus |
| sourceProjectCode / sourceCommitSha | Fork 来源及复制的源版本;普通新项目为 null |
| liked | 当前请求用户是否点赞,匿名访问为 false |
| coverUrl | 固定公开封面地址,null 时展示前端默认图;工作区、社区、Fork 和 AI 卡片共用此字段 |
| urdfMainUrl / urdfBaseUrl | 当前 URDF 主文件与资源目录的公开地址,无资源时均为 null;工作区、社区、AI 卡片均返回,Fork 使用独立副本 |
工作区归属由 `owner.userCode` 判断,不存在 `workspaceCode`。`updatedAt` 不代表仓库最新提交时间。来源项目撤回或删除后,sourceProjectCode 仍可能存在,访问该来源的社区详情会返回 404。
## 登录和用户
### 获取图片验证码
`GET /api/auth/captcha`,无需登录,无参数。
data 示例中 image 仅展示格式前缀,实际值为完整图片:
```json
{
"captchaCode": "55555555555555555555555555555555",
"image": "data:image/png;base64,...",
"expiresIn": 120
}
```
将 image 作为图片 src,将 captchaCode 与用户输入答案一起提交。有效期默认 120 秒,以接口返回值为准。验证码只使用一次,答案错误也会消耗验证码;失败后重新获取图片。答案校验忽略首尾空格和大小写。
### 邮箱登录
`POST /api/auth/login`,无需登录。
| 请求字段 | 必填 | 约束 |
| --- | --- | --- |
| email | 是 | 合法邮箱,最多 254 字符,前端提交前去掉首尾空格 |
| captchaCode | 是 | 验证码接口返回的标识 |
| captchaAnswer | 是 | 用户输入的图片验证码 |
请求:
```json
{
"email": "user@example.com",
"captchaCode": "55555555555555555555555555555555",
"captchaAnswer": "ABCDE"
}
```
响应示例:
```json
{
"code": "OK",
"message": "成功",
"data": {
"token": "example-platform-token",
"tokenType": "Bearer",
"expiresIn": 86400,
"user": {
"userCode": "111111111111",
"nickname": "用户_11111111",
"email": "user@example.com"
}
},
"requestId": "44444444444444444444444444444444"
}
```
首次登录自动创建普通用户,邮箱统一转成小写。正常的 `USER` 和 `ADMIN` 都使用邮箱与图片验证码登录社区,请求只需 `email`、`captchaCode`、`captchaAnswer`,不需要密码。当前不发送邮件,也不验证邮箱归属;知道账号邮箱并通过图片验证码即可登录其社区身份。登录失败后重新获取图片验证码再提交。`OFFICIAL`、禁用账号和其他角色不能登录。
社区 Token 有效期默认 24 小时,以 expiresIn 为准,不是 JWT,没有刷新 Token 接口;会话存于 Redis,应用重启后保留未过期会话;首次从本机缓存版本升级需要重新登录。社区与后台独立保存登录状态,Token 不通用。管理员在社区工作区也只能操作自己的项目,后台仍使用邮箱和密码登录;修改后台密码或禁用账号会使该账号两端旧会话失效。现有登录请求频率限制同样适用于管理员社区登录。
### 当前用户和退出登录
`GET /api/users/me`,需要登录,data 为 User;只有本人用户接口和登录响应包含邮箱,公开作者信息不包含邮箱。
`POST /api/auth/logout`,需要登录,无请求体,成功 data 为 null。前端清除本地登录状态。已失效 Token 调用退出接口会返回 401,同样可以清除本地登录状态。
## 类型与项目列表
### 可选项目类型
`GET /api/project-types`,无需登录,无参数,data 为 ProjectType[]:
```json
[
{ "code": "GENERAL", "name": "通用" },
{ "code": "HUMANOID", "name": "人形" },
{ "code": "QUADRUPED", "name": "四足" },
{ "code": "WHEELED", "name": "轮式" },
{ "code": "ROBOTIC_ARM", "name": "机械臂" }
]
```
左侧类型导航和创建项目下拉框使用这个接口,不在前端写死类型码。“全部”筛选不传 type。当前内置 GENERAL(通用)、HUMANOID(人形)、QUADRUPED(四足)、WHEELED(轮式)、ROBOTIC_ARM(机械臂),创建或修改项目时通过 projectType 提交对应 code,列表筛选时通过 type 提交对应 code。
### 我的项目列表和社区项目列表
- `GET /api/workspace/projects`:需要登录,返回本人所有未删除项目,包括 CREATING、FAILED 项目。
- `GET /api/community/projects`:可选登录,仅返回 READY 且 PUBLISHED 的项目。
两者查询参数相同:
| 参数 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- |
| page | 否 | 1 | 页码 |
| size | 否 | 20 | 每页数量 |
| type | 否 | 无 | 项目类型 code;注意查询字段叫 type,不是 projectType |
| keyword | 否 | 无 | 名称或描述的模糊查询,最多 200 字符;空白值不筛选 |
请求示例:`GET /api/community/projects?page=1&size=20&type=GENERAL&keyword=机器人`。使用 URLSearchParams 编码中文等查询值。
成功 data 为 PageResult&lt;Project&gt;。工作区按创建时间倒序;社区优先展示已上传并确认绑定 URDF 的项目,同组内按最近发布时间倒序,排序后分页。不支持客户端指定排序。更换类型或关键词时,把 page 重置为 1。
## 我的项目管理
以下接口需要登录,且只能操作当前用户的项目。项目不存在、已删除或属于其他用户,均返回 404。
### 创建项目
`POST /api/workspace/projects`。
| 请求字段 | 必填 | 约束 |
| --- | --- | --- |
| name | 是 | 非空,最多 100 字符,保存时去掉首尾空格 |
| description | 否 | 最多 2000 字符,省略或 null 时保存为空字符串 |
| coverUrl | 否 | 去掉首尾空格后最多 2048 字符;绝对 HTTPS 图片地址,主机名合法且不含用户凭据;省略、null 或空字符串表示无封面 |
| projectType | 是 | 类型接口返回的 code,必须精确匹配,最多 64 字符 |
```json
{
"name": "机器人示例项目",
"description": "模型、配置和说明文件",
"projectType": "GENERAL"
}
```
成功 data 为 Project,状态为 READY、UNPUBLISHED。后端已创建私有仓库、main 分支和 README.md。使用返回的 projectCode 进入工作区详情,然后读取根目录获取当前 commitSha。
创建是同步请求,没有任务编号、202 响应或操作进度查询接口。请求失败可能已经留下项目记录;先查看错误 data.projectCode 和工作区列表,不要自动重发创建请求。
### 项目详情
`GET /api/workspace/projects/{projectCode}`,无额外参数,data 为 Project。
### 修改项目信息
`PATCH /api/workspace/projects/{projectCode}`。请求字段与创建项目相同,data 为更新后的 Project。
虽然方法为 PATCH,当前接口要求同时提交 name、projectType;description 省略或 null 会清空描述。前端编辑表单应提交完整的 name、description、projectType。coverUrl 省略或 null 保留原封面,传空字符串或纯空白字符串清除,非空值替换封面;后端不下载外部图片,也不校验图片是否存在。
已发布项目的名称、描述、类型、封面会直接更新社区展示,不生成文件 Commit。Fork 继承源项目的封面地址;替换、清除、删除项目不自动删除 OSS 对象,避免影响共用地址的 Fork。
### 删除项目
`DELETE /api/workspace/projects/{projectCode}`,无请求体,成功 data 为 null。
项目逻辑删除并从社区撤回,已有独立 Fork 不受影响。再次操作已删除项目返回 404。
## 项目封面与 OSS 直传
封面可以填写外部 HTTPS 图片地址,也可以使用本节的 OSS 直传。图片二进制由浏览器直接发往 OSS;后端仅提供签名,支持创建项目之前上传,无需 projectCode。该流程与仓库文件上传分开,图片不进入 Gitea,也不生成文件 Commit。
### 获取封面上传签名
`POST /api/uploads/project-covers/signature`,需要登录,JSON 请求:
```json
{
"contentType": "image/png",
"fileSize": 123456
}
```
| 字段 | 必填 | 约束 |
| --- | --- | --- |
| contentType | 是 | image/jpeg、image/png、image/webp;JPG 使用 image/jpeg,不支持 SVG、GIF |
| fileSize | 是 | 文件字节数,1~5242880(5 MiB),超过上限返回 413 |
成功 data 为 CoverUploadSignature,响应带 `Cache-Control: no-store`。以下 Policy、凭据和签名是占位示意,前端必须使用实时返回值:
```json
{
"uploadUrl": "https://examplebucket.oss-cn-hangzhou.aliyuncs.com",
"objectKey": "vibemake_dev/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png",
"coverUrl": "https://images.example.com/vibemake_dev/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png",
"expiresAt": "2026-10-15T02:05:00",
"formFields": {
"key": "vibemake_dev/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png",
"policy": "<Base64 编码的 Policy>",
"x-oss-signature-version": "OSS4-HMAC-SHA256",
"x-oss-credential": "<AccessKeyId>/20261015/cn-hangzhou/oss/aliyun_v4_request",
"x-oss-date": "20261015T020000Z",
"x-oss-signature": "<十六进制签名>",
"content-type": "image/png",
"success_action_status": "200"
}
}
```
签名有效期为 5 分钟;策略绑定 Bucket、完整对象 key、Content-Type、1 字节~5 MiB 的大小范围和成功状态码 200。文件类型按声明的 MIME 约束,后端不读取或解码图片。对象路径由后端生成,日期使用 UTC:test 为 `vibemake_dev/project-covers/{userCode}/{yyyyMMdd}/{随机编码}.{扩展名}`,prod 为 `vibemake/project-covers/...`。不要修改 formFields、对象路径或上传类型。
### 浏览器直传与保存项目
1. 调用签名接口,取得 uploadUrl、formFields 和 coverUrl。
2. 将 formFields 原样加入 FormData,最后追加 file 字段,直接 POST 到 uploadUrl。不手动设置 multipart Content-Type,不向 OSS 发送平台 Authorization。
3. OSS 成功返回 HTTP 200,响应体为空,不要按平台 ApiResponse 解析。成功后再把 coverUrl 写入项目创建或修改请求;上传本身不会自动更新项目。
4. 失败、取消或网络中断时保留现有项目封面。签名过期时重新获取;尚未绑定项目的对象不自动清理。
以下示例复用后文的 `request<T>` 平台请求封装;发往 OSS 的请求直接使用 fetch:
```typescript
async function uploadProjectCover(file: File, token: string, signal?: AbortSignal): Promise<string> {
const signature = await request<CoverUploadSignature>('/uploads/project-covers/signature', {
method: 'POST', token, signal,
body: { contentType: file.type, fileSize: file.size },
});
const form = new FormData();
for (const [name, value] of Object.entries(signature.formFields)) form.append(name, value);
form.append('file', file); // 必须是最后一个字段
const response = await fetch(signature.uploadUrl, {
method: 'POST', body: form, credentials: 'omit', signal,
});
if (response.status !== 200) throw new Error(`封面上传失败:HTTP ${response.status}`);
return signature.coverUrl;
}
async function replaceProjectCover(project: Project, file: File, token: string) {
const coverUrl = await uploadProjectCover(file, token);
return request<Project>(`/workspace/projects/${encodeURIComponent(project.projectCode)}`, {
method: 'PATCH', token,
body: { name: project.name, description: project.description, projectType: project.projectType, coverUrl },
});
}
```
创建项目时同样先上传,再将返回的 coverUrl 与 name、description、projectType 一起提交。仅修改外部封面地址不需要调用签名接口;图片加载失败时前端展示默认图。
| 位置 | HTTP / code | 处理 |
| --- | --- | --- |
| 签名接口 | 401 UNAUTHORIZED | 先登录 |
| 签名接口 | 400 BAD_REQUEST | 检查 MIME、字节数及必填字段 |
| 签名接口 | 413 UPLOAD_TOO_LARGE | 文件超过 5 MiB,压缩或选择其他图片 |
| 签名接口 | 503 OSS_UNAVAILABLE | OSS 未启用;可继续使用外部 HTTPS 图片 |
| OSS 请求 | 非 200 或网络错误 | 不保存新地址;检查签名过期、Policy 限制、Bucket 权限和 CORS;OSS 的错误响应不使用平台包装 |
### 部署配置
服务端启用 `OSS_ENABLED=true`,配置 `OSS_REGION`、`OSS_BUCKET`、`OSS_ACCESS_KEY_ID`、`OSS_ACCESS_KEY_SECRET`;地域 ID 使用 `cn-beijing` 等编码,不带 `oss-` 前缀。Endpoint 自动生成为 `https://oss-{region}.aliyuncs.com`,例如北京为 `https://oss-cn-beijing.aliyuncs.com`,无需配置 Endpoint 环境变量。特殊域名场景可显式设置 `vibemake.oss.endpoint`,优先使用配置值,要求为公网 HTTPS 地址,不带 Bucket、路径、凭据或查询参数。`OSS_PUBLIC_BASE_URL` 可选。启用时配置缺失或不合法会停止启动。密钥不提交仓库、不返回浏览器;浏览器只收到 AccessKeyId 派生的 credential、Policy 和签名。
公开基础地址可以是 OSS 或 CDN 域名,可带基础路径;最终地址为 `{公开基础地址}/{objectKey}`,CDN 路径需正确映射到同一对象。留空时为 `https://{Bucket}.{Endpoint 主机名}/{objectKey}`。API 的 `coverUrl` 继续接收和返回完整 HTTPS URL;数据库仅对本平台当前环境资源保存 `/project-covers/...` 未编码路径,域名和环境根目录由后端配置补齐,外链原样保存。创建、PATCH、清除封面及 Fork 的调用方式不变,不允许客户端改为提交相对路径。
历史完整平台 URL 及当前环境的 URDF key 均兼容读取,读取不自动迁移。更换域名时,在 `vibemake.oss.legacy-public-base-urls` 配置历史公开基础地址(可带 CDN 基础路径,不含环境根目录、凭据、查询参数及片段),或通过 `OSS_LEGACY_PUBLIC_BASE_URLS` 使用英文逗号分隔。后端按域名、端口和完整路径边界匹配当前环境;带查询参数或片段的封面继续按外链保留。迁移 SQL 与回退步骤见 [资源路径迁移](database.md#资源路径历史数据迁移)。
OSS 控制台配置步骤:
1. 准备指定地域的 Bucket,确认 test/prod 的根目录分别为 `vibemake_dev/`、`vibemake/`。目录是对象前缀,不是 Bucket 名。
2. 给服务端 RAM 用户授予对应环境目录的 `oss:PutObject` 权限,例如资源 `acs:oss:*:*:YOUR_BUCKET/vibemake_dev/project-covers/*`;正式环境改为 `vibemake/project-covers/*`,两个环境可使用各自凭据。
3. 配置 Bucket CORS:AllowedOrigins 填真实前端开发、部署 Origin(含协议和端口),AllowedMethods 包含 POST,若使用 fetch 读图则增加 GET、HEAD;AllowedHeaders 允许 Content-Type,可按需要暴露 ETag、x-oss-request-id。调用签名接口可按上述 API 跨域约定直接访问后端,或通过 `/api` 代理访问;后端 API 的 CORS 不能替代 OSS CORS。
4. 对封面目录配置公开 GetObject 读取权限,或使用能够公开返回图片的 CDN;私有源站通过 CDN 时需配置回源鉴权。对象沿用 Bucket 的访问规则,应用不修改整个 Bucket 的 ACL,也不生成临时下载链接。
5. 测试环境完成“获取签名 → 浏览器直传 → 保存项目 → 匿名读取图片”,核对对象 key 和浏览器网络请求;生产环境重复验收 `vibemake/` 路径。
协议参考:[OSS POST V4 签名](https://www.alibabacloud.com/help/en/oss/developer-reference/signature-version-4-recommend)、[服务端签名直传](https://www.alibabacloud.com/help/en/oss/user-guide/obtain-signature-information-from-the-server-and-upload-data-to-oss)。
## 项目 URDF 文件夹
URDF 为可选项目资源,不进入 Gitea,也不生成 Commit。先创建项目取得 `projectCode`,再选择整个文件夹直传 OSS。文件夹内必须恰好有一个 `.urdf` 文件(扩展名忽略大小写,可位于子目录);没有或多个都直接提示失败,无需用户手动选择主文件。前端提前检查,后端在签名、确认时独立校验。
保留所选文件夹内部层级:`relativePath` 去掉浏览器选择的最外层文件夹名称,以资源包根目录为基准;不要扁平化、重命名或改写 URDF 引用。例如 `robot-assets/urdf/robot.urdf` 对应 `urdf/robot.urdf`,`robot-assets/meshes/base.stl` 对应 `meshes/base.stl`。
### 获取 URDF 签名
`POST /api/workspace/projects/{projectCode}/urdf/signature`,需要登录且为项目所有者,项目必须 READY。JSON 请求:
```json
{
"files": [
{"relativePath": "urdf/robot.urdf", "sizeBytes": 1234},
{"relativePath": "meshes/base.stl", "sizeBytes": 5678},
{"relativePath": "textures/base.png", "sizeBytes": 2048}
]
}
```
成功 data 为 `UrdfUploadSignature`。`batchCode` 为后端生成的 32 位小写十六进制编码,`mainRelativePath` 自动识别。`uploadUrl` 为 OSS 表单上传地址;每个文件具有独立的 `objectKey`、`formFields`。签名有效 15 分钟,`expiresAt` 为所有文件签名的最早过期时间,响应禁止缓存。Policy 精确绑定对象键、文件声明大小、Content-Type 及成功状态 200,不允许客户端修改;MIME 由后端生成,主文件为 `application/xml`。
对象键为 `{环境根目录}/urdf/{projectCode}/{batchCode}/{relativePath}`:test 根目录为 `vibemake_dev`,prod 为 `vibemake`。每次签名产生新批次,不覆盖旧批次。将每个文件的 `formFields` 原样放入 FormData,最后追加该文件,再 POST 到 `uploadUrl`;不手动设置 multipart Content-Type,不携带平台 Authorization,OSS 成功应为 HTTP 200,响应体为空。
### 确认、替换和清除
全部文件上传成功后调用 `PUT /api/workspace/projects/{projectCode}/urdf`:
```json
{
"batchCode": "33333333333333333333333333333333",
"files": [
{"relativePath": "urdf/robot.urdf", "sizeBytes": 1234},
{"relativePath": "meshes/base.stl", "sizeBytes": 5678},
{"relativePath": "textures/base.png", "sizeBytes": 2048}
]
}
```
提交签名响应的真实 `batchCode` 和最初的完整清单,不提交 URL、目录前缀或主文件对象键。后端重新识别唯一主文件,生成当前环境、本项目的路径,通过 OSS 核验所有文件存在且实际大小一致后,一次性保存资源记录。数据库的 `urdf_prefix` 保存 `/urdf/{projectCode}/{batchCode}/`,`urdf_main_object_key` 为此前缀加主文件相对路径,均不含环境根目录和域名;真实 OSS key 仍包含环境根目录。成功 data 为更新后的 Project,包含 `urdfMainUrl`、`urdfBaseUrl` 完整地址;URL 已编码,前端不要再次整体编码。未确认、上传失败、取消或核验失败均不会替换原绑定。
替换重复执行“签名 → 直传 → 确认”,并发以最后一次成功确认生效。签名过期时重新申请新批次并重新上传,不修改旧签名。没有上传会话或后台任务查询接口。
`DELETE /api/workspace/projects/{projectCode}/urdf` 清空当前绑定,无请求体,成功 data 为 null;重复清除也成功,OSS 未开启时仍可清除。未上传、清除后 `urdfMainUrl`、`urdfBaseUrl` 都为 null。项目创建和 PATCH 请求不接收 URDF 字段。
URDF 替换或清除立即影响社区,不需要重新发布仓库。Fork 在创建时读取当前 URDF 并复制到新项目目录,复制成功后才返回 READY;失败响应包含新项目的 `projectCode`,按现有初始化失败规则核对。源项目后续替换、清除不影响 Fork。替换、清除、删除项目均不自动删除 OSS 对象,旧公开 URL 仍可读取;撤回社区也不使已知的公开资源 URL 失效。
### 限制、错误与部署
| 项目 | 默认值 |
| --- | --- |
| 单文件 | 50 MiB,`URDF_MAX_FILE_BYTES=52428800` |
| 整包总量 | 200 MiB,`URDF_MAX_TOTAL_BYTES=209715200` |
| 文件数量 | 500,`URDF_MAX_FILES=500` |
| 对象键 | 最多 512 个 Java 字符且 UTF-8 最多 1023 字节;前缀占用也计入 |
URDF 直传不受仓库上传的 multipart 10 MiB / 52 MiB 限制影响。路径必须是唯一相对路径,不能包含绝对路径、空段、`.`、`..`、反斜杠、控制字符、`.git` 目录或冒号。系统不解析 URDF 语义、不执行 Xacro、不自动修复 `package://` 等引用;渲染器的资源解析由前端处理。
| HTTP / code | 提示与处理 |
| --- | --- |
| 400 URDF_MAIN_FILE_INVALID | 没有:文件夹中未找到 URDF 文件;多个:文件夹中存在多个 URDF 文件,请仅保留一个后重新上传 |
| 400 BAD_REQUEST | 清单、路径、批次编码或字节数不合法 |
| 400 URDF_FILE_MISSING | URDF 文件未上传完整,请重新上传 |
| 400 URDF_FILE_SIZE_MISMATCH | URDF 文件大小不符,请重新上传 |
| 401 UNAUTHORIZED / 404 NOT_FOUND | 登录或检查项目归属、删除状态 |
| 409 CONFLICT | 项目尚未就绪,或 Fork 复制时源资源发生变化 |
| 413 URDF_UPLOAD_TOO_LARGE | 文件数量或大小超过限制 |
| 502 OSS_ERROR / 503 OSS_UNAVAILABLE | OSS 访问失败或未启用;保留原资源 |
复用封面的 OSS 凭据及公开基础地址配置。上线前先执行 [URDF 加字段 SQL](database.md#已有数据库增加项目-urdf)。RAM 用户增加当前环境 `urdf/*` 范围的 `oss:PutObject`、`oss:GetObject` 权限,用于上传、元信息核验和服务端复制;不需要开放整个 Bucket 写权限。对 URDF 目录配置公开读取或使用公开 CDN,并为真实前端 Origin 配置 POST、GET、HEAD 的 CORS。应用不修改 Bucket ACL 或版本控制配置。表单附带禁止覆盖参数;Bucket 已开启或暂停版本控制时 OSS 不保证该参数有效,按新批次上传且不要复用成功签名修改资源。
### 浏览器文件夹上传示例
页面使用 `<input type="file" webkitdirectory multiple>` 选择文件夹。以下示例复用本文的 `request` 方法;可直接展示抛出的错误消息,不提供主文件选择交互。
```ts
async function uploadProjectUrdf(projectCode: string, selected: FileList, token: string) {
const entries = Array.from(selected).map(file => {
const path = file.webkitRelativePath || file.name;
return { file, relativePath: file.webkitRelativePath ? path.slice(path.indexOf('/') + 1) : path };
});
const count = entries.filter(item => item.relativePath.toLowerCase().endsWith('.urdf')).length;
if (count === 0) throw new Error('文件夹中未找到 URDF 文件');
if (count > 1) throw new Error('文件夹中存在多个 URDF 文件,请仅保留一个后重新上传');
const files: UrdfFile[] = entries.map(item => ({ relativePath: item.relativePath, sizeBytes: item.file.size }));
const endpoint = `/workspace/projects/${encodeURIComponent(projectCode)}/urdf`;
const signature = await request<UrdfUploadSignature>(`${endpoint}/signature`, {
method: 'POST', token, body: { files },
});
const byPath = new Map(entries.map(item => [item.relativePath, item.file]));
for (const item of signature.files) {
const form = new FormData();
for (const [key, value] of Object.entries(item.formFields)) form.append(key, value);
form.append('file', byPath.get(item.relativePath)!);
const uploaded = await fetch(signature.uploadUrl, { method: 'POST', body: form });
if (uploaded.status !== 200) throw new Error(`URDF 上传失败:HTTP ${uploaded.status}`);
}
return request<Project>(endpoint, {
method: 'PUT', token, body: { batchCode: signature.batchCode, files },
});
}
async function clearProjectUrdf(projectCode: string, token: string) {
return request<null>(`/workspace/projects/${encodeURIComponent(projectCode)}/urdf`, {
method: 'DELETE', token,
});
}
```
## 目录和文件读取
### 工作区目录
`GET /api/workspace/projects/{projectCode}/tree`,需要登录。
| 参数 | 必填 | 说明 |
| --- | --- | --- |
| path | 否 | 目录相对路径,省略或空字符串表示根目录 |
| commitSha | 否 | 省略时读取当前 main;传入时读取该项目指定提交 |
data 示例:
```json
{
"commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"path": "",
"entries": [
{
"path": "models",
"name": "models",
"type": "dir",
"size": 0,
"blobSha": "cccccccccccccccccccccccccccccccccccccccc"
},
{
"path": "README.md",
"name": "README.md",
"type": "file",
"size": 5,
"blobSha": "dddddddddddddddddddddddddddddddddddddddd"
}
]
}
```
entries 仅包含当前目录的直接子项,目录在前,名称升序。展开子目录时传条目的完整 path。需要一致的历史文件视图时,目录和文件读取都使用同一个 commitSha。
### 工作区文件
`GET /api/workspace/projects/{projectCode}/files`,需要登录。
| 参数 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- |
| path | 是 | 无 | 普通文件的相对路径 |
| commitSha | 否 | 当前 main | 指定历史提交 |
| download | 否 | false | true 返回文件附件 |
文本文件 data 示例:
```json
{
"commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"path": "README.md",
"blobSha": "dddddddddddddddddddddddddddddddddddddddd",
"size": 5,
"encoding": "utf-8",
"content": "hello",
"editable": true
}
```
二进制文件 data 示例:
```json
{
"commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"path": "models/data.bin",
"blobSha": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"size": 3,
"encoding": "base64",
"content": "AAEC",
"editable": false
}
```
只有 UTF-8、没有 NUL 字节且不超过文本编辑限制的文件返回 editable=true。二进制文件或超过编辑限制的文本返回 base64,不能直接把 base64 放进编辑器提交;使用上传替换。文件和下载均受单文件读取上限限制。
`download=true` 成功返回 `application/octet-stream`,带 `Content-Disposition: attachment`,不套 JSON。工作区下载需要带 Bearer Token,应使用 fetch 获取 Blob,直接使用 a 标签或 window.open 无法附加该请求头。失败时按 JSON 错误响应处理。
### 社区目录和文件
- `GET /api/community/projects/{projectCode}/tree`:path 用法与工作区一致,data 为 Tree。
- `GET /api/community/projects/{projectCode}/files`:支持 path、download,返回与工作区相同的文件数据或二进制。
均可匿名访问,固定读取当前 publishedCommitSha。**不要传 commitSha 参数,即使传空字符串也会返回 400。** 社区页面只读,需要编辑时先 Fork 到自己的工作区。撤回、删除或未发布项目返回 404。
### 路径限制
文件和非根目录路径必须为相对路径,最长 1024 字符。支持中文、空格和多级目录,例如 `models/轮式机器人/底盘.stl`;不加开头或结尾斜杠。根目录在目录接口和上传 directory 中用空字符串。
禁止绝对路径、反斜杠、空路径段、`.`、`..`、`.git` 路径段、冒号及控制字符。读取普通文件接口不支持符号链接或 Git 子模块。使用 URLSearchParams 处理查询编码,不自行拼接未编码的 path。
## 文件编辑与上传提交
### 多文件提交
`POST /api/workspace/projects/{projectCode}/commits`,需要登录。
| 请求字段 | 必填 | 约束 |
| --- | --- | --- |
| expectedCommitSha | 是 | 当前编辑所基于的完整工作区 SHA |
| message | 是 | 非空,最多 1000 字符 |
| changes | 是 | 1~500 个文件变更 |
每个 changes 元素使用以下字段:
| 字段 | 说明 |
| --- | --- |
| action | CREATE_FILE、UPDATE_FILE、DELETE_FILE、CREATE_DIRECTORY |
| path | 文件或新目录的相对路径 |
| content | CREATE_FILE、UPDATE_FILE 必填,UTF-8 文本;可为 `""` 创建或替换为空文件 |
请求示例中的路径必须符合仓库实际情况:创建路径应尚不存在,修改或删除目标必须存在。
```json
{
"expectedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"message": "更新说明并添加文件",
"changes": [
{ "action": "UPDATE_FILE", "path": "README.md", "content": "新的说明" },
{ "action": "CREATE_FILE", "path": "src/main.txt", "content": "hello" },
{ "action": "CREATE_DIRECTORY", "path": "models" },
{ "action": "DELETE_FILE", "path": "old.txt" }
]
}
```
成功 data 为 Commit:
```json
{
"commitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"message": "更新说明并添加文件"
}
```
一次请求生成一个 Commit。保存成功后,更新编辑器基准 SHA 并重新加载目录和受影响的文件。编辑器输入只存在于当前前端状态中,后端没有自动保存或草稿接口。
新建空目录实际创建 `{path}/.gitkeep`,目录和文件会在提交时进入仓库。一批不能重复操作同一路径,包含新目录转换成 .gitkeep 后的实际路径。DELETE_FILE、CREATE_DIRECTORY 不需要 content。没有单独的删除目录或重命名接口;删除目录需提交其所有文件的删除操作,包括 .gitkeep,并遵守每批 500 个变更限制。
如果 expectedCommitSha 已不是最新 main,返回 409 CONFLICT。前端保留当前未提交输入,重新读取工作区版本,让用户处理差异后再提交;不要只替换 SHA 后自动覆盖内容。浏览历史版本时应使用只读模式,回到最新版本后再编辑。
### 上传并提交
`POST /api/workspace/projects/{projectCode}/uploads/commit`,需要登录,使用 FormData。
| multipart 字段 | 必填 | 说明 |
| --- | --- | --- |
| expectedCommitSha | 是 | 基于的当前工作区版本 |
| message | 是 | 非空,最多 1000 字符 |
| directory | 否 | 目标目录,省略或空字符串表示根目录 |
| files | 是 | 重复使用同名 files 字段,1~500 个文件 |
| paths | 否 | 重复使用同名 paths 字段,与 files 顺序和数量一一对应 |
不传 paths 时使用各文件的原始文件名;传入时每个值是相对于 directory 的路径。例:directory=`models`、paths=`robot/body.stl`,最终路径为 `models/robot/body.stl`,不要重复添加 directory 前缀。
同名文件会替换,界面应说明覆盖行为。所有文件生成一个 Commit,成功 data 与文本提交相同。上传用于二进制文件和较大文本文件的新增或替换。
### 默认大小限制
| 限制 | 数值 |
| --- | --- |
| 在线创建或编辑的单个文本内容 | 1 MiB,1048576 字节 |
| 上传或读取的单文件 | 10 MiB,10485760 字节 |
| 本次上传文件或提交内容总量 | 50 MiB,52428800 字节 |
| multipart 整个请求 | 52 MiB,包含传输开销 |
| 单批变更或上传文件数量 | 500 |
| multipart 表单项数量 | 1003,含 500 个 files、500 个 paths 和 3 个公共字段 |
大小按字节计算,文本使用 UTF-8 编码长度,不使用 JavaScript 字符串 length 计算文件体积。以上是当前默认配置,超限返回 413。后端调整业务上传大小时还需同步调整 multipart 配置。
### 提交历史
`GET /api/workspace/projects/{projectCode}/commits?page=1&size=20`,需要登录。
data 为 PageResult&lt;HistoryEntry&gt;,只读取 main 的历史,不提供分支切换。历史条目示例:
```json
{
"commitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"message": "更新说明并添加文件",
"authorName": "用户_11111111",
"authorDate": "2026-10-13T08:40:00Z"
}
```
点击历史条目,把 commitSha 传给工作区 tree、files 接口。历史 total 依赖仓库服务的统计响应头,未提供时退化为本页条数;前端也可结合本页 items 数量提供下一页操作。
## 社区发布和撤回
### 首次发布和更新社区版本
`PUT /api/workspace/projects/{projectCode}/publication`,需要登录。
请求:
```json
{
"commitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
```
commitSha 必须为当前 main 的完整 SHA,不能发布历史提交。成功 data 为 Project,publishStatus=PUBLISHED,publishedCommitSha 为提交的版本,publishedAt 更新为本次发布时间。
同一路径用于首次发布和以后手动更新社区版本。发布后继续提交、上传或创建目录,都不会自动更新社区代码。需要更新时,取得最新工作区 SHA,再调用此接口。项目名称、描述和类型的修改直接更新展示。
例:发布版本 A 后,在工作区提交得到 B,工作区展示 B,社区仍展示 A;再次用 B 调用 publication 后,社区才展示 B。前端可比较工作区 tree.commitSha 与项目 publishedCommitSha,显示“有未发布的更新”。
工作区 SHA 已变化时返回 409 CONFLICT,刷新版本后由用户重新确认发布。成功后刷新工作区详情和社区列表或详情。
### 撤回社区
`DELETE /api/workspace/projects/{projectCode}/publication`,需要登录,无请求体,成功 data 为 null。
撤回后项目留在工作区,社区列表、详情、目录、文件、评论列表及新增互动不可访问。原有评论、点赞和发布记录保留,再次发布继续使用;已有独立 Fork 不受影响。
## 社区详情和 Fork
### 项目详情
`GET /api/community/projects/{projectCode}`,可选登录,data 为 Project。
列表项点击后用 projectCode 进入前端详情路由,再请求本接口。可并行请求根目录和评论列表。需要当前用户的点赞状态时携带有效 Token。前端页面 URL 由前端定义,后端不返回可直接跳转的页面地址。
### Fork 到我的工作区
`POST /api/community/projects/{projectCode}/forks`,需要登录。
| 请求字段 | 必填 | 说明 |
| --- | --- | --- |
| name | 是 | 新项目名称,非空,最多 100 字符 |
| publishedCommitSha | 是 | 当前社区详情返回的完整发布版本 |
```json
{
"name": "我的机器人副本",
"publishedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
```
成功 data 为当前用户的新 Project,状态 READY、UNPUBLISHED;使用返回的新 projectCode 跳转工作区。类型和描述继承源项目,sourceProjectCode、sourceCommitSha 记录来源。
Fork 使用 Git 仓库级快照复制:冻结校验通过的 publishedCommitSha,保留该提交完整的文件树,在新私有仓库 main 上创建一个无父提交的初始版本,不继承源仓库的历史、其他分支或标签,不自动同步上游。允许同一用户及多个用户多次 Fork 同一来源。新副本的提交 SHA 与 sourceCommitSha 不同,应通过工作区 tree 接口获取新版本。
复制保留普通文件、执行权限、符号链接、`.gitmodules` 和子模块引用;不递归下载子模块依赖。Git LFS 指针及发布快照引用的实体会完整复制,并从副本独立下载校验。缺失的 LFS 实体会导致 Fork 失败。复制不使用普通文件接口的 10 MiB 读取上限,在线文件浏览、下载及 LFS 展开能力仍受原限制。URDF 按受理时绑定的当前清单独立复制到新目录,复制时校验 ETag,封面继承原 URL;Git、LFS 和 OSS 全部完成后才返回 READY。
后端部署需要 Git 和 git-lfs。默认 Fork 总预算5分钟、单实例最多同时2次,每次临时磁盘上限5 GiB(含 Git 对象、LFS 源缓存和副本校验缓存)。配置分别为 FORK_TIMEOUT、FORK_MAX_CONCURRENT、FORK_MAX_TEMPORARY_BYTES;临时目录可通过 FORK_TEMPORARY_DIRECTORY 指定。依赖不可用或并发超限时,在创建项目记录前拒绝。普通创建和其他 API 不依赖 Fork 运行环境。
| 错误码 | 行为 |
| --- | --- |
| FORK_UNAVAILABLE(503) | Git、git-lfs、临时目录或 Gitea 配置不可用,联系后端处理 |
| FORK_BUSY(429) | 达到 Fork 并发上限,稍后手动重试 |
| FORK_RESOURCE_LIMIT(413) | 临时磁盘或元数据超过限制,核对项目状态及服务端配额 |
| FORK_COPY_FAILED(502) | 快照、认证或 LFS 复制/校验失败,使用 requestId 排查 |
| FORK_TIMEOUT(504)/ FORK_CANCELLED(499) | 已超时或取消,先核对工作区再决定下一步 |
| REMOTE_RESULT_UNKNOWN(504) | 远端写入结果未确认,保留 CREATING,禁止自动重试 |
创建记录后发生异常时,错误 data.projectCode 指向本次新副本。明确失败标记 FAILED;远端写入结果不明或回写异常保留 CREATING 并阻止后续写入。后端终止相关子进程、清理本地临时目录,不自动删除远端仓库或 OSS 对象,也不自动修复历史失败副本。
源项目发布版本已变化时返回 409 CONFLICT,刷新社区详情后由用户重新确认。Fork 是同步请求,可能耗时较长;前端和代理读取超时默认至少400秒,提交期间显示加载状态并防止重复点击。超时、网络断开或失败后先查询工作区,不要自动重发。
## 评论和点赞
### 评论列表
`GET /api/community/projects/{projectCode}/comments?page=1&size=20`,可选登录。
data 为 PageResult&lt;Comment&gt;,按创建时间倒序,平铺展示,不提供回复层级。评论 data 示例:
```json
{
"commentCode": "33333333333333333333333333333333",
"author": {
"userCode": "111111111111",
"nickname": "用户_11111111"
},
"content": "这个项目的结构很清楚",
"createdAt": "2026-10-13T08:45:00"
}
```
### 新增评论
`POST /api/community/projects/{projectCode}/comments`,需要登录。
```json
{
"content": "这个项目的结构很清楚"
}
```
content 非空,最多 2000 字符,保存时去掉首尾空格。成功 data 为新 Comment。只支持纯文本,没有富文本、评论编辑或回复接口;前端以文本渲染。提交成功后刷新评论列表和项目 commentCount,不要自动重试新增评论请求。
### 删除自己的评论
`DELETE /api/comments/{commentCode}`,需要登录,无请求体,成功 data 为 null。
比较 `comment.author.userCode === currentUser.userCode` 决定是否显示删除入口,后端仍会校验作者身份。删除他人的、已删除的或不存在的评论返回 404。删除成功后刷新评论列表和项目统计。
### 点赞和取消点赞
- `PUT /api/community/projects/{projectCode}/like`:需要登录,点赞。
- `DELETE /api/community/projects/{projectCode}/like`:需要登录,取消点赞。
均无请求体,成功 data 为 null,两者幂等。点赞接口不返回最新计数,成功后重新请求社区详情获取 liked、likeCount;可以先做乐观更新,失败时恢复并刷新详情。
## Maker AI
`POST /api/community/ai/chat`,需要登录。请求头为 `Content-Type: application/json`、`Accept: text/event-stream` 和 `Authorization: Bearer <平台 token>`。普通 JSON 请求封装不能用于读取该接口的成功响应。
Maker AI 支持身份介绍、日常闲聊、一般知识和技术问答,可在回复中给出文本代码示例。聊天基于模型知识,不联网、不执行代码、不写入项目;例如发送 `{"message":"你是谁"}`,会介绍自己为 Maker AI,而不是要求补充项目需求。聊天与项目操作共用同一个接口和最近6轮历史。
查找时只检索社区已发布、仓库就绪且未删除项目的名称、描述和类型,不读取 README、代码或评论。模型先提取条件,后端查询最多20个候选,再由模型排序;最终返回最多5张经过校验的项目卡片。名称、描述没有写明的技术能力无法可靠匹配,缺少依据的偏好通过 unverifiedRequirements 提示;明确要求缺少依据时不作为满足条件的结果。
### 支持的操作
接口根据当前 message 识别操作,history 用于聊天上下文、补充需求和理解指代。明确要求且信息充分时直接执行,不增加确认步骤;每轮最多执行一次创建或 Fork,多项写入要求先请用户选择一项。问候、感谢和普通聊天不会触发历史中的待办操作,历史中已完成的操作不会再次执行。明确查找平台项目或追问候选项目详情走项目检索,一般概念解释和创意讨论直接回答。
| 操作 | 示例 | 行为 |
| --- | --- | --- |
| 聊天与身份介绍 | 你好,你是谁 | 以 Maker AI 身份自然回答,返回 CHAT,不进行候选检索或项目写入 |
| 知识与技术问答 | 什么是 ROS2?用 Java 写一个循环示例 | 直接解答,可返回文本代码示例,不创建项目或实际执行代码 |
| 查找 | 找适合教学、支持 ROS2 的四足项目 | 返回最多5张有依据的社区项目卡片 |
| 创建空项目 | 创建一个轮式导航实验项目,叫“我的导航实验” | 提取或生成名称和目标描述,类型无法判断时使用 GENERAL;初始化私有仓库和默认 README,不生成业务代码、不自动发布 |
| 按编码 Fork | Fork 项目 7m4k9x2p8q6r,副本叫“我的实验” | 后端核验来源,复制执行时的当前发布版本到本人工作区 |
| 按序号 Fork | Fork 第二个项目 | 根据 previousProjectCodes 的原顺序定位;未指定副本名称时沿用来源名称 |
| 查找并 Fork | 找一个支持 ROS2 教学的项目并 Fork | 本轮检索、排序与校验后仅一个推荐结果时执行;多个结果返回 NEEDS_SELECTION,等待下一轮选择;无结果返回 NO_MATCH |
只说“创建项目”、只说“Fork”而没有具体需求或来源、引用不存在的序号、明确指定不可用类型时,返回 NEEDS_CLARIFICATION。用户可以通过下一轮补充信息继续。创建时未提供描述可为空,未提供封面则无封面;封面只接受用户明确提供且符合既有约束的 HTTPS 地址。名称、类型和其他输入仍受现有项目接口约束。
Fork 不使用模型生成的 SHA。后端在执行前读取来源的当前发布 SHA,再交给既有服务校验;读取后来源撤下或发布版本变化时返回原业务错误,不自动改用另一个版本。新项目或副本成功后均为 READY、UNPUBLISHED。
### 请求与对话维护
```json
{
"message": "改成轮式,其他要求不变",
"history": [
{ "role": "user", "content": "找四足机器人,必须支持ROS2,最好适合教学" },
{ "role": "assistant", "content": "为你找到 1 个候选项目,请结合匹配依据和未确认事项查看详情。" }
],
"previousProjectCodes": ["11111111111111111111111111111111"]
}
```
| 字段 | 限制及用途 |
| --- | --- |
| message | 必填,非空,最多2000字符,当前问题不重复放入 history |
| history | 可省略或为 null,最多12条,保留最近6轮完整 user/assistant 对话;从 user 开始、交替排列并以 assistant 结束;每条 content 非空且最多2000字符,不接受 system 角色 |
| previousProjectCodes | 可省略或为 null,最多5个项目编码,每个非空且最多32字符;按最近一次项目结果的卡片展示顺序提交,穿插 CHAT 时保留,用于理解“第二个项目”等指代,后端只读取其中仍可见的社区项目 |
前端在内存维护对话,仅在收到 result 后将当前问题和 reply 组成完整的一轮追加到 history,下一次提交前保留末尾12条。CHAT 同样追加历史,但保留原 previousProjectCodes,不用空 projects 覆盖,也不必清除已展示的项目卡片,支持“搜索 → 闲聊 → Fork 第二个”。其他状态使用本轮 projects 的编码列表替换 previousProjectCodes,包括 NEEDS_SELECTION 的候选;CREATED、FORKED 的 projects 为空,应清空上一轮候选编码。error、网络失败或主动取消时不追加未完成对话。新建对话或刷新页面清空两者,无服务端会话创建、恢复或删除接口。
### SSE 事件与响应类型
```typescript
export interface AiChatRequest {
message: string;
history?: Array<{ role: 'user' | 'assistant'; content: string }>;
previousProjectCodes?: string[];
}
export interface AiProgress {
stage: 'understanding' | 'searching' | 'ranking' | 'validating' | 'creating' | 'forking';
message: string;
}
export interface AiProjectCard {
project: Project; // 复用上文项目类型,包含 projectCode 和 publishedCommitSha
reason: string;
evidence: Array<{
field: 'name' | 'description' | 'projectType';
quote: string; // 在对应字段中核验过的连续原文
requirement: string | null; // 该证据对应的要求或偏好;一般依据为 null
}>;
unverifiedRequirements: string[]; // 未确认的偏好,不代表已经满足
}
export interface AiChatResult {
status: 'CHAT' | 'MATCHED' | 'NO_MATCH' | 'NEEDS_CLARIFICATION' | 'NEEDS_SELECTION' | 'CREATED' | 'FORKED';
reply: string; // CHAT 为非空完整回复,最多2000字符,可直接追加到 history
projects: AiProjectCard[]; // MATCHED、NEEDS_SELECTION 返回候选,其他状态为空数组
project: Project | null; // CREATED、FORKED 返回操作后的项目,其他状态为 null
}
```
| 事件 | data 类型 | 行为 |
| --- | --- | --- |
| progress | `ApiResponse<AiProgress>` | 展示阶段;CHAT 只有 understanding 阶段;空候选或需要澄清时可能提前结束,不保证所有阶段全部出现;直接创建或 Fork 无搜索阶段 |
| result | `ApiResponse<AiChatResult>` | 一次最终结果,随后关闭连接;所有状态均为正常业务结果;CHAT 展示 reply、保留候选编码;NEEDS_SELECTION 展示候选等待选择,CREATED/FORKED 使用 project.projectCode 进入工作区 |
| error | `ApiResponse<{ projectCode?: string } \| null>`,code 非 OK | 显示错误并结束本轮;初始化异常可能携带项目编码,先核对工作区,不要自动重试 |
阶段消息是服务端进度,不是逐字生成的模型文字。聊天复用一次意图识别调用生成完整 reply,事件顺序为 understanding → result,不新增逐字输出事件。心跳使用 `:keep-alive` 注释行,没有 JSON 数据,解析器直接忽略。聊天回复、代码示例、项目和推荐文字按纯文本渲染;链接由前端使用 project.projectCode 生成,不将模型文字当作 HTML 或链接执行。点击搜索卡片后使用既有社区详情接口重新读取当前项目,撤下的项目可能返回404。CREATED、FORKED 使用 result.project.projectCode 打开工作区详情,不能用社区详情接口读取尚未发布的新项目。
事件流示例:
```text
event:progress
data:{"code":"OK","message":"成功","data":{"stage":"understanding","message":"正在理解需求"},"requestId":"44444444444444444444444444444444"}
event:result
data:{"code":"OK","message":"成功","data":{"status":"CHAT","reply":"我是 Maker AI,可以陪你聊天、解答问题、讨论创意,也能帮你查找、创建和 Fork 社区项目。","projects":[],"project":null},"requestId":"44444444444444444444444444444444"}
```
鉴权、参数、功能关闭和入口限流发生在建流前,按 HTTP 400/401/429/503 返回普通 JSON;流建立后发生的模型异常和项目业务异常通过 error 事件返回,此时 HTTP 状态仍为200。requestId 与入口响应头一致。
| 错误码 | 含义与前端处理 |
| --- | --- |
| AI_UNAVAILABLE | AI 未启用或正在停止,提示暂不可用,保留普通搜索入口 |
| AI_BUSY | 达到全局并发上限,入口 HTTP 429,稍后手动重试 |
| AI_RATE_LIMITED | 超过当前用户频率限制,入口 HTTP 429,稍后手动重试 |
| AI_TIMEOUT | 模型调用或整次处理超时;涉及创建或 Fork 时先核对工作区,不能直接重试 |
| AI_PROVIDER_FAILURE | 上游 HTTP 错误、响应不完整或格式异常,提示服务异常 |
| AI_INVALID_RESPONSE | 模型结果的操作、参数、编码、引用或聊天回复未通过校验(如空白、超长或 CHAT 夹带项目参数),不执行该操作 |
| AI_SEARCH_FAILURE | 服务内部异常,携带 requestId 联系后端;涉及写入时先核对工作区 |
| NOT_FOUND / CONFLICT | Fork 来源不可访问或发布版本变化,不自动重新选择或换版本执行 |
| FORK_UNAVAILABLE / FORK_BUSY / FORK_RESOURCE_LIMIT / FORK_COPY_FAILED / FORK_TIMEOUT / FORK_CANCELLED | 按上文 Fork 错误码处理;error 事件不会改变已建立 SSE 的 HTTP 200 状态 |
| GITEA_ERROR / REMOTE_RESULT_UNKNOWN / PROJECT_INITIALIZATION_ERROR | 项目初始化失败或结果待核对,优先使用 data.projectCode 查询工作区详情 |
默认每次模型调用30秒,模型/搜索阶段总预算65秒;进入 forking 后切换为独立 Fork 预算(默认5分钟,另留15秒入口及终态余量),不再受搜索阶段65秒截止时间影响。SSE 容器超时覆盖搜索与 Fork 两阶段,心跳持续发送。全局 AI 并发4个、每用户滑动一分钟最多10次,Fork 另受单实例2次并发限制,超限不排队。主动取消通过 AbortController;服务端在检测连接断开后尽力取消上游,实际工作结束后释放并发名额。写入前检测取消,写入开始后超时或断开不保证回滚;即使没有收到项目编码,也应先查询工作区列表核对,不自动重发。不要在页面上同时启动多个 AI 请求;代理应关闭 SSE 缓冲,读取超时至少400秒。
### fetch 接收 SSE 示例
以下示例复用下文的 API_BASE、ApiError 和上文的数据类型。它处理跨网络分块的 UTF-8 文本和 SSE 边界,不使用不能携带 Bearer 请求头的原生 EventSource。
```typescript
async function chatAi(
input: AiChatRequest,
token: string,
onProgress: (progress: AiProgress) => void,
signal?: AbortSignal,
): Promise<AiChatResult> {
const response = await fetch(`${API_BASE}/community/ai/chat`, {
method: 'POST',
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
Accept: 'text/event-stream',
},
body: JSON.stringify(input),
signal,
});
const requestId = response.headers.get('X-Request-Id');
if (!response.ok) {
const failure: ApiResponse<null> = await response.json();
throw new ApiError(response.status, failure.code, failure.message,
failure.requestId ?? requestId);
}
if (!response.body || !response.headers.get('Content-Type')?.includes('text/event-stream')) {
throw new ApiError(response.status, 'BAD_RESPONSE', '接口未返回事件流', requestId);
}
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
let eventName = '';
let dataLines: string[] = [];
let result: AiChatResult | undefined;
function dispatch() {
if (!dataLines.length) { eventName = ''; return; }
const event: ApiResponse<AiProgress | AiChatResult | { projectCode?: string }> = JSON.parse(dataLines.join('\n'));
dataLines = [];
if (eventName === 'error' || event.code !== 'OK') {
throw new ApiError(response.status, event.code, event.message,
event.requestId ?? requestId, event.data);
}
if (eventName === 'progress') onProgress(event.data as AiProgress);
if (eventName === 'result') result = event.data as AiChatResult;
eventName = '';
}
try {
while (true) {
const { value, done } = await reader.read();
buffer += decoder.decode(value, { stream: !done });
let end: number;
while ((end = buffer.indexOf('\n')) >= 0) {
const line = buffer.slice(0, end).replace(/\r$/, '');
buffer = buffer.slice(end + 1);
if (!line) dispatch();
else if (line.startsWith('event:')) eventName = line.slice(6).trim();
else if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart());
// 注释心跳及其他字段忽略。
}
if (result) return result;
if (done) break;
}
throw new ApiError(response.status, 'AI_STREAM_INCOMPLETE',
'连接提前结束,未收到处理结果;如涉及写入,请先核对工作区', requestId); // 前端封装错误码
} finally {
await reader.cancel().catch(() => {});
reader.releaseLock();
}
}
// 点击“停止”或离开页面时执行 controller.abort()。
const controller = new AbortController();
// 实际页面应将两者保存在组件状态中,并在后续请求时复用。
let history: NonNullable<AiChatRequest['history']> = [];
let previousProjectCodes: string[] = [];
const message = '找适合教学的四足机器人,最好支持ROS2';
const result = await chatAi(
{ message, history, previousProjectCodes },
token,
progress => console.log(progress.message),
controller.signal,
);
// 收到 result 后更新页面和最近6轮 history;CHAT 不覆盖候选编码。
history.push({ role: 'user', content: message }, { role: 'assistant', content: result.reply });
history = history.slice(-12);
if (result.status !== 'CHAT') {
previousProjectCodes = result.projects.map(card => card.project.projectCode);
}
// CHAT 展示完整 reply,保留此前卡片及候选编码。
// MATCHED/NEEDS_SELECTION 展示候选;CREATED/FORKED 使用 result.project.projectCode 打开工作区。
// 捕获 ApiError 时读取 error.data?.projectCode(先做类型判断),用于核对初始化未完成的项目。
```
## 错误码与前端处理
### 错误响应示例
版本冲突通常不带 data:
```json
{
"code": "CONFLICT",
"message": "工作区版本已变化,请刷新后重新提交",
"data": null,
"requestId": "44444444444444444444444444444444"
}
```
部分创建、Fork 或仓库调用错误携带关联项目:
```json
{
"code": "REMOTE_RESULT_UNKNOWN",
"message": "仓库连接异常或超时,写入结果需核对",
"data": {
"projectCode": "22222222222222222222222222222222"
},
"requestId": "44444444444444444444444444444444"
}
```
### 错误处理对照
| HTTP | code | 前端处理 |
| --- | --- | --- |
| 400 | BAD_REQUEST | 参数、分页、类型、路径、SHA 或文件操作不合法,展示 message 并检查请求 |
| 400 | CAPTCHA_INVALID | 验证码错误、已使用或过期,刷新验证码 |
| 401 | UNAUTHORIZED | 清除登录状态,受保护页面进入登录流程;公开 GET 可移除失效 Token 后重新读取 |
| 403 | ACCOUNT_DISABLED | 登录账号不可用,停止登录流程并展示提示 |
| 403 | FORBIDDEN | 无权访问,展示权限提示 |
| 404 | NOT_FOUND | 项目不可访问、目标文件或版本不存在;停止加载目标资源并展示不可用状态 |
| 405 | METHOD_NOT_ALLOWED | 检查请求方法 |
| 409 | CONFLICT | 工作区或发布版本变化,或仓库未就绪,按 message 刷新版本或核对状态 |
| 409 | GITEA_CONFLICT | 仓库内容冲突,刷新目录和文件后由用户处理 |
| 409 | REMOTE_RESULT_UNKNOWN | 上一次仓库写入结果待核对,暂不能继续该项目的仓库写入 |
| 413 | FILE_TOO_LARGE | 文件读取、编辑或上传内容超限,提示大小限制 |
| 413 | UPLOAD_TOO_LARGE | 整体 multipart 请求超限 |
| 413 | UPLOAD_TOO_MANY_PARTS | multipart 文件或表单项数量超限,减少文件或重复字段 |
| 415 | UNSUPPORTED_MEDIA_TYPE | 检查 Content-Type,JSON 与 FormData 不要混用 |
| 500 | CAPTCHA_ERROR | 验证码生成失败,可重新获取并记录 requestId |
| 500 | PROJECT_INITIALIZATION_ERROR | 项目初始化或回写未完成,查看 data.projectCode 和工作区,请后端核对 |
| 500 | INTERNAL_ERROR | 展示服务异常并保留 requestId |
| 500 | RESOURCE_PATH_INVALID | 历史资源路径格式或所属环境异常,保留 requestId 请后端核对 |
| 502 | GITEA_ERROR | 仓库服务异常;写请求先核对结果,避免自动重试 |
| 502 | GITEA_INVALID_RESPONSE | 仓库响应无法确认;写请求先核对结果,避免自动重试 |
| 503 | GITEA_NOT_CONFIGURED | 后端缺少仓库配置,请后端处理 |
| 503 | USER_CODE_EXHAUSTED | 用户编码分配连续冲突,重新获取验证码后稍后登录,并保留 requestId |
| 504 | REMOTE_RESULT_UNKNOWN | 仓库连接异常或超时;读请求可重新读取,写请求需先核对结果 |
通过 HTTP 状态和 code 判断行为,保留 requestId 供排查。通用请求封装不要自动重试创建项目、Fork、评论或文件写入。浏览器超时、取消请求、连接中断不保证后端没有执行成功。
写入结果待核对时,数据库持久化的写入状态会阻止该项目后续仓库写入或发布;仍可读取可用文件、修改项目信息、撤回和删除。CREATING 项目因仓库尚未 READY,不能读取文件。没有 repository_operation 查询接口、自动恢复接口或跨重启完整幂等保证。
## 页面调用顺序
| 页面或操作 | 调用顺序 |
| --- | --- |
| 社区首页 | project-types → community/projects;选类型和关键词时重置页码 |
| 社区详情 | community 项目详情、根目录、评论列表;展开目录或点击文件再读取对应内容 |
| 登录页 | captcha → login;失败后刷新验证码;成功后保存平台登录状态 |
| 我的工作区 | users/me → workspace/projects,分别显示仓库状态和发布状态 |
| 创建项目 | POST workspace/projects → 使用返回 projectCode 进入详情 → tree 获取当前版本 |
| 上传封面 | uploads/project-covers/signature → 浏览器直接 POST OSS → 成功后将 coverUrl 写入项目创建或修改接口 |
| 上传或替换 URDF | 校验文件夹唯一主文件 → urdf/signature → 全部文件直传 OSS → PUT urdf 确认绑定 |
| 清除 URDF | DELETE urdf → 刷新项目详情 |
| 文件编辑 | workspace 详情与 tree → files → 判断 editable → commits → 刷新版本、目录和文件 |
| 上传文件 | tree 获取基准 SHA → uploads/commit → 刷新目录和当前版本 |
| 发布或更新社区 | 获取最新工作区 SHA → publication → 刷新项目和社区页面 |
| Fork | 获取社区详情中的发布 SHA → forks → 使用新 projectCode 进入工作区 |
| 评论或点赞 | 完成写请求 → 刷新评论或项目详情中的统计字段 |
## 前端请求示例
以下示例使用浏览器 fetch 和 TypeScript,类型声明见前面的响应结构。API_BASE 默认使用 `/api`,配合同域反向代理或开发代理;从白名单前端直接跨域访问时,改为实际后端的 HTTPS 地址加 `/api`,继续传递 Bearer Token,无需设置 `credentials: 'include'`。
### JSON 与 FormData 请求封装
```typescript
const API_BASE = '/api';
class ApiError extends Error {
constructor(
readonly status: number,
readonly code: string,
message: string,
readonly requestId: string | null,
readonly data: unknown = null,
) {
super(message);
this.name = 'ApiError';
}
}
async function request<T>(
path: string,
options: {
method?: string;
token?: string;
body?: unknown;
signal?: AbortSignal;
} = {},
): Promise<T> {
const headers = new Headers({ Accept: 'application/json' });
if (options.token) headers.set('Authorization', `Bearer ${options.token}`);
let body: BodyInit | undefined;
if (options.body instanceof FormData) {
body = options.body; // 浏览器自动设置 multipart boundary
} else if (options.body !== undefined) {
headers.set('Content-Type', 'application/json');
body = JSON.stringify(options.body);
}
const response = await fetch(`${API_BASE}${path}`, {
method: options.method ?? 'GET',
headers,
body,
signal: options.signal,
});
let result: ApiResponse<T>;
try {
result = await response.json();
} catch {
throw new ApiError(
response.status,
'BAD_RESPONSE', // 前端封装错误码,不是后端业务错误码
'接口未返回有效 JSON',
response.headers.get('X-Request-Id'),
);
}
if (!response.ok || result.code !== 'OK') {
throw new ApiError(
response.status, result.code, result.message,
result.requestId ?? response.headers.get('X-Request-Id'), result.data,
);
}
return result.data as T; // 返回 null 的接口使用 request<null>
}
```
调用处捕获 ApiError,按照错误码表处理。fetch 的网络错误和 AbortError 也需要处理;对于写请求,这些错误同样先核对结果。此封装不自动重试,也不用于下载二进制。
### 列表和文件读取
```typescript
async function loadProjects(type: string | undefined, keyword: string) {
const query = new URLSearchParams({ page: '1', size: '20' });
if (type) query.set('type', type);
if (keyword.trim()) query.set('keyword', keyword.trim());
return request<PageResult<Project>>(`/community/projects?${query}`);
}
async function readWorkspaceFile(projectCode: string, path: string, token: string) {
const query = new URLSearchParams({ path });
return request<ProjectFile>(
`/workspace/projects/${encodeURIComponent(projectCode)}/files?${query}`,
{ token },
);
}
```
需要 liked 状态时,列表请求也传入有效 token。
### 上传示例
```typescript
async function uploadFiles(
projectCode: string,
expectedCommitSha: string,
files: File[],
token: string,
) {
const form = new FormData();
form.append('expectedCommitSha', expectedCommitSha);
form.append('message', '上传模型文件');
form.append('directory', 'models');
for (const file of files) {
form.append('files', file, file.name);
form.append('paths', file.name); // 也可改为相对于 models 的多级路径
}
return request<Commit>(
`/workspace/projects/${encodeURIComponent(projectCode)}/uploads/commit`,
{ method: 'POST', token, body: form },
);
}
```
### 工作区下载示例
```typescript
async function downloadWorkspaceFile(projectCode: string, path: string, token: string) {
const query = new URLSearchParams({ path, download: 'true' });
const response = await fetch(
`${API_BASE}/workspace/projects/${encodeURIComponent(projectCode)}/files?${query}`,
{ headers: { Authorization: `Bearer ${token}` } },
);
if (!response.ok) {
const result = await response.json();
throw new ApiError(
response.status, result.code, result.message,
result.requestId ?? response.headers.get('X-Request-Id'), result.data,
);
}
const objectUrl = URL.createObjectURL(await response.blob());
const link = document.createElement('a');
link.href = objectUrl;
link.download = path.split('/').pop() || 'download';
document.body.appendChild(link);
link.click();
link.remove();
setTimeout(() => URL.revokeObjectURL(objectUrl), 0);
}
```
### UTC 时间解析
只对项目、评论中不带时区的 UTC 字段使用这个函数;历史 authorDate 已带时区时按其原值解析。
```typescript
function parseUtcTime(value: UtcDateTime): Date {
const hasTimezone = /(?:Z|[+-]\d{2}:\d{2})$/i.test(value);
return new Date(hasTimezone ? value : `${value}Z`);
}
```
### 开发代理示例
使用 Vite 时可在现有配置中加入以下 server 配置,保留 `/api` 路径,不进行 rewrite:
本地代理的 `changeOrigin` 会修改上游 Host,但可能保留浏览器的 localhost Origin。为避免本地写请求被后端白名单拒绝,示例通过 [Vite 的 configure 回调](https://vite.dev/config/server-options#server-proxy)在本地代理转发时移除 Origin,Authorization 保持原样;线上部署代理仍需透传真实 Origin。
```typescript
export default {
server: {
proxy: {
'/api': {
target: 'http://localhost:8993',
changeOrigin: true,
configure(proxy) {
proxy.on('proxyReq', (proxyReq) => {
proxyReq.removeHeader('origin');
});
},
},
},
},
};
```
## 后端人工核对
本节供前端遇到写入结果不明时与后端协作使用。记录 projectCode、requestId、接口路径及操作时间,提供给后端;不要在日志或工单中记录 Token、验证码答案、邮箱或文件内容。
后端先按 projectCode 对应的固定仓库名核对仓库、文件与提交历史。初始化未完成的项目核对后修正 repo_status 和仓库映射;确认没有远端写入仍在执行后,按管理端部署说明核对并恢复数据库中的写入状态;单纯重启不会解除持久化阻断。超时不能直接视为未提交后再次写入。数据库结构见 [四表数据库说明](database.md)。
## Redis 接入后的兼容与错误处理
接口路径、请求字段和正常响应字段保持兼容,仍只暴露业务编码。普通用户登录方式不变。会话已存入 Redis,应用重启保留未过期会话,首次从本机缓存版本升级需要重新登录。生产环境默认关闭 Swagger/OpenAPI;test 保留。
新增错误:429 RATE_LIMITED(频率超限)、429 FILE_BUSY(文件处理并发繁忙)、503 REDIS_UNAVAILABLE(安全状态服务不可用)、413 REQUEST_TOO_LARGE(JSON 请求字节超限)、502 GITEA_RESPONSE_TOO_LARGE(上游读取超限)。429 频率/文件繁忙响应提供 Retry-After 秒数,并通过 CORS 暴露;前端等待后手动重试。保留原 AI_BUSY、AI_RATE_LIMITED、FORK_BUSY、ADMIN_LOGIN_LIMITED 及文件大小错误码。
鉴权或普通业务请求收到 503 时保留本地 Token,提示服务暂不可用;正常 401 仍清除登录状态。用户主动退出时始终清理本地 Token;退出接口若返回 503,表示服务端撤销结果尚未确认。仓库写入遇到 REMOTE_RESULT_UNKNOWN 时先核对项目和 requestId,不自动重发。请求限流在解析大内容前执行,部分超限请求可能先返回 429。
Fork 每用户每分钟 10 次、URDF 批次签名 20 次、封面签名 30 次,均为独立请求尝试次数;一个 URDF 文件夹的一次批次签名算一次,不按文件数计。Fork 同时执行仍最多 2 个,文件读取/目录/历史/提交/上传合计最多 4 个。普通 JSON 256 KiB、URDF 清单 2 MiB、提交 JSON 64 MiB,原有单文件和总内容约束继续保留。全部规则和可配置变量见 [部署说明](admin-deployment.md#redis-安全与资源保护)。
登录和签名响应显式禁止缓存。CORS 新增暴露 Retry-After,不启用跨域 Cookie;正文、Token、邮箱及验证码答案不得写入前端日志。