# Community 管理后台前端接口文档 适用模块:`community-adminapi`。本文按当前后端实现整理,可直接用于后台页面开发和联调。接口均已包含 `/admin-api` 前缀;示例数据仅用于说明字段结构。 部署、管理员初始化及服务配置见 [部署说明](admin-deployment.md),前端对接无需执行数据库操作。 ## 1. 接入约定 | 项目 | 约定 | | --- | --- | | 本地服务地址 | `http://localhost:8994` | | 接口前缀 | `/admin-api` | | 测试、生产地址 | 由后端提供,可通过前端代理统一到 `/admin-api` | | 在线 Swagger | `http://localhost:8994/swagger-ui.html` | | OpenAPI JSON | `http://localhost:8994/v3/api-docs` | | 身份验证 | 除登录外,所有业务接口携带 `Authorization: Bearer ` | | 请求格式 | 默认 `application/json`;Git 文件上传为 `multipart/form-data` | | 编码 | UTF-8;字段为 camelCase | | 分页 | `page` 从 **1** 开始,默认 1;`size` 默认 20,范围 1~100 | | 业务编码 | `userCode`、`projectCode`、`taskCode` 均为字符串,原样保存和传递 | 后台 Token 与社区端 `/api` 的 Token 不通用,前端应独立保存后台登录状态。无需 Cookie,不设置 `credentials: 'include'`。跨域联调时将前端完整来源地址交给后端配置;也可以通过开发服务器代理访问。 本文内容: - [通用响应和请求封装](#2-通用响应和请求封装) - [登录与账号](#3-登录与账号) - [用户管理](#4-用户管理) - [项目管理](#5-项目管理) - [目录文件与提交](#6-目录文件与提交) - [封面上传](#7-封面上传) - [URDF 目录上传](#8-urdf-目录上传) - [GitHub 项目迁移](#9-github-项目迁移) - [错误处理](#10-错误处理) - [页面调用顺序与联调检查](#11-页面调用顺序与联调检查) ## 2. 通用响应和请求封装 ### 2.1 响应结构 成功响应: ```json { "code": "OK", "message": "成功", "data": null, "requestId": "e27eaa6c4cd94df582c0588d2a851e69" } ``` 错误响应示例(HTTP 409): ```json { "code": "CONFLICT", "message": "工作区版本已变化,请刷新后重新提交", "data": null, "requestId": "e27eaa6c4cd94df582c0588d2a851e69" } ``` 错误的 `data` 通常为 `null`,部分错误包含辅助信息,例如重复迁移返回 `{ "projectCode": "已有项目编码" }`。错误提示优先使用 `message`,同时保留 `code` 和 `requestId` 供排查。 - 普通成功返回 HTTP **200**;创建、重试迁移任务返回 **202**,`code` 同样为 `OK`。 - 没有业务返回值的操作也返回上述 JSON,`data: null`,不是空响应。 - 文件下载成功返回二进制;OSS 直传返回 OSS 自身响应。这两种请求不要经过普通 JSON 解包逻辑。 分页示例: ```json { "code": "OK", "message": "成功", "data": { "items": [], "page": 1, "size": 20, "total": 0 }, "requestId": "e27eaa6c4cd94df582c0588d2a851e69" } ``` **分页列表字段是 `items`,不是 `records`、`list` 或 `rows`。** 筛选条件为空时省略参数,尤其不要发送 `role=`、`status=` 等空枚举。 ### 2.2 时间和公共类型 ```ts type UtcDateTime = string; interface ApiResponse { code: string; message: string; data: T; requestId: string | null; } interface PageResponse { items: T[]; page: number; size: number; total: number; } ``` `createdAt`、`updatedAt`、`publishedAt`、`expiresAt`、`startedAt`、`finishedAt` 为 UTC 时间字符串,例如 `2026-10-20T02:30:00.123`,当前没有时区后缀。前端按 UTC 解析后再格式化为本地时间,不能直接当作北京时间。提交历史的 `authorDate` 沿用 Git 日期,可能自带 `Z` 或时区偏移。 ```ts function parseServerTime(value: string): Date { return new Date(/(?:Z|[+-]\d{2}:?\d{2})$/i.test(value) ? value : `${value}Z`); } ``` ### 2.3 可复用请求示例 以下示例使用原生 `fetch`。`ADMIN_API_BASE` 已包含 `/admin-api`,函数调用时传 `/users` 等后续路径,避免重复拼接。实际项目中把 `adminToken` 接到自己的登录状态管理即可。 ```ts const ADMIN_API_BASE = '/admin-api'; // 开发代理;直连可改为 http://localhost:8994/admin-api let adminToken: string | null = null; class AdminApiError extends Error { constructor( public status: number, public code: string, message: string, public requestId: string | null, public details: unknown, ) { super(message); } } interface AdminRequestOptions { method?: string; body?: unknown; signal?: AbortSignal; anonymous?: boolean; } async function requestAdmin(path: string, options: AdminRequestOptions = {}): Promise { const headers = new Headers({ Accept: 'application/json' }); if (!options.anonymous && adminToken) { headers.set('Authorization', `Bearer ${adminToken}`); } let body: BodyInit | undefined; if (options.body instanceof FormData) { body = options.body; // 不手动设置 multipart Content-Type } else if (options.body !== undefined) { headers.set('Content-Type', 'application/json'); body = JSON.stringify(options.body); } const response = await fetch(`${ADMIN_API_BASE}${path}`, { method: options.method ?? 'GET', headers, body, signal: options.signal, }); // 代理层有时返回非 JSON;这种情况也要作为错误交给页面处理。 const result = await response.json().catch(() => null) as ApiResponse | null; if (!response.ok || result?.code !== 'OK') { throw new AdminApiError( response.status, result?.code ?? 'INVALID_RESPONSE', result?.message ?? '服务响应异常,请稍后查看状态', result?.requestId ?? response.headers.get('X-Request-Id'), result?.data, ); } return result.data; } function queryString(values: Record): string { const query = new URLSearchParams(); for (const [key, value] of Object.entries(values)) { if (value !== undefined && value !== null && value !== '') { query.set(key, String(value)); } } return query.size ? `?${query.toString()}` : ''; } ``` 在页面或统一拦截层处理 `AdminApiError`。登录接口的 401 显示账号密码错误;其他接口的 401 清空后台登录状态并返回登录页。不要给写请求配置自动重试,详情见 [错误处理](#10-错误处理)。 ## 3. 登录与账号 ### 3.1 类型 ```ts interface AdminView { userCode: string; email: string; nickname: string; role: 'ADMIN'; } interface LoginView { token: string; tokenType: 'Bearer'; expiresIn: number; // 秒 admin: AdminView; } ``` ### 3.2 登录 `POST /admin-api/auth/login`,不携带 Authorization。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | email | string | 是 | 合法邮箱,最多 254 字符 | | password | string | 是 | 管理员密码,不能是空白;UTF-8 最多 72 字节 | ```json { "email": "admin@example.com", "password": "ExamplePassword123!" } ``` 成功响应示例: ```json { "code": "OK", "message": "成功", "data": { "token": "<登录成功后返回的随机Token>", "tokenType": "Bearer", "expiresIn": 28800, "admin": { "userCode": "a1b2c3d4e5f6", "email": "admin@example.com", "nickname": "社区管理员", "role": "ADMIN" } }, "requestId": "e27eaa6c4cd94df582c0588d2a851e69" } ``` ```ts async function login(email: string, password: string): Promise { const result = await requestAdmin('/auth/login', { method: 'POST', anonymous: true, body: { email, password }, }); adminToken = result.token; return result.admin; } ``` 后台只允许正常的 `ADMIN` 登录。普通用户、官方账号、禁用账号、密码错误均不能登录,不根据失败文案判断账号是否存在。连续失败会触发 429,提示 15 分钟后重试。 会话默认 8 小时,以 `expiresIn` 为准;服务重启后需要重新登录。无刷新 Token 接口。不要把 Token、密码写入控制台、埋点或错误上报。 ### 3.3 当前用户、退出、修改密码 | 方法和路径 | 请求 | 返回的 data | | --- | --- | --- | | `GET /admin-api/auth/me` | 无 | `AdminView` | | `POST /admin-api/auth/logout` | 无 body | `null` | | `PUT /admin-api/auth/password` | `{ "oldPassword": "原密码", "newPassword": "新密码" }` | `null` | 页面初始化时调用 `/auth/me` 确认登录状态,不能只判断本地是否有 Token。退出后清空本地后台状态。 新密码至少 12 字符,UTF-8 最多 72 字节;前端可用 `new TextEncoder().encode(password).byteLength` 计算字节数。修改成功会使该账号全部旧会话失效,清空 Token 并引导重新登录。原密码错误返回 400 `PASSWORD_INVALID`。 第一版没有后台注册、验证码登录、角色编辑、找回密码接口。 ## 4. 用户管理 ### 4.1 用户字段 ```ts type UserRole = 'USER' | 'ADMIN' | 'OFFICIAL'; type UserStatus = 'ACTIVE' | 'DISABLED'; interface UserView { userCode: string; nickname: string; email: string; status: UserStatus; role: UserRole; projectCount: number; // 名下未删除项目数 createdAt: UtcDateTime; } ``` 展示文案:`USER` 普通用户,`ADMIN` 管理员,`OFFICIAL` 官方托管账号;`ACTIVE` 正常,`DISABLED` 禁用。 ### 4.2 用户列表 `GET /admin-api/users` → `PageResponse`。 | Query 参数 | 类型 | 说明 | | --- | --- | --- | | page / size | number | 通用分页 | | userCode | string | 用户编码精确匹配 | | nickname | string | 昵称模糊匹配,最多 254 字符 | | email | string | 邮箱模糊匹配,最多 254 字符 | | role | UserRole | 角色筛选 | | status | UserStatus | 状态筛选 | 例如:`GET /admin-api/users?page=1&size=20&role=USER&status=ACTIVE`。结果按创建时间倒序。 ### 4.3 用户详情和操作 | 方法和路径 | 请求 | 返回的 data | | --- | --- | --- | | `GET /admin-api/users/{userCode}` | 无 | `UserView` | | `PATCH /admin-api/users/{userCode}` | `{ "nickname": "新昵称" }`,必填,1~64 字符 | `UserView` | | `PUT /admin-api/users/{userCode}/status` | `{ "status": "DISABLED" }` 或 `{ "status": "ACTIVE" }` | `null` | | `GET /admin-api/users/{userCode}/projects` | Query:page、size | `PageResponse` | - 禁止禁用当前登录管理员及官方账号;前端隐藏或禁用对应按钮,后端也会校验并返回 409。 - 禁用立即使原会话失效;重新启用后用户仍需重新登录。 - 禁用不会自动下架其项目;项目下架需要单独操作。 - 用户编辑只支持昵称,没有删除用户、修改邮箱、修改角色、转移项目接口。 ## 5. 项目管理 ### 5.1 项目字段 ```ts type RepoStatus = 'CREATING' | 'READY' | 'FAILED'; type PublishStatus = 'UNPUBLISHED' | 'PUBLISHED' | 'BLOCKED'; interface ProjectInput { name: string; description?: string | null; projectType: string; coverUrl?: string | null; } interface ProjectView { projectCode: string; name: string; description: string; coverUrl: string | null; urdfMainUrl: string | null; urdfBaseUrl: string | null; projectType: string; owner: { userCode: string | null; nickname: string }; repoStatus: RepoStatus; publishStatus: PublishStatus; publishedCommitSha: string | null; publishedAt: UtcDateTime | null; sourceProjectCode: string | null; sourceCommitSha: string | null; likeCount: number; commentCount: number; liked: boolean; sourceRepositoryUrl: string | null; sourceLicense: string | null; createdAt: UtcDateTime; updatedAt: UtcDateTime; } interface ManagedProjectView { project: ProjectView; moderationStatus: 'NORMAL' | 'BLOCKED'; moderationReason: string | null; deleted: boolean; } interface TypeView { code: string; name: string; } ``` 字段说明: | 字段 | 页面用途 | | --- | --- | | repoStatus | `CREATING` 仓库准备中;`READY` 可使用;`FAILED` 准备失败 | | publishStatus | `UNPUBLISHED` 未发布;`PUBLISHED` 已发布;`BLOCKED` 管理员下架 | | publishedCommitSha | 社区当前已发布的文件版本,**不是工作区最新版本** | | moderationStatus / moderationReason | 后台治理状态及下架原因;BLOCKED 与 publishStatus=BLOCKED 对应 | | sourceProjectCode / sourceCommitSha | 从社区内部 Fork 的来源;没有则为 null | | sourceRepositoryUrl / sourceLicense | 在线迁移项目的外部来源和许可证;没有或未取得则为 null | | urdfMainUrl / urdfBaseUrl | 已绑定的 URDF 主文件和资源基地址;未绑定则为 null | | liked | 沿用项目公共字段,后台管理页面通常不需要使用 | **响应层次有差别:** 列表、详情、用户名下项目返回 `ManagedProjectView`,项目名称是 `data.project.name` 或 `data.items[i].project.name`;创建、编辑、发布、URDF 确认返回 `ProjectView`,名称是 `data.name`。 ### 5.2 类型和所有者选项 `GET /admin-api/projects/types` → `TypeView[]`,示例 data: ```json [ { "code": "GENERAL", "name": "通用" }, { "code": "HUMANOID", "name": "人形" }, { "code": "QUADRUPED", "name": "四足" }, { "code": "WHEELED", "name": "轮式" }, { "code": "ROBOTIC_ARM", "name": "机械臂" } ] ``` 类型以下发列表为准,不在前端固定允许值。查询使用 `type` 参数,创建/编辑 body 使用 `projectType`。 新建和迁移表单的归属选项: - 默认“社区官方”,不传 `ownerUserCode`。 - 选择用户时查询 `GET /admin-api/users?role=USER&status=ACTIVE`,可附加 nickname/email 搜索,分页选择。 - 指定已有正常普通用户的 `userCode`;不能选择管理员、禁用用户或指定其他官方账号。 - 创建后不支持变更归属。实际文件提交作者为操作管理员,项目所有者不会改变。 ### 5.3 项目列表和详情 `GET /admin-api/projects` → `PageResponse`。 | Query 参数 | 说明 | | --- | --- | | page / size | 通用分页 | | ownerUserCode | 按所有者编码精确筛选 | | type | 项目类型编码 | | keyword | 名称或描述模糊搜索,最多 254 字符 | | publishStatus | UNPUBLISHED / PUBLISHED / BLOCKED | | repoStatus | CREATING / READY / FAILED | | moderationStatus | NORMAL / BLOCKED | 结果只包含未删除项目,按创建时间倒序。没有 `creationSource` 筛选,也没有已删除项目回收站。 `GET /admin-api/projects/{projectCode}` → `ManagedProjectView`,示例 data: ```json { "project": { "projectCode": "b2c3d4e5f6a7", "name": "社区机器人", "description": "项目说明", "coverUrl": null, "urdfMainUrl": null, "urdfBaseUrl": null, "projectType": "WHEELED", "owner": { "userCode": "c3d4e5f6a7b8", "nickname": "社区官方" }, "repoStatus": "READY", "publishStatus": "UNPUBLISHED", "publishedCommitSha": null, "publishedAt": null, "sourceProjectCode": null, "sourceCommitSha": null, "likeCount": 0, "commentCount": 0, "liked": false, "sourceRepositoryUrl": null, "sourceLicense": null, "createdAt": "2026-10-20T02:30:00", "updatedAt": "2026-10-20T02:30:00" }, "moderationStatus": "NORMAL", "moderationReason": null, "deleted": false } ``` ### 5.4 创建、编辑、删除 `POST /admin-api/projects` → `ProjectView`,body: ```json { "project": { "name": "社区机器人", "description": "项目说明", "projectType": "WHEELED", "coverUrl": null } } ``` 指定归属时在最外层加 `ownerUserCode`。成功后项目保持未发布,可直接进入详情页上传文件。 `PATCH /admin-api/projects/{projectCode}` → `ProjectView`,body 为**平铺的项目信息**: ```json { "name": "社区机器人 V2", "description": "更新后的说明", "projectType": "WHEELED", "coverUrl": "" } ``` | 字段 | 校验及编辑行为 | | --- | --- | | name | 必填,非空白,最多 100 字符 | | description | 最多 2000 字符;省略或 null 会保存为空字符串 | | projectType | 必填,来自类型接口,最多 64 字符 | | coverUrl | 可空,HTTPS 地址最多 2048 字符;编辑时省略/null 保留旧封面,传 `""` 清空 | 虽然方法为 PATCH,**name、projectType 仍必须传**。编辑表单应提交当前完整基础信息,避免只传一个字段或意外清空 description。基础信息保存后直接生效;发布 Commit 主要固定 Git 文件版本。 `DELETE /admin-api/projects/{projectCode}`,无 body → `null`。前端二次确认后调用,成功返回列表并刷新。逻辑删除且社区不可见,无恢复接口。 ### 5.5 发布、撤回、下架 | 方法和路径 | 请求 | 返回的 data | | --- | --- | --- | | `PUT /admin-api/projects/{projectCode}/publication` | `{ "commitSha": "确认过的当前main完整SHA" }` | `ProjectView` | | `DELETE /admin-api/projects/{projectCode}/publication` | 无 body | `null` | | `PUT /admin-api/projects/{projectCode}/moderation` | `{ "reason": "下架原因" }`,必填,1~500 字符 | `null` | | `DELETE /admin-api/projects/{projectCode}/moderation` | 无 body | `null` | 发布步骤:读取当前目录获得 `commitSha` → 管理员检查文件 → 明确点击发布 → 提交该 SHA。只能发布当前 `main` 版本;版本变化返回 409,刷新并重新确认,不能静默改 SHA 再发。 文件提交不会自动更新社区已发布版本。已发布项目可以继续编辑文件,明确再次发布后才更新公开文件快照。 | 状态 | 建议操作 | | --- | --- | | repoStatus 非 READY | 展示准备中/失败及迁移任务;不开放目录、文件提交和发布 | | READY + UNPUBLISHED | 查看、编辑、上传、发布、下架、删除 | | READY + PUBLISHED | 查看、编辑、上传、更新发布、撤回、下架、删除 | | READY + BLOCKED | 查看、编辑、上传、解除下架、删除;禁止发布 | 撤回是停止公开;下架同时禁止所有者重新发布。普通撤回不能解除 BLOCKED。解除下架后变为 UNPUBLISHED,仍需明确发布。上述按钮状态是前端提示,遇到服务端冲突仍以接口结果为准。 ## 6. 目录、文件与提交 所有操作面向 `main` 工作区。历史查看可以指定 Commit;不提供分支切换、仓库 ZIP 解压或大文件分片上传接口。 ### 6.1 类型及路径规则 ```ts interface TreeEntry { path: string; name: string; type: string; // 常见 file、dir;迁移项目可能有其他 Git 条目 size: number; // 字节 blobSha: string | null; } interface TreeView { commitSha: string; path: string; entries: TreeEntry[]; } interface FileView { commitSha: string; path: string; blobSha: string; size: number; encoding: 'utf-8' | 'base64'; content: string; editable: boolean; } interface CommitView { commitSha: string; message: string; } interface HistoryEntry { commitSha: string; message: string; authorName: string; authorDate: string; } ``` 路径必须是仓库相对路径,例如 `README.md`、`docs/使用说明.md`: - 根目录用空字符串 `""`,不使用 `/`;目录路径不带末尾 `/`。 - 使用 `/` 分隔,不允许 `\`、空路径段、`.`、`..`、`.git`、冒号或控制字符;总长度不超过 1024 字符。 - Query 用 `URLSearchParams` 编码;JSON、FormData 中直接传原始相对路径。 - SHA 使用接口返回的完整字符串(40 或 64 位十六进制),不截断、不自行生成。 ### 6.2 目录和文件读取 | 方法和路径 | Query | 返回的 data | | --- | --- | --- | | `GET /admin-api/projects/{projectCode}/tree` | path 默认空;commitSha 可选 | `TreeView` | | `GET /admin-api/projects/{projectCode}/files` | path 必填;commitSha 可选;download 默认 false | `FileView` | | `GET /admin-api/projects/{projectCode}/files` | 同上,download=true | 二进制响应 | | `GET /admin-api/projects/{projectCode}/commits` | page、size | `PageResponse` | 不传 `commitSha` 时读取当前 main。需要一致地浏览某次快照时,后续目录和文件请求都带上首次取得的 `commitSha`。 ```ts async function readProjectFile(projectCode: string, path: string, commitSha?: string): Promise { return requestAdmin( `/projects/${projectCode}/files${queryString({ path, commitSha })}`, ); } ``` `encoding=utf-8` 且 `editable=true` 才开放文本编辑;`base64` 代表原始文件内容的 Base64,可按文件类型预览或下载,不能直接当文本提交。在线文本上限默认 1 MiB。符号链接、子模块不支持按普通文件读取,迁移仓库中的 LFS 文件也不保证能在线预览。 下载使用携带后台 Authorization 的 `fetch`,成功后 `response.blob()`,从 `Content-Disposition` 获取文件名并触发保存。不要把 Token 拼到 URL,也不要直接用不带鉴权的 `` 下载。下载失败仍可能是 JSON 错误,应先判断 HTTP 状态。 ### 6.3 在线文本、多文件变更 `POST /admin-api/projects/{projectCode}/commits` → `CommitView`。 ```ts type ChangeAction = 'CREATE_FILE' | 'UPDATE_FILE' | 'DELETE_FILE' | 'CREATE_DIRECTORY'; interface FileChange { action: ChangeAction; path: string; content?: string | null; } interface CommitInput { expectedCommitSha: string; message: string; changes: FileChange[]; } ``` ```json { "expectedCommitSha": "1111111111111111111111111111111111111111", "message": "补充项目说明和目录", "changes": [ { "action": "UPDATE_FILE", "path": "README.md", "content": "# 社区机器人\n项目说明\n" }, { "action": "CREATE_FILE", "path": "docs/使用说明.md", "content": "使用步骤\n" }, { "action": "CREATE_DIRECTORY", "path": "models" } ] } ``` - CREATE_FILE、UPDATE_FILE 必须传原始文本 `content`,空文件传 `""`,不做 Base64 编码。 - DELETE_FILE、CREATE_DIRECTORY 不需要 content;不支持用 DELETE_FILE 删除整个目录。 - changes 为 1~500 项,同一次提交不能重复修改同一路径。 - message 必填,1~1000 字符;文本单文件最多 1 MiB,提交内容合计最多 50 MiB。 - 成功返回新的 `commitSha` 和 `message`。更新本地工作区 SHA,再刷新目录/文件/历史。 版本冲突返回 409 `CONFLICT`。保留未保存的编辑内容,提示用户刷新并比对差异,不能直接换成最新 SHA 自动覆盖。 ### 6.4 多文件上传(保留目录) `POST /admin-api/projects/{projectCode}/uploads/commit`,`multipart/form-data` → `CommitView`。 | FormData 字段 | 必填 | 说明 | | --- | --- | --- | | expectedCommitSha | 是 | 当前工作区完整 Commit SHA | | message | 是 | 提交说明,1~1000 字符 | | directory | 否 | 上传目标目录,默认根目录空字符串 | | files | 是 | 重复 append 的 File 字段,1~500 个 | | paths | 否 | 重复 append 的相对路径,与 files 数量相同且逐项对应;省略则用原文件名 | 单文件最多 **10 MiB**,一批文件合计最多 **50 MiB**;1 MiB = 1,048,576 字节。同名路径会更新已有文件。上传目录不自动解压 ZIP,超限时让用户减少文件或分批提交,每批使用上次返回的新 SHA。 ```ts interface SelectedFile { file: File; relativePath: string; } async function uploadProjectFiles( projectCode: string, expectedCommitSha: string, message: string, selected: SelectedFile[], directory = '', ): Promise { const form = new FormData(); form.append('expectedCommitSha', expectedCommitSha); form.append('message', message); form.append('directory', directory); for (const item of selected) { form.append('files', item.file, item.file.name); form.append('paths', item.relativePath); } return requestAdmin(`/projects/${projectCode}/uploads/commit`, { method: 'POST', body: form, }); } ``` 例如 `directory="docs"`、`relativePath="images/a.png"`,最终路径为 `docs/images/a.png`;不要再把 `docs/` 拼到 relativePath。文件夹选择可用浏览器 `webkitRelativePath`,前端统一决定是否保留所选根目录名称,并在上传前展示最终路径。 Git 上传携带后台 Authorization;不要手写 multipart Content-Type,浏览器会生成 boundary。上传中禁用重复提交按钮;请求超时先刷新目录和历史确认结果,不自动再发。 ## 7. 封面上传 封面是 **获取签名 → 直接上传 OSS → 保存项目 coverUrl** 三步,不调用 Git 上传接口。 `POST /admin-api/uploads/project-covers/signature` → `CoverUploadSignature`。 ```json { "contentType": "image/png", "fileSize": 125000 } ``` 支持 `image/jpeg`、`image/png`、`image/webp`,fileSize 为实际字节数,必须大于 0,最多 **5 MiB**。 ```ts interface CoverUploadSignature { uploadUrl: string; objectKey: string; coverUrl: string; expiresAt: UtcDateTime; formFields: Record; } ``` 签名默认有效 5 分钟,以 `expiresAt` 为准。`formFields` 全部原样传给 OSS,不自行拼接签名或对象地址。 ```ts async function uploadOssFile( uploadUrl: string, formFields: Record, file: File, ): Promise { const form = new FormData(); for (const [key, value] of Object.entries(formFields)) form.append(key, value); form.append('file', file, file.name); // 文件最后添加 const response = await fetch(uploadUrl, { method: 'POST', body: form }); // 不传后台 Authorization,不手动设置 Content-Type,不解析业务 JSON。 if (!response.ok) throw new Error(`OSS 上传失败(${response.status})`); } async function uploadCover(file: File): Promise { const signature = await requestAdmin('/uploads/project-covers/signature', { method: 'POST', body: { contentType: file.type, fileSize: file.size }, }); await uploadOssFile(signature.uploadUrl, signature.formFields, file); return signature.coverUrl; } ``` 当前签名要求 OSS 成功返回 HTTP 200,使用 `response.ok` 判断即可,无需解析响应体。封面上传成功后,把返回的 coverUrl 放进新建/编辑表单,再提交项目。获取签名不等于上传完成,上传失败应保留原封面;过期重新申请签名。 清空封面时编辑项目传 `coverUrl: ""`。不要将 `objectKey` 当 coverUrl,也不要自行替换域名。若浏览器在直传阶段报跨域错误,将 uploadUrl 和错误信息反馈后端排查 OSS 跨域配置。 ## 8. URDF 目录上传 URDF 为独立资源目录上传,不产生 Git Commit,也不自动从迁移仓库识别绑定。确认或清除绑定会直接更新项目展示资源,不需要额外发布 Commit。 ### 8.1 请求与返回 | 方法和路径 | 请求 | 返回的 data | | --- | --- | --- | | `POST /admin-api/projects/{projectCode}/urdf/signature` | `{ "files": UrdfFile[] }` | `UrdfUploadSignature` | | `PUT /admin-api/projects/{projectCode}/urdf` | `{ "batchCode": "签名返回的批次", "files": UrdfFile[] }` | `ProjectView` | | `DELETE /admin-api/projects/{projectCode}/urdf` | 无 body | `null` | ```ts interface UrdfFile { relativePath: string; sizeBytes: number; } interface UrdfFileSignature { relativePath: string; objectKey: string; formFields: Record; } interface UrdfUploadSignature { batchCode: string; mainRelativePath: string; uploadUrl: string; expiresAt: UtcDateTime; files: UrdfFileSignature[]; } ``` 签名请求示例: ```json { "files": [ { "relativePath": "robot.urdf", "sizeBytes": 2400 }, { "relativePath": "meshes/body.stl", "sizeBytes": 120000 } ] } ``` 文件清单中必须有且仅有一个 `.urdf` 文件(扩展名大小写不敏感),其余是配套 mesh、贴图等资源。sizeBytes 使用 `File.size`,路径不得重复,沿用相对路径规则。 默认上限:单文件 **50 MiB**、总计 **200 MiB**、最多 **500** 个文件,超限返回 413 `URDF_UPLOAD_TOO_LARGE`。实际环境可以调整上限,以服务端校验为准。 ### 8.2 前端步骤 1. 选择包含 URDF 及依赖资源的目录,生成相对路径和实际大小清单。 2. 请求签名,保存返回的 batchCode、mainRelativePath 和每个文件的 formFields。签名默认有效 15 分钟。 3. 每个文件使用其对应 formFields 向 uploadUrl 单独 POST,可复用上一节 `uploadOssFile`;不要根据扩展名重写签名表单中的 Content-Type 字段。 4. 全部上传成功后,PUT 确认 batchCode 及同一份 files 清单。后端检查对象是否存在及大小是否一致。 5. 确认成功后刷新项目,用 urdfMainUrl、urdfBaseUrl 展示资源。 ```ts async function uploadUrdf(projectCode: string, selected: SelectedFile[]): Promise { const files: UrdfFile[] = selected.map(item => ({ relativePath: item.relativePath, sizeBytes: item.file.size, })); const signature = await requestAdmin(`/projects/${projectCode}/urdf/signature`, { method: 'POST', body: { files }, }); const byPath = new Map(selected.map(item => [item.relativePath, item.file])); // 示例串行上传,实际可使用有并发上限的队列。 for (const item of signature.files) { const file = byPath.get(item.relativePath); if (!file) throw new Error(`缺少本地文件:${item.relativePath}`); await uploadOssFile(signature.uploadUrl, item.formFields, file); } return requestAdmin(`/projects/${projectCode}/urdf`, { method: 'PUT', body: { batchCode: signature.batchCode, files }, }); } ``` 任一文件失败时不要确认绑定;保留失败状态并检查上传结果。签名过期可重新申请完整批次;同批次已成功文件禁止覆盖,不要无条件重传。移除 URDF 只清除绑定,不物理删除已上传对象。 ## 9. GitHub 项目迁移 页面流程:**输入地址 → 预检 → 补充项目信息 → 创建任务 → 查看阶段 → 检查文件 → 手动发布**。 ### 9.1 预检 `POST /admin-api/project-imports/preview` → `ImportPreview`。 ```json { "repositoryUrl": "https://github.com/JorgeEspiau/argos-robot" } ``` 只接受 HTTPS 公开 GitHub 仓库根地址,例如 `https://github.com/owner/repo`,允许末尾 `.git`。不接受 SSH、私有仓库、其他平台、`/tree/...`、`/blob/...`、查询参数或片段。repositoryUrl 必填,最多 2048 字符。 ```ts interface ImportPreview { repositoryUrl: string; defaultBranch: string; name: string; description: string; license: string | null; existingProjectCode: string | null; } ``` 预检不创建项目或任务。用返回的 repositoryUrl 作为规范来源;name、description 填入可编辑表单,再选择 projectType、封面和归属。许可证可能未取得,应显示“未识别”,不要视为空许可或默认开源授权。 existingProjectCode 非 null 时提示“已存在项目”,提供进入现有项目详情的入口,不重复创建。预检通过也不保证创建必然成功,创建时仍会重新校验来源和重复记录。 ### 9.2 创建任务 `POST /admin-api/project-imports` → **HTTP 202**,data 为 `TaskView`。 ```json { "repositoryUrl": "https://github.com/JorgeEspiau/argos-robot", "project": { "name": "Argos Robot", "description": "待管理员检查的迁移项目", "projectType": "WHEELED", "coverUrl": null } } ``` ownerUserCode 可选,放在最外层,规则同新建项目。project 字段与普通创建一致;许可证、默认分支不通过创建 body 修改。点击创建时禁用重复提交按钮,收到 202 后进入任务详情页。**202 表示已受理,不是迁移完成。** ```ts type ImportStatus = 'QUEUED' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'REVIEW'; type ImportPhase = 'QUEUED' | 'PRECHECK' | 'MIGRATING' | 'MIGRATED' | 'NORMALIZING' | 'BRANCH_READY' | 'LINKED'; interface TaskView { taskCode: string; projectCode: string; status: ImportStatus; phase: ImportPhase; errorCode: string | null; warnings: string[]; createdAt: UtcDateTime; startedAt: UtcDateTime | null; finishedAt: UtcDateTime | null; } ``` 任务响应示例: ```json { "code": "OK", "message": "成功", "data": { "taskCode": "aabbccddeeff00112233445566778899", "projectCode": "0123456789abcdef0123456789abcdef", "status": "QUEUED", "phase": "QUEUED", "errorCode": null, "warnings": [], "createdAt": "2026-10-20T02:30:00", "startedAt": null, "finishedAt": null }, "requestId": "e27eaa6c4cd94df582c0588d2a851e69" } ``` ### 9.3 任务列表、详情与重试 | 方法和路径 | 请求 | 返回的 data | | --- | --- | --- | | `GET /admin-api/project-imports` | Query:page、size、status、projectCode,可选 | `PageResponse` | | `GET /admin-api/project-imports/{taskCode}` | 无 | `TaskView` | | `POST /admin-api/project-imports/{taskCode}/retry` | 无 body | HTTP 202,`TaskView` | 状态决定页面行为,阶段用于文字说明: | status | 建议文案 | 前端行为 | | --- | --- | --- | | QUEUED | 排队中 | 持续轮询,不重复提交 | | RUNNING | 迁移中 | 持续轮询,展示阶段和 warnings | | SUCCEEDED | 迁移完成,待检查发布 | 停止轮询,跳转项目检查;不会自动发布 | | FAILED | 迁移失败 | 停止轮询,展示 errorCode、warnings,可由用户点击重试 | | REVIEW | 结果待核对 | 停止轮询,提示联系维护人员,不自动重试 | | phase | 建议文案 | | --- | --- | | QUEUED | 等待处理 | | PRECHECK | 校验来源和项目信息 | | MIGRATING | 迁移 Git 仓库与 LFS | | MIGRATED | 仓库迁移已确认 | | NORMALIZING | 适配社区主分支 | | BRANCH_READY | 主分支已准备 | | LINKED | 已关联社区项目 | 不展示百分比进度,接口没有 progress、duration、canRetry 字段。耗时可根据 startedAt、finishedAt 计算,空值显示 `—`。任务查询 HTTP 200、code=OK 只表示查询成功,必须再判断 data.status 是否失败或待核对。 ### 9.4 轮询示例 建议约 3 秒轮询一次,等待上次请求完成再发下次;离开页面、退出或遇到终态时停止。网络异常显示“获取状态失败”,允许恢复查询,不能把查询失败当作迁移失败。 ```ts function sleepForPoll(ms: number, signal: AbortSignal): Promise { return new Promise((resolve, reject) => { if (signal.aborted) { reject(new DOMException('Aborted', 'AbortError')); return; } const onAbort = () => { clearTimeout(timer); reject(new DOMException('Aborted', 'AbortError')); }; const timer = setTimeout(() => { signal.removeEventListener('abort', onAbort); resolve(); }, ms); signal.addEventListener('abort', onAbort, { once: true }); }); } async function watchImport( taskCode: string, signal: AbortSignal, onUpdate: (task: TaskView) => void, ): Promise { for (;;) { const task = await requestAdmin(`/project-imports/${taskCode}`, { signal }); onUpdate(task); if (task.status !== 'QUEUED' && task.status !== 'RUNNING') return task; await sleepForPoll(3000, signal); } } // 页面挂载时创建 AbortController,并将 signal 传入 watchImport。 // 页面卸载时调用 controller.abort();捕获 AbortError 后不弹错误提示。 ``` ### 9.5 重试和功能边界 - FAILED 点击重试后,按返回任务恢复轮询;后端拒绝时显示 409 message,不循环重发。 - REVIEW 可能涉及远端结果不明,需要维护人员核对。部分已确认阶段支持同一 retry 接口安全续跑,但判断所需信息不对前端暴露;默认不显示常规重试按钮,也不要只根据 phase 推断可重试。 - 重复来源可能返回 409 `DUPLICATE_SOURCE`,错误 data 中的 projectCode 可用于跳转现有项目。不要改项目名或重新预检后循环创建。 - 没有取消任务、强行成功、删除目标仓库、定期同步源仓库的接口。 - 迁移保留 Git 历史、分支、标签并迁移 LFS;不迁移 Issue、PR、Wiki、Release 附件,不递归复制子模块依赖。保留分支不代表后台可切换分支。 - 原默认分支非 main 时进行适配;已有 main 内容冲突会停止,前端展示任务错误和提醒即可。 - 成功后项目仍未发布;需要管理员查看文件并手动发布。封面和 URDF 需要按前面流程单独上传/绑定。 ## 10. 错误处理 | HTTP / code | 前端处理 | | --- | --- | | 400 BAD_REQUEST | 按 message 修正表单、路径或参数,不自动重发 | | 400 PASSWORD_INVALID | 提示原密码不正确,保留修改密码页面 | | 400 URDF_MAIN_FILE_INVALID | URDF 清单没有主文件或存在多个主文件,要求重新选择 | | 400 URDF_FILE_SIZE_MISMATCH | 实际上传大小不符,检查文件清单和上传结果 | | 401 ADMIN_LOGIN_FAILED | 登录页提示账号或密码错误 | | 401 UNAUTHORIZED | 清除后台会话并回登录页;保留合理的返回路径 | | 403 FORBIDDEN / OPERATOR_UNAVAILABLE | 提示无权限或任务操作人已失去权限,不继续写入 | | 404 NOT_FOUND | 资源不存在或已删除,刷新列表/返回上级 | | 409 CONFLICT / GITEA_CONFLICT | 版本或状态冲突,刷新并由用户重新确认;保留未保存内容 | | 409 PROJECT_BUSY | 项目正在执行其他写操作,稍后刷新状态 | | 409 PROJECT_BLOCKED | 项目被管理员下架,刷新详情,不继续发布 | | 409 DUPLICATE_SOURCE | 使用错误 data.projectCode 引导查看已有项目 | | REMOTE_RESULT_UNKNOWN(状态码以响应为准) | 写入结果待核对,停止重复提交,展示 requestId | | 413 FILE_TOO_LARGE / UPLOAD_TOO_LARGE / URDF_UPLOAD_TOO_LARGE | 检查对应上传类型限额,拆批或减少文件 | | 429 ADMIN_LOGIN_LIMITED | 提示 15 分钟后重试,不循环发登录请求 | | 503 OSS_UNAVAILABLE | 暂停上传入口并提示当前环境未开放上传 | | 503 PROJECT_LOCK_UNAVAILABLE / PROJECT_LOCK_INTERRUPTED | 暂停写入并刷新,必要时联系后端核对 | | 502 / 504,上游错误或 GITHUB_UNAVAILABLE | 展示 message/requestId;写操作先查状态,禁止盲目重试 | | 其他错误 | 展示后端 message 和 requestId,保留用户输入,不假定操作已成功 | 浏览器超时、断网、AbortError 都不证明服务端已停止处理。创建项目、上传、提交、发布、创建迁移任务等有副作用操作,恢复网络后先刷新详情、目录/历史或任务列表确认结果,再由用户决定下一步。不要在请求库对这些接口统一启用自动重试。 requestId 同时可能出现在响应头 `X-Request-Id`。错误提示可附“请求编号”,方便向后端反馈;不向用户展示堆栈或完整请求内容。 ## 11. 页面调用顺序与联调检查 ### 11.1 页面与接口对应 | 页面 | 主要调用顺序 | | --- | --- | | 登录页 | login → 保存后台 Token → me/进入首页 | | 用户列表 | users 分页筛选 → 编辑昵称/启停 → 刷新当前列表 | | 用户详情 | users/{userCode} + users/{userCode}/projects | | 项目列表 | projects/types + projects 分页筛选 | | 新建项目 | types + 可选用户搜索 → 可选上传封面 → POST projects → 进入详情 | | 项目详情 | GET projects/{projectCode} → repo READY 时读取 tree、commits | | 文件编辑/上传 | 取得当前 SHA → 提交或上传 → 保存新 SHA → 刷新目录和历史 | | 发布确认 | 读取并检查当前 main 文件 → PUT publication → 刷新详情 | | URDF 设置 | 选目录 → signature → 逐文件 OSS 上传 → PUT urdf → 刷新详情 | | 迁移创建 | preview → 补充表单 → POST project-imports → 进入任务页 | | 迁移任务 | 详情轮询 → SUCCEEDED 后检查项目 → 明确发布 | ### 11.2 联调重点 - 普通用户无法后台登录;社区 Token 无法调用后台;后台 401 能返回登录页。 - 修改密码后需要重新登录;禁用用户时旧会话失效;不能禁用自己及官方账号。 - 列表读取 items;管理项目列表读取 item.project;创建和编辑读取平铺 ProjectView。 - 新建默认官方归属;选择用户仅限正常 USER;名称、类型及描述长度校验准确。 - 封面、Git 文件、URDF 三种上传流程和限额区分正确,FormData 没有手写 boundary。 - 文件夹上传路径符合预览;提交成功更新 SHA;冲突保留输入,不覆盖他人版本。 - 上传或编辑文件后不自动发布;已发布版本与工作区最新 SHA 分开展示。 - 下架后不能发布;解除下架后仍需手动发布。 - 迁移 202 显示已受理;终态停止轮询;不把 FAILED/REVIEW 显示为成功。 - 重复来源提供现有项目入口;任务失败、超时及待核对不自动重建迁移任务。