# 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<Project> | | 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<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 或下载二进制 | | 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 | ## 响应数据结构 以下 TypeScript 类型与当前 JSON 字段对应。项目列表、工作区详情、社区详情、创建、修改、发布和 Fork 共用 Project 结构。 ```typescript /** 无时区后缀,按 UTC 解释。 */ export type UtcDateTime = string; export interface ApiResponse { code: string; message: string; data: T | null; requestId: string; } export interface PageResult { 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<Project>。工作区按创建时间倒序,社区按最近发布时间倒序;不支持客户端指定排序。更换类型或关键词时,把 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<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 复制发布版本的所有普通文件,不复制源仓库提交历史,不自动同步上游。允许同一用户多次 Fork。所有文件复制完成才返回 READY;不支持符号链接或子模块。 源项目发布版本已变化时返回 409 CONFLICT,刷新社区详情后由用户重新确认。Fork 是同步请求,可能耗时较长;提交期间显示加载状态并防止重复点击。超时、网络断开或失败后先查询工作区,不要自动重发。 ## 评论和点赞 ### 评论列表 `GET /api/community/projects/{projectCode}/comments?page=1&size=20`,可选登录。 data 为 PageResult<Comment>,按创建时间倒序,平铺展示,不提供回复层级。评论 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( path: string, options: { method?: string; token?: string; body?: unknown; signal?: AbortSignal; } = {}, ): Promise { 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; 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 } ``` 调用处捕获 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>(`/community/projects?${query}`); } async function readWorkspaceFile(projectCode: string, path: string, token: string) { const query = new URLSearchParams({ path }); return request( `/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( `/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)。