1752 lines
99 KiB
Markdown
1752 lines
99 KiB
Markdown
# Vibemake 前端接口对接文档
|
||
|
||
供社区列表、项目详情、登录、我的工作区和在线文件编辑页面使用。前端通过 Vibemake 后端完成所有业务操作;登录 Token 是平台 Token,前端不连接 Gitea、不持有 Gitea 凭据。
|
||
|
||
项目模块和 Java 包名使用 `vibemake`,对外接口路径保持原有命名,包括 `/api/community/**`,前端调用无需调整。
|
||
|
||
当前支持项目、文件、目录、提交、手动发布、快照 Fork、评论和点赞,以及可配置开启的 Maker AI(聊天问答、查找、创建空项目、Fork)。项目发布后,后续提交只更新工作区,需要再次调用发布接口才更新社区代码。没有服务端草稿保存、独立工作区实体或项目类型表。
|
||
|
||
ZIP、TAR.GZ 下载和 HTTPS Git 本地开发的独立前端交付文档见 [仓库下载与 Git 接入](frontend-repository-download-git.md),包含六个浏览器接口、页面流程、TypeScript 示例及联调清单。
|
||
|
||
CAD 个人工作空间使用独立的 `/api/cad/workspace/projects`,共用登录,但不创建 Git 仓库、不混入现有项目列表。本人工作区带 STEP 的 READY 项目可通过 `POST /api/workspace/projects/{projectCode}/cad-project` 获取或创建关联 CAD,再进入编辑器导入 STEP,编辑结果按原生 `.sc` 保存。接口、保存续编流程和共用 OSS 配置见 [CAD 工作空间前端对接](frontend-cad-workspace.md),上线前执行 [CAD 建表及增量 SQL](cad-database.md)。
|
||
|
||
PCB 个人工作空间使用独立的 `/api/pcb/workspace/projects`,共用登录,通过完整工程 ZIP 直传 OSS 保存与续编,个人空间按独立 PCB 分类查询。接口、版本冲突、重试和部署配置见 [PCB 工作空间前端对接](frontend-pcb-workspace.md),上线前手工执行 [PCB 建表 SQL](pcb-database.md)。
|
||
|
||
CAD 网页 AI Agent 使用 `/api/cad/ai/capabilities` 和 `/api/cad/ai/chat`,支持流式回复及浏览器执行的 CAD 工具调用,复用豆包连接配置。功能默认关闭,聊天不落库;完整协议及 SolidCraft 网页适配要求见 [CAD AI Agent 前端对接](frontend-cad-ai-agent.md)。
|
||
|
||
## 阅读导航
|
||
|
||
- [接入约定](#接入约定)
|
||
- [接口总览](#接口总览)
|
||
- [响应数据结构](#响应数据结构)
|
||
- [登录和用户](#登录和用户)
|
||
- [类型与项目列表](#类型与项目列表)
|
||
- [我的项目管理](#我的项目管理)
|
||
- [项目封面与 OSS 直传](#项目封面与-oss-直传)
|
||
- [项目 URDF 文件夹](#项目-urdf-文件夹)
|
||
- [目录和文件读取](#目录和文件读取)
|
||
- [文件编辑与上传提交](#文件编辑与上传提交)
|
||
- [HTTPS Git 与本地开发](#https-git-与本地开发)
|
||
- [社区发布和撤回](#社区发布和撤回)
|
||
- [社区详情和 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: []`。
|
||
|
||
### 时间和版本
|
||
|
||
项目、评论及上传过期时间统一使用上海时间(`Asia/Shanghai`,UTC+8),JSON 格式为 `2026-10-13T08:30:00`,可能带小数秒,**没有时区后缀**。前端解析这些字段时应补充 `+08:00`,再转换成用户时区;不能继续补 `Z` 或依赖浏览器本地时区。历史提交的 `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<Project> |
|
||
| 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 或下载二进制 |
|
||
| GET | `/api/workspace/projects/{projectCode}/archive` | 是 | 当前或指定版本的 ZIP、TAR.GZ 仓库归档 |
|
||
| GET | `/api/workspace/projects/{projectCode}/git` | 是 | GitConnection |
|
||
| GET | `/api/workspace/projects/{projectCode}/git/tokens` | 是 | PageResult<GitTokenView> |
|
||
| POST | `/api/workspace/projects/{projectCode}/git/tokens` | 是 | credential 和仅返回一次的 token |
|
||
| DELETE | `/api/workspace/projects/{projectCode}/git/tokens/{tokenCode}` | 是 | null |
|
||
| POST | `/api/workspace/projects/{projectCode}/commits` | 是 | Commit |
|
||
| POST | `/api/workspace/projects/{projectCode}/cad-project` | 是 | CadProject,获取或创建关联 CAD,无请求体,见 [STEP 编辑流程](frontend-cad-workspace.md#从个人空间-step-项目进入编辑器) |
|
||
| GET | `/api/workspace/projects/{projectCode}/commits` | 是 | PageResult<HistoryEntry> |
|
||
| 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<Project> |
|
||
| GET | `/api/community/projects/{projectCode}` | 可选 | Project |
|
||
| GET | `/api/community/projects/{projectCode}/tree` | 可选 | Tree |
|
||
| GET | `/api/community/projects/{projectCode}/files` | 可选 | ProjectFile 或下载二进制 |
|
||
| GET | `/api/community/projects/{projectCode}/archive` | 可选 | 当前已发布版本的 ZIP、TAR.GZ 仓库归档 |
|
||
| POST | `/api/community/projects/{projectCode}/forks` | 是 | Project |
|
||
| GET | `/api/community/projects/{projectCode}/comments` | 可选 | PageResult<Comment> |
|
||
| 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
|
||
/** 无时区后缀,按 Asia/Shanghai(UTC+8)解释。 */
|
||
export type ShanghaiDateTime = 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 ResourceFileView {
|
||
relativePath: string;
|
||
sizeBytes: number;
|
||
url: 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
|
||
stepMainUrl: string | null; // 当前 STEP 文件公开下载地址
|
||
stepFileName: string | null; // 原始文件名
|
||
stepSizeBytes: number | null; // 实际字节数,默认最大 500 MiB
|
||
modelGlbUrl: string | null;
|
||
modelPartsBaseUrl: string | null; // 目录地址以 / 结尾
|
||
modelPartsFiles?: ResourceFileView[]; // 详情始终返回,列表省略
|
||
assemblyJsonUrl: string | null;
|
||
walkingResourcesBaseUrl: string | null;
|
||
walkingResourcesFiles?: ResourceFileView[]; // 详情始终返回,列表省略
|
||
projectType: string;
|
||
owner: PublicUser;
|
||
repoStatus: 'CREATING' | 'READY' | 'FAILED';
|
||
publishStatus: 'UNPUBLISHED' | 'PUBLISHED' | 'BLOCKED';
|
||
publishedCommitSha: string | null;
|
||
publishedAt: ShanghaiDateTime | null; // 仅后台可编辑;发布时仅在为空时填充
|
||
sourceProjectCode: string | null;
|
||
sourceCommitSha: string | null;
|
||
sourceRepositoryUrl: string | null; // 在线迁移任务记录的原仓库地址
|
||
sourceLicense: string | null; // 原仓库许可证标识,未识别时为 null
|
||
likeCount: number;
|
||
commentCount: number;
|
||
liked: boolean;
|
||
createdAt: ShanghaiDateTime;
|
||
updatedAt: ShanghaiDateTime;
|
||
}
|
||
|
||
export interface CoverUploadSignature {
|
||
uploadUrl: string;
|
||
objectKey: string;
|
||
coverUrl: string;
|
||
expiresAt: ShanghaiDateTime; // 无时区后缀,按 Asia/Shanghai(UTC+8)解释
|
||
formFields: Record<string, string>;
|
||
}
|
||
|
||
export interface UrdfFile {
|
||
relativePath: string;
|
||
sizeBytes: number;
|
||
}
|
||
|
||
export interface UrdfUploadSignature {
|
||
batchCode: string;
|
||
mainRelativePath: string;
|
||
uploadUrl: string;
|
||
expiresAt: ShanghaiDateTime; // 无时区后缀,按 Asia/Shanghai(UTC+8)解释
|
||
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: ShanghaiDateTime;
|
||
}
|
||
```
|
||
|
||
### 项目示例与状态含义
|
||
|
||
已发布项目的 data 示例:
|
||
|
||
```json
|
||
{
|
||
"projectCode": "22222222222222222222222222222222",
|
||
"name": "机器人示例项目",
|
||
"description": "模型、配置和说明文件",
|
||
"coverUrl": "https://images.example.com/vibemake/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png",
|
||
"urdfMainUrl": null,
|
||
"urdfBaseUrl": null,
|
||
"stepMainUrl": null,
|
||
"stepFileName": null,
|
||
"stepSizeBytes": null,
|
||
"modelGlbUrl": null,
|
||
"modelPartsBaseUrl": null,
|
||
"modelPartsFiles": [],
|
||
"assemblyJsonUrl": null,
|
||
"walkingResourcesBaseUrl": null,
|
||
"walkingResourcesFiles": [],
|
||
"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 使用独立副本 |
|
||
| stepMainUrl / stepFileName / stepSizeBytes | 当前 STEP 公开下载地址、原始文件名和字节数;无绑定三个字段均为 null;由管理端上传,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<Project>。工作区按创建时间倒序;社区先展示四项资源齐全的项目,再在各组内按 `publishedAt` 倒序,组内发布时间为 NULL 的排最后。资源齐全指 `model_glb_object_key`、`assembly_json_object_key`、`walking_resources_prefix`、`model_parts_prefix` 全部非 NULL 且非空字符串,对应返回的 `modelGlbUrl`、`assemblyJsonUrl`、`walkingResourcesBaseUrl`、`modelPartsBaseUrl`。资源齐全但无发布时间的项目仍排在资源不齐全的项目前面,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 约束,后端不读取或解码图片。对象路径由后端生成,日期使用 Asia/Shanghai: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/...` 等未编码的环境相对路径(也支持来自 README 和项目资源目录的托管图片),域名和环境根目录由后端配置补齐,外链原样保存。创建、PATCH、清除封面及 Fork 的调用方式不变,不允许客户端改为提交相对路径。CAD、URDF、STEP 和其他资源绑定字段均不保存环境前缀,完整规范与存量转换见 [OSS 引用规范](oss-storage-paths.md)。
|
||
|
||
历史完整平台 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 50 MiB / 202 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}` 和 `GET /api/community/projects/{projectCode}` 返回当前绑定的整机 GLB、零件目录及清单、拼装步骤 JSON、行走资源目录及清单,字段见 Project 定义。未绑定时地址为 null,文件清单为 `[]`。列表保留四类资源地址,但省略两个文件清单;需要加载零件或行走资源时请求详情。
|
||
|
||
直接使用 `modelGlbUrl` 加载整机、`assemblyJsonUrl` 读取步骤 JSON,文件夹逐项使用清单中的 `url`,不需要列举 OSS 目录。`relativePath` 保留子目录及文件名大小写,目录地址以 `/` 结尾,URL 已编码,不要再次整体编码。行走资源不保证含 `robot.json`,需要由使用方自行识别;后端不校验拼装 JSON 的业务结构。
|
||
|
||
这四类资源只由管理端上传、替换和清除,用户端不提供上传接口,项目创建或 PATCH 也不接收对应资源字段。管理端成功确认后立即更新社区详情,不依赖仓库发布版本。
|
||
|
||
Fork 直接继承这四类资源的数据库字段和原资源地址,不访问 OSS,不复制或下载这些文件,因此大资源不会增加 Fork 的文件传输耗时。来源和副本独立保存绑定,任一方替换、清除或删除项目都不会改变另一方的绑定;旧 OSS 对象保留。URDF 继续按照上一节规则独立复制。
|
||
|
||
## 目录和文件读取
|
||
|
||
### 工作区目录
|
||
|
||
`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 放进编辑器提交;使用上传替换。JSON 文件预览默认上限 50 MiB,在线文本编辑默认上限 1 MiB。
|
||
|
||
`download=true` 使用独立的流式下载链路,默认最大 **1 GiB**(`FILE_DOWNLOAD_MAX_BYTES=1073741824`),不受 JSON 预览的 50 MiB 上限影响。成功返回 `application/octet-stream`,带 `Content-Disposition: attachment`、UTF-8 文件名、`Content-Length`、`Cache-Control: no-store` 和 `X-Request-Id`,不套 JSON。下载受理时固定 SHA;工作区省略版本时使用当时的 main,社区使用当前发布版本。空文件可正常下载,LFS 指针按仓库原文返回,不自动展开实体。
|
||
|
||
工作区下载需要带 Bearer Token,应使用 fetch 获取 Blob,直接使用 a 标签或 window.open 无法附加该请求头。上游处理和读取总预算默认 **5 分钟**(`FILE_DOWNLOAD_TIMEOUT=5m`),客户端超时建议至少预留 **400 秒**。沿用文件读取限流及 `FILE_MAX_CONCURRENT` 名额,名额持有到传输结束。大小超限为 `413 FILE_TOO_LARGE`,超时为 `504 FILE_DOWNLOAD_TIMEOUT`,并发不足为 `429 FILE_BUSY`。
|
||
|
||
发包前失败返回标准 JSON;传输开始后失败会停止响应,HTTP 状态可能仍为 200,此时不再返回 JSON。网络错误、取消或长度不符应丢弃残缺文件,由用户手动重试;不要自动重试。不提供 Range 断点续传。
|
||
|
||
### 社区目录和文件
|
||
|
||
- `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。
|
||
|
||
## 仓库 ZIP、TAR.GZ 下载
|
||
|
||
- `GET /api/workspace/projects/{projectCode}/archive`:需要登录,只允许下载本人的未删除项目,仓库必须 READY。
|
||
- `GET /api/community/projects/{projectCode}/archive`:可匿名访问,只允许下载 READY、已发布且未删除项目的当前发布版本。
|
||
|
||
| 参数 | 工作区 | 社区 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| format | 可选 | 可选 | 省略为 `zip`;仅接受 `zip`、`tar.gz`,区分大小写,空字符串或其他值返回 400 |
|
||
| commitSha | 可选 | 禁止 | 工作区省略时下载当前 main,也可传入本项目的完整历史 SHA;社区传入该参数即返回 400,包括空字符串 |
|
||
|
||
示例:`GET /api/community/projects/{projectCode}/archive?format=tar.gz`。
|
||
|
||
服务端在请求受理时冻结完整 SHA,再向 Gitea 获取归档。发布 A 后工作区提交 B,社区仍下载 A;工作区默认下载 B,指定 A 的 SHA 可下载 A。下载过程中 main 或发布版本变化不会切换本次版本;撤回或删除后,新发起的社区下载返回 404。
|
||
|
||
成功返回 HTTP 200 二进制附件,不使用 ApiResponse 包装。ZIP 为 `application/zip`,TAR.GZ 为 `application/gzip`,文件名为 `{projectCode}-{SHA前12位}.{format}`;带 `Content-Disposition: attachment`、`Cache-Control: no-store` 和 `X-Request-Id`。归档内的根目录、文件层级、符号链接和 `.gitattributes` 导出规则沿用 Gitea 原生行为,不包含 Git 提交历史。
|
||
|
||
**这是 Git 仓库归档,不是项目全部资源打包。** LFS 文件保留指针,不替换为真实大文件;子模块依赖不递归下载。单独绑定于 OSS 的封面、URDF、STEP、GLB、零件、拼装及行走资源不会加入归档;如果仓库本身包含同类文件,则按仓库内容正常导出。
|
||
|
||
归档使用独立配置,不受 JSON 单文件预览 50 MiB、单文件流式下载或仓库上传 200 MiB 限制影响:
|
||
|
||
| 配置 | 默认值 | 含义 |
|
||
| --- | --- | --- |
|
||
| ARCHIVE_MAX_BYTES | 1073741824(1 GiB) | 本次下载的压缩包字节数上限 |
|
||
| ARCHIVE_TIMEOUT | 5m | 获取当前版本、等待归档及读取上游响应体的预算 |
|
||
| ARCHIVE_MAX_CONCURRENT | 2 | 单实例同时处理的归档下载数,独立于普通文件并发,超限不排队 |
|
||
| RATE_ARCHIVE_READ_PER_MINUTE | 10 | 每 IP 每分钟下载请求数,工作区和社区共用额度 |
|
||
|
||
| HTTP / code | 处理 |
|
||
| --- | --- |
|
||
| 400 BAD_REQUEST | 检查格式和 SHA;社区不要提交 commitSha |
|
||
| 401 UNAUTHORIZED | 工作区下载先登录;已失效 Token 不应携带到社区请求 |
|
||
| 404 NOT_FOUND | 项目不存在、无权访问、未公开、已撤回、已删除,或提交不存在 |
|
||
| 409 CONFLICT | 工作区仓库尚未就绪 |
|
||
| 413 ARCHIVE_TOO_LARGE | 压缩包超过归档大小上限 |
|
||
| 429 ARCHIVE_BUSY / RATE_LIMITED | 并发或频率超限,按 Retry-After 稍后手动重试 |
|
||
| 502 GITEA_ERROR | 上游异常、重定向或未返回有效归档,使用 requestId 排查 |
|
||
| 503 GITEA_NOT_CONFIGURED | 服务端仓库凭据尚未配置 |
|
||
| 504 ARCHIVE_TIMEOUT | 等待或读取超时,可稍后手动重新下载 |
|
||
| 499 ARCHIVE_CANCELLED | 客户端连接在发包前取消;主动停止时通常表现为 AbortError |
|
||
|
||
错误发生在发送附件之前时返回上述 JSON 错误;开始传输后无法改写 HTTP 状态,服务端会停止传输,不向压缩包尾部追加 JSON。此时可能表现为网络中断或下载到不完整的压缩包,应丢弃残缺文件并手动重新下载。本期不提供断点续传、下载任务或进度查询。
|
||
|
||
工作区必须使用带 Bearer Token 的 fetch;不要将 Token 拼入 URL,也不要使用无法附加请求头的直接链接。成功后读取 Blob,失败先解析 JSON。以下示例支持两种入口和 AbortController,复用本文的 API_BASE、ApiError:
|
||
|
||
```typescript
|
||
async function downloadRepositoryArchive(
|
||
scope: 'workspace' | 'community',
|
||
projectCode: string,
|
||
format: 'zip' | 'tar.gz' = 'zip',
|
||
options: { token?: string; commitSha?: string; signal?: AbortSignal } = {},
|
||
) {
|
||
if (scope === 'workspace' && !options.token) throw new Error('请先登录');
|
||
if (scope === 'community' && options.commitSha !== undefined) {
|
||
throw new Error('社区归档仅支持当前已发布版本');
|
||
}
|
||
const query = new URLSearchParams({ format });
|
||
if (options.commitSha !== undefined) query.set('commitSha', options.commitSha);
|
||
const response = await fetch(
|
||
`${API_BASE}/${scope}/projects/${encodeURIComponent(projectCode)}/archive?${query}`,
|
||
{
|
||
headers: options.token ? { Authorization: `Bearer ${options.token}` } : {},
|
||
signal: options.signal,
|
||
},
|
||
);
|
||
if (!response.ok) {
|
||
const failure = await response.json();
|
||
throw new ApiError(response.status, failure.code, failure.message,
|
||
failure.requestId ?? response.headers.get('X-Request-Id'), failure.data);
|
||
}
|
||
const disposition = response.headers.get('Content-Disposition') ?? '';
|
||
const encodedName = disposition.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
|
||
const filename = encodedName ? decodeURIComponent(encodedName) : `${projectCode}.${format}`;
|
||
const blob = await response.blob(); // 完整接收后再触发保存。
|
||
const objectUrl = URL.createObjectURL(blob);
|
||
const link = document.createElement('a');
|
||
link.href = objectUrl;
|
||
link.download = filename;
|
||
document.body.appendChild(link);
|
||
link.click();
|
||
link.remove();
|
||
setTimeout(() => URL.revokeObjectURL(objectUrl), 0);
|
||
}
|
||
|
||
const downloadController = new AbortController();
|
||
// 社区可省略 token;工作区传入平台 token。
|
||
await downloadRepositoryArchive('workspace', projectCode, 'zip', {
|
||
token, signal: downloadController.signal,
|
||
});
|
||
// 用户点击停止或离开页面时调用 downloadController.abort()。
|
||
```
|
||
|
||
Blob 下载会占用浏览器存储或内存,不代表服务端将整个归档缓存在内存中;前端应限制重复点击,捕获 AbortError 和网络错误。
|
||
|
||
## 文件编辑与上传提交
|
||
|
||
### 多文件提交
|
||
|
||
`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 字节 |
|
||
| 上传或 JSON 预览的单文件 | 50 MiB,52428800 字节 |
|
||
| 流式下载的单文件 | 1 GiB,1073741824 字节,`FILE_DOWNLOAD_MAX_BYTES` 可配置 |
|
||
| 本次上传文件或提交内容总量 | 200 MiB,209715200 字节 |
|
||
| multipart 整个请求 | 202 MiB,预留 2 MiB 表单开销 |
|
||
| 单批变更或上传文件数量 | 500 |
|
||
| multipart 表单项数量 | 1003,含 500 个 files、500 个 paths 和 3 个公共字段 |
|
||
|
||
大小按字节计算,文本使用 UTF-8 编码长度,不使用 JavaScript 字符串 length 计算文件体积。以上是当前默认配置,超限返回 413。提交 JSON 请求另受 64 MiB 默认上限约束,包含转义和结构开销。后端调整业务上传大小时还需同步调整 multipart 配置。
|
||
|
||
### 提交历史
|
||
|
||
`GET /api/workspace/projects/{projectCode}/commits?page=1&size=20`,需要登录。
|
||
|
||
data 为 PageResult<HistoryEntry>,只读取 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 失败。复制不使用 JSON 文件预览的 50 MiB 上限或流式下载的 1 GiB 上限;JSON 预览与下载各自受配置限制,在线读取不展开 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<Comment>,按创建时间倒序,平铺展示,不提供回复层级。评论 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 | JSON 预览、流式下载、编辑或上传内容超过各自大小上限,展示 message 中的限制 |
|
||
| 499 | FILE_DOWNLOAD_CANCELLED | 下载取消,丢弃残缺文件 |
|
||
| 504 | FILE_DOWNLOAD_TIMEOUT | 下载超时,丢弃残缺文件,可手动重试 |
|
||
| 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);
|
||
}
|
||
```
|
||
|
||
### 上海时间解析
|
||
|
||
对项目、评论、上传过期时间等不带时区的上海时间字段使用这个函数;历史 authorDate 已带时区时按其原值解析。前端与后端需同时切换,旧版补 `Z` 的解析方式会多显示 8 小时。
|
||
|
||
```typescript
|
||
function parseShanghaiTime(value: ShanghaiDateTime): Date {
|
||
const hasTimezone = /(?:Z|[+-]\d{2}:\d{2})$/i.test(value);
|
||
return new Date(hasTimezone ? value : `${value}+08:00`);
|
||
}
|
||
```
|
||
|
||
### 开发代理示例
|
||
|
||
使用 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、邮箱及验证码答案不得写入前端日志。
|
||
|
||
## HTTPS Git 与本地开发
|
||
|
||
Git 网关由部署开关 `GIT_ENABLED` 控制,开启后仅本人工作区可 clone/fetch/pull/push;社区项目先 Fork。网站身份沿用邮箱加图片验证码,当前不验证邮箱归属,Git Token 继承此身份校验边界。普通用户不需要 Gitea 账号。
|
||
|
||
### 接口清单与数据
|
||
|
||
以下接口均携带网站 `Authorization: Bearer <平台 Token>`,仅所有者可访问。所有成功响应仍为平台 ApiResponse,均设置 `Cache-Control: no-store`;Git 协议请求使用独立认证。
|
||
|
||
| 接口 | 作用 |
|
||
| --- | --- |
|
||
| `GET /api/workspace/projects/{projectCode}/git` | 获取克隆信息及写入状态 |
|
||
| `GET /api/workspace/projects/{projectCode}/git/tokens?page=1&size=20` | 分页查询 Git 凭据元数据 |
|
||
| `POST /api/workspace/projects/{projectCode}/git/tokens` | 创建凭据,明文只返回一次 |
|
||
| `DELETE /api/workspace/projects/{projectCode}/git/tokens/{tokenCode}` | 撤销凭据,重复撤销成功 |
|
||
|
||
克隆信息 data:
|
||
|
||
```json
|
||
{
|
||
"cloneUrl": "https://git.example.com/git/projects/7m4k9x2p8q6r.git",
|
||
"username": "111111111111",
|
||
"defaultBranch": "main",
|
||
"headCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||
"publishedCommitSha": null,
|
||
"writeStatus": "IDLE",
|
||
"canPush": true
|
||
}
|
||
```
|
||
|
||
`canPush` 表示当前项目状态、main 保护及技术账号配置允许写入,不保证后续请求一定成功;仍需读写权限的 Git Token。`writeStatus=WRITING` 表示正在写入,`REVIEW` 表示结果待核对。仅刷新页面即可看到已推送内容,不使用项目 updatedAt 判断版本。
|
||
|
||
创建请求:
|
||
|
||
```json
|
||
{"name":"我的笔记本","scope":"READ_WRITE","expiresInDays":90}
|
||
```
|
||
|
||
name 必填、非空、最多64字符;scope 为 READ_ONLY 或 READ_WRITE;expiresInDays 省略默认90,允许1~365。每项目最多10个有效凭据。读写凭据创建前会核验或初始化 main 保护;配置不兼容返回错误,不覆盖已有规则。首次签发会由后端管理账号给独立技术账号授予该仓库 write 权限,用户侧权限仍由项目 Token 决定。
|
||
|
||
创建成功 data 为 `{ "credential": GitTokenView, "token": "vbg_..." }`;列表 data 为 `PageResult<GitTokenView>`。GitTokenView 只有 tokenCode、name、scope、status、createdAt、expiresAt、revokedAt、lastUsedAt。status 为 ACTIVE、EXPIRED、REVOKED(包括账号会话版本变化失效)。时间沿用本文上海时间约定。最近使用时间最多每5分钟写回一次。
|
||
|
||
明文仅在创建时展示一次,不能再次查询;遗失后撤销并新建。列表、日志、数据库均不保存或返回明文。普通退出网站不撤销 Git Token;撤销、过期、禁用账号或账号 sessionVersion 改变后,新 Git/LFS 请求会被拒绝。已经受理的传输不保证立即中止或回滚。
|
||
|
||
### 网站交互与本地使用
|
||
|
||
工作区提供“克隆与本地开发”入口,显示克隆 URL、用户名、main SHA、发布 SHA 和写入状态;提供 Token 创建、列表、撤销和一次性明文展示。明文只保存在当前展示状态,不写 localStorage、不放克隆 URL、查询参数或日志。用户可用操作系统凭据管理器保存。
|
||
|
||
Git 使用 HTTP Basic:用户名为网站 userCode,密码为项目 Git Token;网站 Bearer Token 不能用于 Git,Git Token 不能用于普通 `/api`。同域名不同项目必须配置 HTTP 路径级凭据:
|
||
|
||
```bash
|
||
git lfs install
|
||
git -c credential.useHttpPath=true clone --single-branch --branch main <cloneUrl>
|
||
cd <本地仓库目录>
|
||
git config credential.useHttpPath true
|
||
|
||
git add .
|
||
git commit -m "更新项目"
|
||
git push origin main
|
||
```
|
||
|
||
支持标准 Git v0/v2 读取、main 正常快进更新和合并提交,保留本地提交作者、邮箱、时间、签名及 SHA。禁止强推、删除 main、创建其他分支或标签、多引用推送、push-options、signed-push 扩展;普通签名提交支持。仓库已有其他分支和标签可以读取,本期不清理历史数据。LFS Basic Transfer 支持实体上传、下载和 verify;不支持 LFS 文件锁,locks/verify 返回空集合,锁创建/删除返回501。不递归下载子模块,独立绑定的 OSS 封面、URDF、STEP、模型等资源不会自动进入仓库。
|
||
|
||
本地 push 后重新请求工作区 tree、files、commits 显示最新内容;社区仍固定 publishedCommitSha,需用户明确点击发布。网页编辑基准落后继续返回409,保留用户输入;本地 main 落后时先 pull、合并再 push。REVIEW 期间阻止仓库写入及发布,后台只读核对,不自动重推。网络断开或超时不能视为失败,先刷新核对。
|
||
|
||
前端创建示例(复用本文 request):
|
||
|
||
```ts
|
||
interface GitTokenView {
|
||
tokenCode: string;
|
||
name: string;
|
||
scope: 'READ_ONLY' | 'READ_WRITE';
|
||
status: 'ACTIVE' | 'EXPIRED' | 'REVOKED';
|
||
createdAt: string;
|
||
expiresAt: string;
|
||
revokedAt: string | null;
|
||
lastUsedAt: string | null;
|
||
}
|
||
async function createGitToken(projectCode: string, token: string) {
|
||
return request<{credential: GitTokenView; token: string}>(
|
||
`/workspace/projects/${encodeURIComponent(projectCode)}/git/tokens`, {
|
||
method: 'POST', token,
|
||
body: {name: '我的笔记本', scope: 'READ_WRITE', expiresInDays: 90},
|
||
});
|
||
}
|
||
```
|
||
|
||
协议路径 `/git/**` 成功响应为 Git pkt-line/pack 或 LFS 标准结构;错误使用 Git 文本或 LFS `{message}`,不使用平台包装。401 含 Basic challenge,429 含 Retry-After。不要用浏览器平台 JSON 请求封装访问协议路径。
|
||
|
||
| 错误码/状态 | 处理 |
|
||
| --- | --- |
|
||
| GIT_UNAVAILABLE / 503 | 功能关闭或依赖不可用,保留网站编辑入口;仍可查询、撤销已有凭据 |
|
||
| GIT_POLICY_UNAVAILABLE / 503 | 技术账号或 main 保护不兼容,联系运维,不放宽规则 |
|
||
| CONFLICT / 409 | 有效凭据已达上限,先撤销旧凭据 |
|
||
| GIT_UNAUTHORIZED / 401 | 用户名或项目 Git Token 无效、过期或撤销 |
|
||
| GIT_READ_ONLY / 403 | 使用读写 Token 后再推送或上传 LFS |
|
||
| GIT_COMMAND_REJECTED / 400 | 仅推送 main,移除不支持的引用/扩展 |
|
||
| GIT_STALE_MAIN / 409 | 先拉取、合并,再推送 |
|
||
| GIT_BUSY / 429 | 用户限流、IP认证失败限流或并发已满,稍后手动重试 |
|
||
| GIT_TRANSFER_TOO_LARGE、GIT_METADATA_TOO_LARGE、LFS_TOO_LARGE / 413 | 缩小请求或联系运维核对配置 |
|
||
| GIT_TIMEOUT / 504、GIT_UPSTREAM_ERROR / 502、REMOTE_RESULT_UNKNOWN / 409或503 | 涉及 push 时先刷新工作区及历史,结果未确认前不能重复写入 |
|
||
|
||
默认 pack 5 GiB、LFS 单对象1 GiB、元数据8 MiB、batch最多500个对象;每次 Git/LFS 请求预算10分钟,含请求及响应流。读取/push/LFS 每实例并发4/2/8;每用户每分钟 Git120次、LFS600次,每IP每分钟最多20次认证失败。均可配置,独立于 JSON、multipart、50 MiB 文件预览、单文件流式下载和归档下载限制。中途超限、超时或断开会终止传输;不提供任务、进度查询或断点续传接口。
|