Files
community/docs/admin-api.md
T
2026-10-21 16:28:53 +08:00

1109 lines
46 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Community 管理后台前端接口文档
适用模块:`community-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-目录上传)
- [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<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` 或时区偏移。
```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<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 分钟后重试。
会话默认 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<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;
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<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:
```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<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 文件也不保证能在线预览。
下载使用携带后台 Authorization 的 `fetch`,成功后 `response.blob()`,从 `Content-Disposition` 获取文件名并触发保存。不要把 Token 拼到 URL,也不要直接用不带鉴权的 `<a href>` 下载。下载失败仍可能是 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<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: UtcDateTime;
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: 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<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`。
```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 迁移表单上传封面和 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 稳定身份重新核对。任务创建失败且尚未创建项目时,已上传的同一来源批次可保留用于用户确认后的再次提交,不必覆盖重传文件;查询到 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' | 'MIGRATED'
| 'NORMALIZING' | 'BRANCH_READY' | 'LINKED';
interface TaskView {
taskCode: string;
projectCode: string;
status: ImportStatus;
phase: ImportPhase;
errorCode: string | null;
canRetry: boolean;
retryMessage: 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,
"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 |
| MIGRATED | 仓库迁移已确认 |
| NORMALIZING | 适配社区主分支 |
| BRANCH_READY | 主分支已准备 |
| LINKED | 已关联社区项目 |
不展示百分比进度,接口没有 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、发布过、下架或删除时拒绝重试。
- 超时、进程在远端迁移期间中断等未知结果,不自动删除仓库或重发迁移;canRetry=false 时由维护人员处理。清理本身超时或回写中断,可通过重试重新核验目标是否已删除后恢复。
- 旧版本显示 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 | 检查对应上传类型限额,拆批或减少文件 |
| 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;未完整上传时不能创建任务。
- 重复来源提供现有项目入口;任务失败、超时及待核对不自动重建迁移任务。
- 重试按钮使用 canRetry 控制,确认框显示 retryMessage;明确失败时可清理重迁,结果未知时不盲目删库;CLEANING 阶段展示清理提示。