Files
community/docs/api.md
T
2026-10-14 10:26:20 +08:00

966 lines
38 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.
# Community 前端接口对接文档
供社区列表、项目详情、登录、我的工作区和在线文件编辑页面使用。前端通过 Community 后端完成所有业务操作;登录 Token 是平台 Token,前端不连接 Gitea、不持有 Gitea 凭据。
当前支持项目、文件、目录、提交、手动发布、快照 Fork、评论和点赞。项目发布后,后续提交只更新工作区,需要再次调用发布接口才更新社区代码。没有服务端草稿保存、AI 检索、独立工作区实体或项目类型表。
## 阅读导航
- [接入约定](#接入约定)
- [接口总览](#接口总览)
- [响应数据结构](#响应数据结构)
- [登录和用户](#登录和用户)
- [类型与项目列表](#类型与项目列表)
- [我的项目管理](#我的项目管理)
- [目录和文件读取](#目录和文件读取)
- [文件编辑与上传提交](#文件编辑与上传提交)
- [社区发布和撤回](#社区发布和撤回)
- [社区详情和 Fork](#社区详情和-fork)
- [评论和点赞](#评论和点赞)
- [错误码与前端处理](#错误码与前端处理)
- [页面调用顺序](#页面调用顺序)
- [前端请求示例](#前端请求示例)
- [后端人工核对](#后端人工核对)
## 接入约定
### 地址和请求头
本机默认后端地址为 `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`,部署时通过同域反向代理访问;仅允许 OPTIONS 请求不代表已经支持浏览器跨域访问。
### 统一响应
除成功的文件下载外,响应为以下 JSON 结构。所有成功接口使用 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 对象标识,前端不用它提交文件 |
项目详情不包含工作区当前 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[] |
| 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 |
| 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 |
## 响应数据结构
以下 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;
projectType: string;
owner: PublicUser;
repoStatus: 'CREATING' | 'READY' | 'FAILED';
publishStatus: 'UNPUBLISHED' | 'PUBLISHED';
publishedCommitSha: string | null;
publishedAt: UtcDateTime | null;
sourceProjectCode: string | null;
sourceCommitSha: string | null;
likeCount: number;
commentCount: number;
liked: boolean;
createdAt: UtcDateTime;
updatedAt: UtcDateTime;
}
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": "模型、配置和说明文件",
"projectType": "GENERAL",
"owner": {
"userCode": "11111111111111111111111111111111",
"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 | 当前在社区展示 |
| publishedCommitSha / publishedAt | 撤回后可能仍保留上一次发布值,是否公开必须判断 publishStatus |
| sourceProjectCode / sourceCommitSha | Fork 来源及复制的源版本;普通新项目为 null |
| liked | 当前请求用户是否点赞,匿名访问为 false |
工作区归属由 `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": "11111111111111111111111111111111",
"nickname": "用户_11111111",
"email": "user@example.com"
}
},
"requestId": "44444444444444444444444444444444"
}
```
首次登录自动创建用户,邮箱统一转成小写。当前只验证邮箱格式与图片验证码,不发送邮件、不使用密码,也不验证邮箱归属。Token 有效期默认 24 小时,以 expiresIn 为准,不是 JWT,没有刷新 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": "轮式" }
]
```
左侧类型导航和创建项目下拉框使用这个接口,不在前端写死类型码。“全部”筛选不传 type。当前内置 GENERAL(通用)、HUMANOID(人形)、QUADRUPED(四足)、WHEELED(轮式),创建或修改项目时通过 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;。工作区按创建时间倒序,社区按最近发布时间倒序;不支持客户端指定排序。更换类型或关键词时,把 page 重置为 1。
## 我的项目管理
以下接口需要登录,且只能操作当前用户的项目。项目不存在、已删除或属于其他用户,均返回 404。
### 创建项目
`POST /api/workspace/projects`。
| 请求字段 | 必填 | 约束 |
| --- | --- | --- |
| name | 是 | 非空,最多 100 字符,保存时去掉首尾空格 |
| description | 否 | 最多 2000 字符,省略或 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 会清空描述。前端编辑表单应提交完整的三个字段。
已发布项目的名称、描述、类型会直接更新社区展示,不生成文件 Commit。
### 删除项目
`DELETE /api/workspace/projects/{projectCode}`,无请求体,成功 data 为 null。
项目逻辑删除并从社区撤回,已有独立 Fork 不受影响。再次操作已删除项目返回 404。
## 目录和文件读取
### 工作区目录
`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 |
大小按字节计算,文本使用 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 复制发布版本的所有普通文件,不复制源仓库提交历史,不自动同步上游。允许同一用户多次 Fork。所有文件复制完成才返回 READY;不支持符号链接或子模块。
源项目发布版本已变化时返回 409 CONFLICT,刷新社区详情后由用户重新确认。Fork 是同步请求,可能耗时较长;提交期间显示加载状态并防止重复点击。超时、网络断开或失败后先查询工作区,不要自动重发。
## 评论和点赞
### 评论列表
`GET /api/community/projects/{projectCode}/comments?page=1&size=20`,可选登录。
data 为 PageResult&lt;Comment&gt;,按创建时间倒序,平铺展示,不提供回复层级。评论 data 示例:
```json
{
"commentCode": "33333333333333333333333333333333",
"author": {
"userCode": "11111111111111111111111111111111",
"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;可以先做乐观更新,失败时恢复并刷新详情。
## 错误码与前端处理
### 错误响应示例
版本冲突通常不带 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 请求超限 |
| 415 | UNSUPPORTED_MEDIA_TYPE | 检查 Content-Type,JSON 与 FormData 不要混用 |
| 500 | CAPTCHA_ERROR | 验证码生成失败,可重新获取并记录 requestId |
| 500 | PROJECT_INITIALIZATION_ERROR | 项目初始化或回写未完成,查看 data.projectCode 和工作区,请后端核对 |
| 500 | INTERNAL_ERROR | 展示服务异常并保留 requestId |
| 502 | GITEA_ERROR | 仓库服务异常;写请求先核对结果,避免自动重试 |
| 502 | GITEA_INVALID_RESPONSE | 仓库响应无法确认;写请求先核对结果,避免自动重试 |
| 503 | GITEA_NOT_CONFIGURED | 后端缺少仓库配置,请后端处理 |
| 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 获取当前版本 |
| 文件编辑 | workspace 详情与 tree → files → 判断 editable → commits → 刷新版本、目录和文件 |
| 上传文件 | tree 获取基准 SHA → uploads/commit → 刷新目录和当前版本 |
| 发布或更新社区 | 获取最新工作区 SHA → publication → 刷新项目和社区页面 |
| Fork | 获取社区详情中的发布 SHA → forks → 使用新 projectCode 进入工作区 |
| 评论或点赞 | 完成写请求 → 刷新评论或项目详情中的统计字段 |
## 前端请求示例
以下示例使用浏览器 fetch 和 TypeScript,类型声明见前面的响应结构。API_BASE 使用 `/api`,配合同域反向代理或开发代理。
### 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:
```typescript
export default {
server: {
proxy: {
'/api': {
target: 'http://localhost:8993',
changeOrigin: true,
},
},
},
};
```
## 后端人工核对
本节供前端遇到写入结果不明时与后端协作使用。记录 projectCode、requestId、接口路径及操作时间,提供给后端;不要在日志或工单中记录 Token、验证码答案、邮箱或文件内容。
后端先按 projectCode 对应的固定仓库名核对仓库、文件与提交历史。初始化未完成的项目核对后修正 repo_status 和仓库映射;确认没有远端写入仍在执行后,再重启后端解除本机待核对标记。超时不能直接视为未提交后再次写入。数据库结构见 [四表数据库说明](database.md)。