Files
community/docs/admin-api.md
T

44 KiB
Raw Blame History

Community 管理后台前端接口文档

适用模块:community-adminapi。本文按当前后端实现整理,可直接用于后台页面开发和联调。接口均已包含 /admin-api 前缀;示例数据仅用于说明字段结构。

部署、管理员初始化及服务配置见 部署说明,前端对接无需执行数据库操作。

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 <token>
请求格式 默认 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. 通用响应和请求封装

2.1 响应结构

成功响应:

{
  "code": "OK",
  "message": "成功",
  "data": null,
  "requestId": "e27eaa6c4cd94df582c0588d2a851e69"
}

错误响应示例(HTTP 409):

{
  "code": "CONFLICT",
  "message": "工作区版本已变化,请刷新后重新提交",
  "data": null,
  "requestId": "e27eaa6c4cd94df582c0588d2a851e69"
}

错误的 data 通常为 null,部分错误包含辅助信息,例如重复迁移返回 { "projectCode": "已有项目编码" }。错误提示优先使用 message,同时保留 code 和 requestId 供排查。

  • 普通成功返回 HTTP 200;创建、重试迁移任务返回 202,code 同样为 OK。
  • 没有业务返回值的操作也返回上述 JSON,data: null,不是空响应。
  • 文件下载成功返回二进制;OSS 直传返回 OSS 自身响应。这两种请求不要经过普通 JSON 解包逻辑。

分页示例:

{
  "code": "OK",
  "message": "成功",
  "data": {
    "items": [],
    "page": 1,
    "size": 20,
    "total": 0
  },
  "requestId": "e27eaa6c4cd94df582c0588d2a851e69"
}

分页列表字段是 items,不是 records、list 或 rows。 筛选条件为空时省略参数,尤其不要发送 role=、status= 等空枚举。

2.2 时间和公共类型

type UtcDateTime = string;

interface ApiResponse<T> {
  code: string;
  message: string;
  data: T;
  requestId: string | null;
}

interface PageResponse<T> {
  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 或时区偏移。

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 接到自己的登录状态管理即可。

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<T>(path: string, options: AdminRequestOptions = {}): Promise<T> {
  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<T> | 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, string | number | null | undefined>): 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 清空后台登录状态并返回登录页。不要给写请求配置自动重试,详情见 错误处理。

3. 登录与账号

3.1 类型

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 字节
{
  "email": "admin@example.com",
  "password": "ExamplePassword123!"
}

成功响应示例:

{
  "code": "OK",
  "message": "成功",
  "data": {
    "token": "<登录成功后返回的随机Token>",
    "tokenType": "Bearer",
    "expiresIn": 28800,
    "admin": {
      "userCode": "a1b2c3d4e5f6",
      "email": "admin@example.com",
      "nickname": "社区管理员",
      "role": "ADMIN"
    }
  },
  "requestId": "e27eaa6c4cd94df582c0588d2a851e69"
}
async function login(email: string, password: string): Promise<AdminView> {
  const result = await requestAdmin<LoginView>('/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 用户字段

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<UserView>。

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<ManagedProjectView>
  • 禁止禁用当前登录管理员及官方账号;前端隐藏或禁用对应按钮,后端也会校验并返回 409。
  • 禁用立即使原会话失效;重新启用后用户仍需重新登录。
  • 禁用不会自动下架其项目;项目下架需要单独操作。
  • 用户编辑只支持昵称,没有删除用户、修改邮箱、修改角色、转移项目接口。

5. 项目管理

5.1 项目字段

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:

[
  { "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<ManagedProjectView>。

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:

{
  "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:

{
  "project": {
    "name": "社区机器人",
    "description": "项目说明",
    "projectType": "WHEELED",
    "coverUrl": null
  }
}

指定归属时在最外层加 ownerUserCode。成功后项目保持未发布,可直接进入详情页上传文件。

PATCH /admin-api/projects/{projectCode} → ProjectView,body 为平铺的项目信息:

{
  "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 类型及路径规则

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<HistoryEntry>

不传 commitSha 时读取当前 main。需要一致地浏览某次快照时,后续目录和文件请求都带上首次取得的 commitSha。

async function readProjectFile(projectCode: string, path: string, commitSha?: string): Promise<FileView> {
  return requestAdmin<FileView>(
    `/projects/${projectCode}/files${queryString({ path, commitSha })}`,
  );
}

encoding=utf-8 且 editable=true 才开放文本编辑;base64 代表原始文件内容的 Base64,可按文件类型预览或下载,不能直接当文本提交。在线文本上限默认 1 MiB。符号链接、子模块不支持按普通文件读取,迁移仓库中的 LFS 文件也不保证能在线预览。

下载使用携带后台 Authorization 的 fetch,成功后 response.blob(),从 Content-Disposition 获取文件名并触发保存。不要把 Token 拼到 URL,也不要直接用不带鉴权的 <a href> 下载。下载失败仍可能是 JSON 错误,应先判断 HTTP 状态。

6.3 在线文本、多文件变更

POST /admin-api/projects/{projectCode}/commits → CommitView。

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[];
}
{
  "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。

interface SelectedFile {
  file: File;
  relativePath: string;
}

async function uploadProjectFiles(
  projectCode: string,
  expectedCommitSha: string,
  message: string,
  selected: SelectedFile[],
  directory = '',
): Promise<CommitView> {
  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<CommitView>(`/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。

{
  "contentType": "image/png",
  "fileSize": 125000
}

支持 image/jpeg、image/png、image/webp,fileSize 为实际字节数,必须大于 0,最多 5 MiB。

interface CoverUploadSignature {
  uploadUrl: string;
  objectKey: string;
  coverUrl: string;
  expiresAt: UtcDateTime;
  formFields: Record<string, string>;
}

签名默认有效 5 分钟,以 expiresAt 为准。formFields 全部原样传给 OSS,不自行拼接签名或对象地址。

async function uploadOssFile(
  uploadUrl: string,
  formFields: Record<string, string>,
  file: File,
): Promise<void> {
  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<string> {
  const signature = await requestAdmin<CoverUploadSignature>('/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
interface UrdfFile {
  relativePath: string;
  sizeBytes: number;
}
interface UrdfFileSignature {
  relativePath: string;
  objectKey: string;
  formFields: Record<string, string>;
}
interface UrdfUploadSignature {
  batchCode: string;
  mainRelativePath: string;
  uploadUrl: string;
  expiresAt: UtcDateTime;
  files: UrdfFileSignature[];
}

签名请求示例:

{
  "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 展示资源。
async function uploadUrdf(projectCode: string, selected: SelectedFile[]): Promise<ProjectView> {
  const files: UrdfFile[] = selected.map(item => ({
    relativePath: item.relativePath, sizeBytes: item.file.size,
  }));
  const signature = await requestAdmin<UrdfUploadSignature>(`/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<ProjectView>(`/projects/${projectCode}/urdf`, {
    method: 'PUT', body: { batchCode: signature.batchCode, files },
  });
}

任一文件失败时不要确认绑定;保留失败状态并检查上传结果。签名过期可重新申请完整批次;同批次已成功文件禁止覆盖,不要无条件重传。移除 URDF 只清除绑定,不物理删除已上传对象。

9. GitHub 项目迁移

页面流程:输入地址 → 预检 → 补充信息、可选上传封面和 URDF → 创建任务并绑定资源 → 查看阶段 → 检查文件 → 手动发布。封面和 URDF 均可在迁移表单内完成,无需等迁移后再去项目列表寻找项目。

9.1 预检

POST /admin-api/project-imports/preview → ImportPreview。

{
  "repositoryUrl": "https://github.com/JorgeEspiau/argos-robot"
}

只接受 HTTPS 公开 GitHub 仓库根地址,例如 https://github.com/owner/repo,允许末尾 .git。不接受 SSH、私有仓库、其他平台、/tree/...、/blob/...、查询参数或片段。repositoryUrl 必填,最多 2048 字符。

interface ImportPreview {
  repositoryUrl: string;
  defaultBranch: string;
  name: string;
  description: string;
  license: string | null;
  existingProjectCode: string | null;
}

预检不创建项目或任务。用返回的 repositoryUrl 作为规范来源;name、description 填入可编辑表单,再选择 projectType、封面和归属。许可证可能未取得,应显示“未识别”,不要视为空许可或默认开源授权。

existingProjectCode 非 null 时提示“已存在项目”,提供进入现有项目详情的入口,不重复创建。预检通过也不保证创建必然成功,创建时仍会重新校验来源和重复记录。

9.2 迁移表单上传封面和 URDF(可选)

封面继续使用第 7 节的签名和 OSS 直传流程,把上传成功后返回的 coverUrl 放入 project.coverUrl。

URDF 使用专门的迁移前签名接口:POST /admin-api/project-imports/urdf/signature → UrdfUploadSignature(返回字段同第 8 节)。此时无需 projectCode,也不创建项目或迁移任务。

{
  "repositoryUrl": "https://github.com/JorgeEspiau/argos-robot",
  "files": [
    { "relativePath": "robot.urdf", "sizeBytes": 2400 },
    { "relativePath": "meshes/body.stl", "sizeBytes": 120000 }
  ]
}
请求字段 必填 说明
repositoryUrl 是 与创建迁移任务相同的 GitHub 来源,规则同预检
files 是 同第 8 节 UrdfFile[],有且仅有一个 .urdf;大小、数量、路径限制一致

前端调用顺序:

  1. 预检通过后,在当前迁移表单选择 URDF 目录,生成文件清单。
  2. 申请上述签名,使用每个文件对应的 formFields 直传 OSS;可复用 uploadOssFile。
  3. 全部文件上传成功后,保存 batchCode 和同一份文件清单,作为创建任务 body 的可选 urdf 字段。
  4. 创建任务时后端核验文件存在及大小,并将 URDF 与项目、任务一并保存;不再调用项目的 PUT urdf 接口。
interface ImportInput {
  repositoryUrl: string;
  ownerUserCode?: string;
  project: ProjectInput;
  urdf?: { batchCode: string; files: UrdfFile[] } | null;
}

async function uploadImportUrdf(
  repositoryUrl: string,
  selected: SelectedFile[],
): Promise<{ batchCode: string; files: UrdfFile[] }> {
  const files = selected.map(item => ({
    relativePath: item.relativePath, sizeBytes: item.file.size,
  }));
  const signature = await requestAdmin<UrdfUploadSignature>('/project-imports/urdf/signature', {
    method: 'POST', body: { repositoryUrl, 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 { batchCode: signature.batchCode, files };
}

不上传 URDF 时省略 urdf 或传 null,原有迁移请求保持兼容。若用户已选择 URDF,上传失败时应保留表单并提示,不能静默移除 URDF 后创建任务。

签名与 GitHub 来源绑定;上传后改为另一个仓库,需要重新申请该仓库的签名并上传。来源更名时按 GitHub 稳定身份重新核对。任务创建失败且尚未创建项目时,已上传的同一来源批次可保留用于用户确认后的再次提交,不必覆盖重传文件;查询到 DUPLICATE_SOURCE 则进入已有项目核对,不再重建任务。

9.3 创建任务

POST /admin-api/project-imports → HTTP 202,data 为 TaskView。

{
  "repositoryUrl": "https://github.com/JorgeEspiau/argos-robot",
  "project": {
    "name": "Argos Robot",
    "description": "待管理员检查的迁移项目",
    "projectType": "WHEELED",
    "coverUrl": null
  },
  "urdf": {
    "batchCode": "aabbccddeeff00112233445566778899",
    "files": [
      { "relativePath": "robot.urdf", "sizeBytes": 2400 },
      { "relativePath": "meshes/body.stl", "sizeBytes": 120000 }
    ]
  }
}

ownerUserCode、urdf 可选,均放在最外层;归属规则同新建项目。示例 batchCode 必须替换为本次实际上传返回值,files 使用上传时的原清单;封面上传后把 coverUrl 替换为实际返回地址。project 字段与普通创建一致;许可证、默认分支不通过创建 body 修改。

URDF 缺失或大小不符时拒绝创建,不留下项目和任务。收到 202 表示任务已受理,传入的 URDF 已绑定到目标项目;Git 仓库仍在后台迁移,不表示迁移完成,也不会自动发布。点击创建时禁用重复提交按钮,成功后进入任务详情页。

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;
}

任务响应示例:

{
  "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.4 任务列表、详情与重试

方法和路径 请求 返回的 data
GET /admin-api/project-imports Query:page、size、status、projectCode,可选 PageResponse<TaskView>
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.5 轮询示例

建议约 3 秒轮询一次,等待上次请求完成再发下次;离开页面、退出或遇到终态时停止。网络异常显示“获取状态失败”,允许恢复查询,不能把查询失败当作迁移失败。

function sleepForPoll(ms: number, signal: AbortSignal): Promise<void> {
  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<TaskView> {
  for (;;) {
    const task = await requestAdmin<TaskView>(`/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.6 重试和功能边界

  • FAILED 点击重试后,按返回任务恢复轮询;后端拒绝时显示 409 message,不循环重发。
  • REVIEW 可能涉及远端结果不明,需要维护人员核对。部分已确认阶段支持同一 retry 接口安全续跑,但判断所需信息不对前端暴露;默认不显示常规重试按钮,也不要只根据 phase 推断可重试。
  • 重复来源可能返回 409 DUPLICATE_SOURCE,错误 data 中的 projectCode 可用于跳转现有项目。不要改项目名或重新预检后循环创建。
  • 没有取消任务、强行成功、删除目标仓库、定期同步源仓库的接口。
  • 迁移保留 Git 历史、分支、标签并迁移 LFS;不迁移 Issue、PR、Wiki、Release 附件,不递归复制子模块依赖。保留分支不代表后台可切换分支。
  • 原默认分支非 main 时进行适配;已有 main 内容冲突会停止,前端展示任务错误和提醒即可。
  • 成功后项目仍未发布;需要管理员查看文件并手动发布。迁移表单已提交的封面和 URDF 会保留,无需再次绑定;后续替换资源仍可使用普通项目接口。不会自动扫描 Git 仓库中的 URDF 并绑定。

10. 错误处理

HTTP / code 前端处理
400 BAD_REQUEST 按 message 修正表单、路径或参数,不自动重发
400 PASSWORD_INVALID 提示原密码不正确,保留修改密码页面
400 URDF_MAIN_FILE_INVALID URDF 清单没有主文件或存在多个主文件,要求重新选择
400 URDF_FILE_MISSING 文件尚未上传完整或批次与来源不匹配,检查上传结果及来源
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 → 补充表单 → 可选封面及迁移 URDF 签名/OSS 上传 → POST project-imports(含 urdf)→ 进入任务页
迁移任务 详情轮询 → SUCCEEDED 后检查项目 → 明确发布

11.2 联调重点

  • 普通用户无法后台登录;社区 Token 无法调用后台;后台 401 能返回登录页。
  • 修改密码后需要重新登录;禁用用户时旧会话失效;不能禁用自己及官方账号。
  • 列表读取 items;管理项目列表读取 item.project;创建和编辑读取平铺 ProjectView。
  • 新建默认官方归属;选择用户仅限正常 USER;名称、类型及描述长度校验准确。
  • 封面、Git 文件、URDF 三种上传流程和限额区分正确,FormData 没有手写 boundary。
  • 文件夹上传路径符合预览;提交成功更新 SHA;冲突保留输入,不覆盖他人版本。
  • 上传或编辑文件后不自动发布;已发布版本与工作区最新 SHA 分开展示。
  • 下架后不能发布;解除下架后仍需手动发布。
  • 迁移 202 显示已受理;终态停止轮询;不把 FAILED/REVIEW 显示为成功。
  • 在迁移表单上传封面和 URDF 后即可创建任务;不必等待仓库 READY 再绑定 URDF;未完整上传时不能创建任务。
  • 重复来源提供现有项目入口;任务失败、超时及待核对不自动重建迁移任务。