1293 lines
65 KiB
Markdown
1293 lines
65 KiB
Markdown
# Vibemake 管理后台前端接口文档
|
||
|
||
适用模块:`vibemake-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 <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-通用响应和请求封装)
|
||
- [登录与账号](#3-登录与账号)
|
||
- [用户管理](#4-用户管理)
|
||
- [项目管理](#5-项目管理)
|
||
- [目录文件与提交](#6-目录文件与提交)
|
||
- [封面上传](#7-封面上传)
|
||
- [URDF 目录上传](#8-urdf-目录上传)
|
||
- [STEP 单文件上传](#84-step-单文件上传)
|
||
- [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 ShanghaiDateTime = 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` 为上海时间(`Asia/Shanghai`,UTC+8)字符串,例如 `2026-10-20T10:30:00.123`,当前没有时区后缀。前端应补充 `+08:00` 后解析,再格式化为用户本地时间;不能继续补 `Z`,也不能依赖浏览器默认时区。前后端需同时切换时间约定,避免多显示 8 小时。提交历史的 `authorDate` 沿用 Git 日期,可能自带 `Z` 或时区偏移。
|
||
|
||
```ts
|
||
function parseServerTime(value: string): Date {
|
||
return new Date(/(?:Z|[+-]\d{2}:?\d{2})$/i.test(value) ? value : `${value}+08:00`);
|
||
}
|
||
```
|
||
|
||
STEP 上传签名的 `expiresAt` 已包含 UTC 时区后缀 `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<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 清空后台登录状态并返回登录页。不要给写请求配置自动重试,详情见 [错误处理](#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<AdminView> {
|
||
const result = await requestAdmin<LoginView>('/auth/login', {
|
||
method: 'POST', anonymous: true, body: { email, password },
|
||
});
|
||
adminToken = result.token;
|
||
return result.admin;
|
||
}
|
||
```
|
||
|
||
后台只允许正常的 `ADMIN` 登录。普通用户、官方账号、禁用账号、密码错误均不能登录,不根据失败文案判断账号是否存在。连续失败会触发 429,提示 15 分钟后重试。
|
||
|
||
同一 `ADMIN` 账号也可通过社区 `/api/auth/login` 登录前台,只提交邮箱和图片验证码,无需密码;后台登录仍须提交邮箱和密码。社区与后台独立保存 Token,不能混用;在社区工作区仍只能操作自己的项目。修改后台密码或禁用账号会使该账号两端旧会话失效。前台请求字段见[邮箱登录](vibemake-api.md#邮箱登录)。
|
||
|
||
会话默认 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: ShanghaiDateTime;
|
||
}
|
||
```
|
||
|
||
展示文案:`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 项目字段
|
||
|
||
```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;
|
||
stepMainUrl: string | null;
|
||
stepFileName: string | null;
|
||
stepSizeBytes: number | null;
|
||
modelGlbUrl: string | null;
|
||
modelPartsBaseUrl: string | null;
|
||
modelPartsFiles?: ResourceFileView[]; // 详情返回;列表省略
|
||
assemblyJsonUrl: string | null;
|
||
walkingResourcesBaseUrl: string | null;
|
||
walkingResourcesFiles?: ResourceFileView[]; // 详情返回;列表省略
|
||
projectType: string;
|
||
owner: { userCode: string | null; nickname: string };
|
||
repoStatus: RepoStatus;
|
||
publishStatus: PublishStatus;
|
||
publishedCommitSha: string | null;
|
||
publishedAt: ShanghaiDateTime | null; // 后台可编辑;发布时仅在为空时填充
|
||
sourceProjectCode: string | null;
|
||
sourceCommitSha: string | null;
|
||
likeCount: number;
|
||
commentCount: number;
|
||
liked: boolean;
|
||
sourceRepositoryUrl: string | null;
|
||
sourceLicense: string | null;
|
||
createdAt: ShanghaiDateTime;
|
||
updatedAt: ShanghaiDateTime;
|
||
}
|
||
|
||
interface ManagedProjectView {
|
||
project: ProjectView;
|
||
moderationStatus: 'NORMAL' | 'BLOCKED';
|
||
moderationReason: string | null;
|
||
deleted: boolean;
|
||
}
|
||
|
||
interface ResourceFileView {
|
||
relativePath: string;
|
||
sizeBytes: number;
|
||
url: string;
|
||
}
|
||
|
||
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 |
|
||
| stepMainUrl / stepFileName / stepSizeBytes | 当前 STEP 公开下载地址、原始文件名和实际字节数;未绑定三个字段均为 null,Fork 继承同一对象引用 |
|
||
| 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<ManagedProjectView>`。
|
||
|
||
| Query 参数 | 说明 |
|
||
| --- | --- |
|
||
| page / size | 通用分页 |
|
||
| ownerUserCode | 按所有者编码精确筛选 |
|
||
| type | 项目类型编码 |
|
||
| keyword | 名称或描述模糊搜索,最多 254 字符 |
|
||
| publishStatus | UNPUBLISHED / PUBLISHED / BLOCKED |
|
||
| repoStatus | CREATING / READY / FAILED |
|
||
| moderationStatus | NORMAL / BLOCKED |
|
||
| sort | 可选:`CREATED_AT_DESC`(默认)、`PUBLISHED_AT_DESC`、`RESOURCES_FIRST`;其他值返回 400 |
|
||
|
||
结果只包含未删除项目。排序模式:
|
||
|
||
| sort | 排序规则 |
|
||
| --- | --- |
|
||
| CREATED_AT_DESC | 创建时间倒序 |
|
||
| PUBLISHED_AT_DESC | 发布时间倒序,NULL 排最后 |
|
||
| RESOURCES_FIRST | 四项资源齐全的项目优先,各组内按发布时间倒序,组内 NULL 排最后 |
|
||
|
||
资源齐全指 `model_glb_object_key`、`assembly_json_object_key`、`walking_resources_prefix`、`model_parts_prefix` 全部非 NULL 且非空字符串。`RESOURCES_FIRST` 下,资源齐全但无发布时间的项目仍排在资源不齐全的项目前面。各模式同值时均有固定顺序,先排序再分页。没有 `creationSource` 筛选,也没有已删除项目回收站。
|
||
|
||
请求示例:`GET /admin-api/projects?page=1&size=20&sort=RESOURCES_FIRST`;仅按发布时间排序使用 `sort=PUBLISHED_AT_DESC`。
|
||
|
||
`GET /admin-api/projects/{projectCode}` → `ManagedProjectView`,示例 data:
|
||
|
||
```json
|
||
{
|
||
"project": {
|
||
"projectCode": "b2c3d4e5f6a7",
|
||
"name": "社区机器人",
|
||
"description": "项目说明",
|
||
"coverUrl": null,
|
||
"urdfMainUrl": null,
|
||
"urdfBaseUrl": null,
|
||
"stepMainUrl": null,
|
||
"stepFileName": null,
|
||
"stepSizeBytes": null,
|
||
"modelGlbUrl": null,
|
||
"modelPartsBaseUrl": null,
|
||
"modelPartsFiles": [],
|
||
"assemblyJsonUrl": null,
|
||
"walkingResourcesBaseUrl": null,
|
||
"walkingResourcesFiles": [],
|
||
"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": "",
|
||
"publishedAt": "2026-11-02T10:30:00.000"
|
||
}
|
||
```
|
||
|
||
| 字段 | 校验及编辑行为 |
|
||
| --- | --- |
|
||
| name | 必填,非空白,最多 100 字符 |
|
||
| description | 最多 2000 字符;省略或 null 会保存为空字符串 |
|
||
| projectType | 必填,来自类型接口,最多 64 字符 |
|
||
| coverUrl | 可空,HTTPS 地址最多 2048 字符;编辑时省略/null 保留旧封面,传 `""` 清空 |
|
||
| publishedAt | 可选,上海时间字符串,无时区后缀;省略保留原值,传 `null` 清空,传时间字符串更新;格式错误返回 400 |
|
||
|
||
虽然方法为 PATCH,**name、projectType 仍必须传**。编辑表单应提交当前完整基础信息,避免只传一个字段或意外清空 description。基础信息保存后直接生效;发布 Commit 主要固定 Git 文件版本。
|
||
|
||
`publishedAt` 复用现有发布时间字段,仅后台允许编辑。清空时提交 `"publishedAt": null`,修改后直接影响列表排序,不改变项目发布状态或已发布文件版本。
|
||
|
||
`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 再发。
|
||
|
||
文件提交不会自动更新社区已发布版本。已发布项目可以继续编辑文件,明确再次发布后才更新公开文件快照。
|
||
|
||
发布时仅在 `publishedAt` 为空时填入当前上海时间;已有值(包括管理员手动设置的时间)会保留。管理员清空后,下次发布会重新填充当前时间。
|
||
|
||
| 状态 | 建议操作 |
|
||
| --- | --- |
|
||
| 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<HistoryEntry>` |
|
||
|
||
不传 `commitSha` 时读取当前 main。需要一致地浏览某次快照时,后续目录和文件请求都带上首次取得的 `commitSha`。
|
||
|
||
```ts
|
||
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 文件也不保证能在线预览。
|
||
|
||
JSON 文件预览默认最大 50 MiB;`download=true` 使用独立流式下载,默认最大 **1 GiB**,由 `FILE_DOWNLOAD_MAX_BYTES` 配置,上游处理和读取总预算默认 **5 分钟**,由 `FILE_DOWNLOAD_TIMEOUT` 配置。下载按请求受理时的完整 SHA 固定版本,仍支持 `commitSha`。空文件可下载,LFS 指针按仓库原文返回,不展开实体。
|
||
|
||
下载使用携带后台 Authorization 的 `fetch`,成功后 `response.blob()`,从 `Content-Disposition` 获取 UTF-8 文件名并触发保存。成功为 `application/octet-stream`,带 `Content-Length`、`Cache-Control: no-store` 和 `X-Request-Id`。不要把 Token 拼到 URL,也不要直接用不带鉴权的 `<a href>` 下载。客户端超时建议至少预留 **400 秒**,可提供取消操作。
|
||
|
||
下载沿用文件读取限流及 `FILE_MAX_CONCURRENT` 名额,名额持有到传输结束;超限为 `413 FILE_TOO_LARGE`,超时为 `504 FILE_DOWNLOAD_TIMEOUT`。发包前失败返回 JSON,应先判断 HTTP 状态;传输开始后失败会直接停止响应,可能仍是 HTTP 200,不会在文件尾部追加 JSON。网络错误、取消或长度不符时丢弃残缺文件,由用户手动重试;不提供 Range 断点续传。
|
||
|
||
### 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,提交内容合计最多 200 MiB;整个 JSON 请求另受 64 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 数量相同且逐项对应;省略则用原文件名 |
|
||
|
||
单文件最多 **50 MiB**,一批文件合计最多 **200 MiB**,最多 **500 个文件**;1 MiB = 1,048,576 字节。同名路径会更新已有文件。上传目录不自动解压 ZIP,超限时让用户减少文件或分批提交,每批使用上次返回的新 SHA。
|
||
|
||
multipart 整个请求最多 **202 MiB**,其中预留 2 MiB 表单开销;表单项上限为 **1003**(500 个 files、500 个 paths、3 个公共字段)。不要为每个文件额外添加其他表单项。表单项数量超限返回 413 `UPLOAD_TOO_MANY_PARTS`,大小超限返回 `UPLOAD_TOO_LARGE` 或 `FILE_TOO_LARGE`。
|
||
|
||
```ts
|
||
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`。
|
||
|
||
```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: ShanghaiDateTime;
|
||
formFields: Record<string, string>;
|
||
}
|
||
```
|
||
|
||
签名默认有效 5 分钟,以 `expiresAt` 为准。`formFields` 全部原样传给 OSS,不自行拼接签名或对象地址。
|
||
|
||
```ts
|
||
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` |
|
||
|
||
```ts
|
||
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: ShanghaiDateTime;
|
||
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<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 只清除绑定,不物理删除已上传对象。
|
||
|
||
### 8.3 整机、零件、拼装步骤及行走资源
|
||
|
||
四类资源均为选填,只允许管理员上传。先创建项目取得 `projectCode`,项目 READY 后分别上传;每类只保存一个当前绑定,替换后立即反映到社区详情,不需要重新发布。
|
||
|
||
| resourceType | 页面入口 | 规则 | 详情字段 |
|
||
| --- | --- | --- | --- |
|
||
| `model-glb` | 选择整机 GLB | 恰好一个 `.glb`,提交文件名 | `modelGlbUrl` |
|
||
| `model-parts` | 选择零件文件夹 | 只上传 `.glb`,保留子目录 | `modelPartsBaseUrl`、`modelPartsFiles` |
|
||
| `assembly-json` | 高级导入 JSON | 恰好一个 `.json`,提交文件名,不解析业务内容 | `assemblyJsonUrl` |
|
||
| `walking-resources` | 选择行走资源文件夹 | 保留全部文件与子目录,不要求 `robot.json` | `walkingResourcesBaseUrl`、`walkingResourcesFiles` |
|
||
|
||
扩展名忽略大小写,保留原文件名大小写。文件夹相对路径须去掉所选文件夹最外层名称,不能包含绝对路径、空段、`.`、`..`、反斜杠、控制字符、冒号或 `.git` 目录。不同目录可以有同名文件,同一相对路径不能重复。空文件夹不提交;未绑定或清除时地址为 null,详情清单为 `[]`。目录基础地址以 `/` 结尾,文件 URL 已按路径段编码,不要整体二次编码。
|
||
|
||
应用不设置文件数量、目录总量和单文件业务配额,不套用 URDF 的 50 MiB / 200 MiB / 500 文件限制;OSS 表单直传自身单文件上限为 5 GB(5368709120 字节),超出返回 413 `RESOURCE_FILE_TOO_LARGE`。新资源的签名和确认接口不套用普通 JSON 正文配额;反向代理需允许实际清单大小。零字节文件可以上传,本次仅核验扩展名、路径及对象大小。
|
||
|
||
| 方法和路径 | 请求 | 返回 data |
|
||
| --- | --- | --- |
|
||
| `POST /admin-api/projects/{projectCode}/resources/{resourceType}/signature` | `{ files: ResourceFile[] }` | `ResourceUploadSignature` |
|
||
| `PUT /admin-api/projects/{projectCode}/resources/{resourceType}` | `{ batchCode, files: ResourceFile[] }` | 更新后的平铺 `ProjectView` |
|
||
| `DELETE /admin-api/projects/{projectCode}/resources/{resourceType}` | 无 body | `null`,幂等清除绑定 |
|
||
|
||
```ts
|
||
type ResourceType = 'model-glb' | 'model-parts' | 'assembly-json' | 'walking-resources';
|
||
interface ResourceFile { relativePath: string; sizeBytes: number }
|
||
interface ResourceUploadSignature {
|
||
batchCode: string;
|
||
uploadUrl: string;
|
||
expiresAt: ShanghaiDateTime;
|
||
files: { relativePath: string; objectKey: string; formFields: Record<string, string> }[];
|
||
}
|
||
|
||
function selectResourceFiles(type: ResourceType, chosen: FileList): SelectedFile[] {
|
||
return Array.from(chosen).map(file => {
|
||
const path = file.webkitRelativePath;
|
||
const relativePath = path ? path.slice(path.indexOf('/') + 1) : file.name;
|
||
return { file, relativePath };
|
||
}).filter(item => type !== 'model-parts' || /\.glb$/i.test(item.relativePath));
|
||
}
|
||
|
||
async function uploadProjectResource(
|
||
projectCode: string, type: ResourceType, selected: SelectedFile[],
|
||
): Promise<ProjectView> {
|
||
if (!selected.length) throw new Error('请选择资源文件');
|
||
const files: ResourceFile[] = selected.map(item => ({
|
||
relativePath: item.relativePath, sizeBytes: item.file.size,
|
||
}));
|
||
const endpoint = `/projects/${projectCode}/resources/${type}`;
|
||
const signature = await requestAdmin<ResourceUploadSignature>(`${endpoint}/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>(endpoint, {
|
||
method: 'PUT', body: { batchCode: signature.batchCode, files },
|
||
});
|
||
}
|
||
```
|
||
|
||
前端把各文件的 `formFields` 原样加入 FormData,最后追加 `file`,直接 POST OSS,不携带平台 Authorization、不手动设置 multipart Content-Type。OSS 成功为 HTTP 200、空响应体。示例复用第 7 节的 `uploadOssFile`;实际大批量上传可使用有并发上限的队列。
|
||
|
||
每次签名生成新批次,有效期默认 1 小时,可通过 `PROJECT_RESOURCE_SIGNATURE_VALIDITY` 配置,例如 `2h`;签名响应禁止缓存。对象键为 `{环境根目录}/project-resources/{projectCode}/{resourceType}/{batchCode}/{relativePath}`,test 根目录为 `vibemake_dev`,prod 为 `vibemake`。Policy 精确绑定对象键、声明大小、MIME、成功状态,并禁止覆盖。全部上传成功后,提交原批次及原文件清单;后端逐文件 HEAD 核验存在和大小,再一次性更新当前绑定。
|
||
|
||
上传失败、取消或确认失败均保留原绑定;签名过期重新申请批次。确认缺文件返回 400 `RESOURCE_FILE_MISSING`,大小不符返回 400 `RESOURCE_FILE_SIZE_MISMATCH`;路径、扩展名、类型或清单错误返回 400,项目不存在或已删除返回 404,仓库未 READY 返回 409,OSS 未开启返回 503。清除绑定在 OSS 关闭时仍可执行。
|
||
|
||
Fork 只复制这四类资源的八个数据库字段,复用原 OSS 对象,不对这些资源执行 HEAD、复制或下载,OSS 暂不可用也不影响该继承过程。副本与来源后续各自替换绑定,替换、清除和删除项目均保留旧对象。已有 URDF 仍使用原独立复制规则。
|
||
|
||
所有平台资源绑定在数据库中保存不含域名及环境前缀的相对路径,历史完整 key 在项目保存或 Fork 时规范化;返回的签名对象键和公开 URL 仍包含当前环境根目录。存量转换 SQL 见 [OSS 引用规范](oss-storage-paths.md)。
|
||
|
||
部署前执行 [项目资源增量 SQL](admin-database.md#已有数据库增加四类项目资源字段)。RAM 用户对当前环境 `project-resources/*` 增加 `oss:PutObject` 和 `oss:GetObject` 权限;配置资源公开读取或公开 CDN,真实前端 Origin 的 OSS CORS 允许 POST、GET、HEAD,允许 Content-Type。无需为新增资源开通复制或删除权限,应用不修改 Bucket 配置。
|
||
|
||
### 8.4 STEP 单文件上传
|
||
|
||
STEP 独立于 URDF 和 Git,只允许管理员操作已 READY 且未删除的项目;上传、替换、移除立即更新当前资源,不创建提交、不改变发布状态,浏览 Git 历史不会切换 STEP。
|
||
|
||
| 方法和路径 | JSON 请求 | 返回的 data |
|
||
| --- | --- | --- |
|
||
| `POST /admin-api/projects/{projectCode}/step/signature` | `{ files: StepFile[] }` | `StepUploadSignature` |
|
||
| `PUT /admin-api/projects/{projectCode}/step` | `{ batchCode: string, files: StepFile[] }` | 完整 `ProjectView`,不包裹 project |
|
||
| `DELETE /admin-api/projects/{projectCode}/step` | 无 body | `null` |
|
||
|
||
```ts
|
||
interface StepFile {
|
||
relativePath: string;
|
||
sizeBytes: number;
|
||
}
|
||
interface StepUploadSignature {
|
||
batchCode: string;
|
||
mainRelativePath: string;
|
||
uploadUrl: string;
|
||
expiresAt: string; // 带时区,例如 2026-11-02T08:15:00Z
|
||
files: [{ relativePath: string; objectKey: string; formFields: Record<string, string> }];
|
||
}
|
||
```
|
||
|
||
只接受一个 `.step` / `.stp` 文件,忽略后缀大小写,默认范围为 **1–524288000 字节(500 MiB)**。文件名最多 1024 字符,保留中文、空格和大小写,不允许目录、反斜杠、冒号、控制字符等。前端常量和提示文案需同步为 500 MiB。
|
||
|
||
签名有效期 15 分钟,响应禁止缓存。上传时原样附加所有 `formFields`,最后追加 `file`,向 `uploadUrl` 发起 multipart POST;不要携带管理端 Bearer Token。Policy 精确限制对象及大小,并禁止覆盖。对象以 `model{原始后缀}` 存储,原始名称通过 `stepFileName` 和签名中的 Content-Disposition 保留,不从 URL 猜文件名。
|
||
|
||
上传完成后使用原 `batchCode` 和文件清单 PUT 确认;成功返回完整项目。详情 GET 的层级仍为 `data.project`。前端直接访问 `stepMainUrl` 下载,无额外下载接口。替换、移除及删除项目不物理删除 OSS 对象,旧链接仍可访问;Fork 继承资源引用,后续可分别修改。
|
||
|
||
本期与 URDF 一样不保存批次:确认只核验对应项目 STEP 目录的对象存在及大小,不比对历史签名清单,不提供严格幂等、批次过期或绑定冲突检测。确认失败可以重试,但每次确认都重新核验和写入;已上传对象可在签名过期后确认;并发以最后一次成功写入为准;旧请求可能在替换或移除后重新绑定旧对象。不要依据旧需求假设服务端会返回 STEP_BATCH_EXPIRED、STEP_BATCH_MISMATCH 或 STEP_BINDING_CHANGED。
|
||
|
||
参数错误为 `400 STEP_INVALID_FILE`,超过上限为 `413 STEP_FILE_TOO_LARGE`;对象缺失、大小不符分别为 `409 STEP_FILE_MISSING`、`409 STEP_FILE_SIZE_MISMATCH`。OSS 访问故障沿用 `OSS_ERROR` / `OSS_UNAVAILABLE`,前端保留已上传请求以便重试确认。
|
||
|
||
## 9. GitHub 项目迁移
|
||
|
||
页面流程:**输入地址 → 预检 → 补充信息、可选上传封面和 URDF → 创建任务并绑定资源 → 查看阶段 → 检查文件 → 手动发布**。封面和 URDF 均可在迁移表单内完成,无需等迁移后再去项目列表寻找项目。
|
||
|
||
### 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 时提示“已存在项目”,提供进入现有项目详情的入口,不重复创建。同一来源对应的旧项目全部删除后返回 null,可以重新填写表单并创建迁移任务。新迁移使用新的 projectCode、taskCode 和仓库,重新拉取 GitHub 内容;旧项目及历史任务不被覆盖,已删除项目仍不出现在管理员列表和详情中。预检通过也不保证创建必然成功,创建时仍会重新校验来源和重复记录。
|
||
|
||
### 9.2 迁移表单上传封面和 URDF(可选)
|
||
|
||
封面继续使用第 7 节的签名和 OSS 直传流程,把上传成功后返回的 coverUrl 放入 `project.coverUrl`。
|
||
|
||
URDF 使用专门的迁移前签名接口:`POST /admin-api/project-imports/urdf/signature` → `UrdfUploadSignature`(返回字段同第 8 节)。**此时无需 projectCode,也不创建项目或迁移任务。**
|
||
|
||
```json
|
||
{
|
||
"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 接口**。
|
||
|
||
```ts
|
||
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 稳定身份重新核对。任务创建失败且尚未创建项目、来源迁移记录也未变化时,已上传的同一来源批次可保留用于用户确认后的再次提交,不必覆盖重传文件;旧项目删除后再次迁移必须重新申请签名和上传 URDF,不能沿用旧项目的批次。查询到 DUPLICATE_SOURCE 则进入尚未删除的已有项目核对,不再重建任务。
|
||
|
||
### 9.3 创建任务
|
||
|
||
`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
|
||
},
|
||
"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 仓库仍在后台迁移,**不表示迁移完成,也不会自动发布**。点击创建时禁用重复提交按钮,成功后进入任务详情页。
|
||
|
||
```ts
|
||
type ImportStatus = 'QUEUED' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'REVIEW';
|
||
type ImportPhase = 'QUEUED' | 'CLEANING' | 'PRECHECK' | 'MIGRATING' | 'VERIFYING' | 'MIGRATED'
|
||
| 'NORMALIZING' | 'BRANCH_READY' | 'README_IMAGES' | 'LINKED';
|
||
|
||
interface TaskView {
|
||
taskCode: string;
|
||
projectCode: string;
|
||
status: ImportStatus;
|
||
phase: ImportPhase;
|
||
errorCode: string | null;
|
||
canRetry: boolean;
|
||
retryMessage: string | null;
|
||
warnings: string[];
|
||
createdAt: ShanghaiDateTime;
|
||
startedAt: ShanghaiDateTime | null;
|
||
finishedAt: ShanghaiDateTime | null;
|
||
}
|
||
```
|
||
|
||
任务响应示例:
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "成功",
|
||
"data": {
|
||
"taskCode": "aabbccddeeff00112233445566778899",
|
||
"projectCode": "0123456789abcdef0123456789abcdef",
|
||
"status": "QUEUED",
|
||
"phase": "QUEUED",
|
||
"errorCode": null,
|
||
"canRetry": false,
|
||
"retryMessage": 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;先展示 retryMessage 供用户确认 | HTTP 202,`TaskView`;后台清理或续跑 |
|
||
|
||
状态决定页面行为,阶段用于文字说明:
|
||
|
||
| status | 建议文案 | 前端行为 |
|
||
| --- | --- | --- |
|
||
| QUEUED | 排队中 | 持续轮询,不重复提交 |
|
||
| RUNNING | 迁移中 | 持续轮询,展示阶段和 warnings |
|
||
| SUCCEEDED | 迁移完成,待检查发布 | 停止轮询,跳转项目检查;不会自动发布 |
|
||
| FAILED | 迁移失败 | 停止轮询,展示提醒;canRetry=true 时显示“重试迁移” |
|
||
| REVIEW | 结果待核对 | 停止轮询;canRetry=true 时可重试核验/续跑,否则提示联系维护人员 |
|
||
|
||
| phase | 建议文案 |
|
||
| --- | --- |
|
||
| QUEUED | 等待处理 |
|
||
| CLEANING | 核验并清理失败仓库,准备重新迁移 |
|
||
| PRECHECK | 校验来源和项目信息 |
|
||
| MIGRATING | 迁移 Git 仓库与 LFS |
|
||
| VERIFYING | 核验已有迁移结果,确认后接续原任务 |
|
||
| MIGRATED | 仓库迁移已确认 |
|
||
| NORMALIZING | 适配社区主分支 |
|
||
| BRANCH_READY | 主分支已准备 |
|
||
| README_IMAGES | 转存 README 外链图片并核对提交 |
|
||
| LINKED | 已关联社区项目 |
|
||
|
||
README 图片转存自动在主分支适配后执行,支持 Markdown、HTML 图片及备用图片地址;仓库内图片和动态徽章保持原样。单图失败保留原链,原因追加到 `warnings`,迁移仍可完成。README 提交结果不明时任务进入 `REVIEW`,重试只核对原操作收据,不重新迁移或重发提交。后台迁移完成后仍需管理员手动发布。
|
||
|
||
不展示百分比进度,接口没有 progress、duration 字段。canRetry 由后端判断,前端不要仅按 status/phase 猜测是否可重试;重试仍会校验项目最新状态,可能返回 409。retryMessage 是重试确认框或无法重试时的说明,正常执行中/成功时为 null。耗时可根据 startedAt、finishedAt 计算,空值显示 `—`。任务查询 HTTP 200、code=OK 只表示查询成功,必须再判断 data.status。
|
||
|
||
### 9.5 轮询示例
|
||
|
||
建议约 3 秒轮询一次,等待上次请求完成再发下次;离开页面、退出或遇到终态时停止。网络异常显示“获取状态失败”,允许恢复查询,不能把查询失败当作迁移失败。
|
||
|
||
```ts
|
||
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 重试和功能边界
|
||
|
||
- canRetry=true 时显示“重试迁移”按钮,用 retryMessage 说明操作并确认;点击后禁用重复提交,收到 202 后恢复轮询。409 表示状态已变化或核验未通过,刷新任务并显示 message,不循环重发。
|
||
- 对于明确失败的 `GITEA_MIGRATION_REJECTED`,新任务显示 FAILED。重试后经过 CLEANING:后台核验残留仓库的任务标识、组织、名称、来源及仓库身份,清理后确认不存在,再重新迁移。沿用原 taskCode/projectCode,保留项目资料、封面及 URDF。
|
||
- 已取得成功迁移收据时,重试只核验并继续后续步骤,不删除已迁移仓库。项目已 READY、发布过、下架或删除时拒绝重试。若项目已删除并希望重新拉取 GitHub 内容,应返回“新建迁移”重新预检、提交,创建新的项目和任务;不要对旧任务反复调用 retry。管理员查询仍不显示已删除项目。
|
||
- 超时、进程在远端迁移期间中断、成功响应丢失且尚未保存收据时,原任务进入 REVIEW。若项目仍符合恢复条件,canRetry=true,点击同一“重试迁移”接口返回 202,进入 VERIFYING;后台只读核验任务归属标识、GitHub 稳定来源、组织、仓库名称、私有属性、非镜像、非空状态、已记录仓库身份及稳定的来源分支提交。通过后原子保存恢复收据和冻结 SHA,再继续分支适配和项目关联;不删除仓库、不重新发起 GitHub 迁移,不自动发布,原封面和 URDF 保留。VERIFYING 是结果核验,不表示重新拉取文件。
|
||
- 核验时仓库不存在、仍为空、无法读取、归属/来源不符或身份变化时,保持 REVIEW,项目仍被阻断;前端展示 errorCode、retryMessage,按 canRetry 决定是否允许再次核验。MIGRATION_NOT_FINISHED 可等待 Gitea 完成后再次点击;MIGRATION_TARGET_UNSAFE、MIGRATION_TARGET_REPLACED 需要先人工核对,不能改数据库标记成功或绕过身份校验。来源稳定标识发生变化时返回 SOURCE_CHANGED 并停止重试。
|
||
- REVIEW 迁移不会被定时扫描自动核验;由管理员点击重试触发后台核验及续跑。不要为 REVIEW 自动循环发送 retry,也不要用列表“刷新状态”代替恢复操作。清理本身超时或回写中断仍沿用 CLEANING 的原有核验流程。
|
||
- 旧版本显示 REVIEW 且错误为 GITEA_MIGRATION_REJECTED 的任务,也可以显示重试按钮。若仓库已不存在可以重迁;若仍有残留,但缺少新版本的任务归属标识,则停止清理并返回 REVIEW,避免误删。
|
||
- 如果返回 CLEANUP_REPOSITORY_UNSAFE 或 CLEANUP_REPOSITORY_REPLACED,说明残留仓库归属无法核实或身份变化,未删除仓库。项目仍允许恢复时 canRetry=true,retryMessage 提示先人工核对清理;人工删除目标仓库后,刷新并点击同一“重试迁移”按钮即可,无需修改数据库或新建任务。重试仍先核验:仓库依然存在且无法确认归属时继续阻断,确认不存在才重新迁移。canRetry=true 表示允许再次核验,不表示仓库已清理或必然迁移成功。
|
||
- 同一来源存在未删除项目时返回 409 `DUPLICATE_SOURCE`,错误 data 中的 projectCode 可用于跳转现有项目。若旧项目已全部删除,则允许创建全新的迁移;不要改项目名或循环创建来绕过有效项目的去重。
|
||
- 没有取消任务、强行成功、任意删除仓库、定期同步源仓库的接口;失败仓库清理只能通过上述受保护的 retry 流程执行。
|
||
- 迁移保留 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 引导查看已有项目 |
|
||
| 409 CLEANUP_REPOSITORY_UNSAFE / CLEANUP_REPOSITORY_REPLACED | 残留仓库核验不通过,停止清理;任务中的同名 errorCode 也按此提示 |
|
||
| REMOTE_RESULT_UNKNOWN(状态码以响应为准) | 写入结果待核对,停止重复提交,展示 requestId |
|
||
| 413 FILE_TOO_LARGE / UPLOAD_TOO_LARGE / URDF_UPLOAD_TOO_LARGE | 检查对应预览、下载或上传大小上限;上传可拆批或减少文件 |
|
||
| 499 FILE_DOWNLOAD_CANCELLED / 504 FILE_DOWNLOAD_TIMEOUT | 下载取消或超时,丢弃残缺文件,可手动重试 |
|
||
| 413 UPLOAD_TOO_MANY_PARTS | 文件或表单项数量超限,减少文件并检查重复添加的字段 |
|
||
| 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 → 刷新详情 |
|
||
| 整机、零件、拼装步骤、行走资源 | 创建项目并等待 READY → resources/{resourceType}/signature → 逐文件 OSS 上传 → PUT resources/{resourceType} |
|
||
| 迁移创建 | 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;未完整上传时不能创建任务。
|
||
- 重复来源提供现有项目入口;任务失败、超时及待核对不自动重建迁移任务。
|
||
- 重试按钮使用 canRetry 控制,确认框显示 retryMessage;明确失败时可清理重迁,结果未知时核验已有仓库再续跑;CLEANING 展示清理提示,VERIFYING 展示结果核验提示。
|
||
|
||
## Redis 接入后的兼容与错误处理
|
||
|
||
接口路径、请求字段和正常响应字段保持兼容,仍只暴露业务编码。普通用户登录方式不变。会话已存入 Redis,应用重启保留未过期会话,首次从本机缓存版本升级需要重新登录。生产环境默认关闭 Swagger/OpenAPI;test 保留。
|
||
|
||
新增错误:429 RATE_LIMITED(频率超限)、429 FILE_BUSY(文件处理并发繁忙)、503 REDIS_UNAVAILABLE(安全状态服务不可用)、413 REQUEST_TOO_LARGE(JSON 请求字节超限)、502 GITEA_RESPONSE_TOO_LARGE(上游读取超限)。429 频率/文件繁忙响应提供 Retry-After 秒数,并通过 CORS 暴露;前端等待后手动重试。保留原 AI_BUSY、AI_RATE_LIMITED、FORK_BUSY、ADMIN_LOGIN_LIMITED 及文件大小错误码。
|
||
|
||
鉴权或普通业务请求收到 503 时保留本地 Token,提示服务暂不可用;正常 401 仍清除登录状态。用户主动退出时始终清理本地 Token;退出接口若返回 503,表示服务端撤销结果尚未确认。仓库写入遇到 REMOTE_RESULT_UNKNOWN 时先核对项目和 requestId,不自动重发。请求限流在解析大内容前执行,部分超限请求可能先返回 429。
|
||
|
||
Fork 每用户每分钟 10 次、URDF 批次签名 20 次、封面签名 30 次,均为独立请求尝试次数;一个 URDF 文件夹的一次批次签名算一次,不按文件数计。Fork 同时执行仍最多 2 个,文件读取/目录/历史/提交/上传合计最多 4 个。普通 JSON 256 KiB、URDF 清单 2 MiB、提交 JSON 64 MiB,原有单文件和总内容约束继续保留。全部规则和可配置变量见 [部署说明](admin-deployment.md#redis-安全与资源保护)。
|
||
|
||
登录和签名响应显式禁止缓存。CORS 新增暴露 Retry-After,不启用跨域 Cookie;正文、Token、邮箱及验证码答案不得写入前端日志。
|