diff --git a/community-adminapi/src/main/java/com/linkerbot/community/adminapi/controller/AdminImportController.java b/community-adminapi/src/main/java/com/linkerbot/community/adminapi/controller/AdminImportController.java index 7225969..2128a22 100644 --- a/community-adminapi/src/main/java/com/linkerbot/community/adminapi/controller/AdminImportController.java +++ b/community-adminapi/src/main/java/com/linkerbot/community/adminapi/controller/AdminImportController.java @@ -1,6 +1,7 @@ package com.linkerbot.community.adminapi.controller; import com.linkerbot.community.bean.AdminContracts.*; +import com.linkerbot.community.bean.Contracts.UrdfUploadSignature; import com.linkerbot.community.common.*; import com.linkerbot.community.service.admin.AdminImportService; @@ -22,6 +23,12 @@ public class AdminImportController { return ApiResponse.success(service.preview(input.repositoryUrl())); } + @PostMapping("/urdf/signature") + public ApiResponse urdfSignature( + @Valid @RequestBody ImportUrdfUploadInput input) { + return ApiResponse.success(service.urdfSignature(input)); + } + @PostMapping public ResponseEntity> create(@Valid @RequestBody ImportInput input) { return ResponseEntity.accepted().body(ApiResponse.success(service.create(input))); diff --git a/community-adminapi/src/test/java/com/linkerbot/community/adminapi/AdminWorkflowTest.java b/community-adminapi/src/test/java/com/linkerbot/community/adminapi/AdminWorkflowTest.java index 48f4c43..51892c2 100644 --- a/community-adminapi/src/test/java/com/linkerbot/community/adminapi/AdminWorkflowTest.java +++ b/community-adminapi/src/test/java/com/linkerbot/community/adminapi/AdminWorkflowTest.java @@ -10,8 +10,10 @@ import com.linkerbot.community.common.BusinessException; import com.linkerbot.community.security.TokenService; import com.linkerbot.community.service.*; import com.linkerbot.community.service.admin.AdminImportService; +import com.linkerbot.community.service.config.OssProperties; import com.linkerbot.community.service.mapper.*; import com.linkerbot.community.service.migration.GitHubSourceChecks; +import com.linkerbot.community.service.oss.OssObjectStore; import com.linkerbot.community.service.support.*; import org.junit.jupiter.api.*; @@ -55,6 +57,12 @@ class AdminWorkflowTest { return new FakeGiteaClient(); } + @Bean + @Primary + FakeOssObjectStore fakeOss() { + return new FakeOssObjectStore(); + } + @Bean @Primary GitHubSourceChecks fakeSources() { @@ -86,6 +94,8 @@ class AdminWorkflowTest { @Autowired ProjectService projectService; @Autowired UserService userService; @Autowired ProjectLocks locks; + @Autowired OssProperties oss; + @Autowired FakeOssObjectStore ossObjects; private User admin; private User ordinary; private String token; @@ -110,6 +120,8 @@ class AdminWorkflowTest { } SOURCES.incrementAndGet(); gitea.reset(); + oss.setEnabled(false); + ossObjects.objects.clear(); admin = userService.login(UUID.randomUUID() + "@example.invalid"); ordinary = userService.login(UUID.randomUUID() + "@example.invalid"); auth.bootstrap(admin.getUserCode(), PASSWORD); @@ -168,6 +180,138 @@ class AdminWorkflowTest { .path("data"); } + private void enableOss() { + oss.setRegion("cn-hangzhou"); + oss.setBucket("examplebucket"); + oss.setAccessKeyId("UnitTestAccessKey"); + oss.setAccessKeySecret("unit-test-secret"); + oss.setPublicBaseUrl("https://images.example.com"); + oss.setEnabled(true); + } + + private List> urdfFiles() { + return List.of( + Map.of("relativePath", "urdf/机械臂.URDF", "sizeBytes", 12), + Map.of("relativePath", "meshes/body.stl", "sizeBytes", 24)); + } + + private JsonNode importUrdfSignature() throws Exception { + return request( + signed(body(post("/admin-api/project-imports/urdf/signature"), + Map.of("repositoryUrl", "https://github.com/example/robot", + "files", urdfFiles()))), + 200) + .path("data"); + } + + private void storeUrdfFiles(JsonNode signature) { + for (int index = 0; index < urdfFiles().size(); index++) { + String key = signature.path("files").get(index).path("objectKey").asText(); + long size = ((Number) urdfFiles().get(index).get("sizeBytes")).longValue(); + ossObjects.objects.put(key, new OssObjectStore.Metadata(size, "test-etag")); + } + } + + private Map importWithUrdf(JsonNode signature) { + return Map.of( + "repositoryUrl", "https://github.com/example/robot", + "project", metadata(), + "urdf", Map.of("batchCode", signature.path("batchCode").asText(), + "files", urdfFiles())); + } + + @Test + void migrationBindsCoverAndUrdfWithoutWaitingForRepositoryReadiness() throws Exception { + enableOss(); + JsonNode signature = importUrdfSignature(); + assertThat(signature.path("mainRelativePath").asText()).isEqualTo("urdf/机械臂.URDF"); + assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM project", Long.class)).isZero(); + assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM project_import_task", Long.class)).isZero(); + storeUrdfFiles(signature); + String cover = request( + signed(body(post("/admin-api/uploads/project-covers/signature"), + Map.of("contentType", "image/png", "fileSize", 100))), 200) + .path("data").path("coverUrl").asText(); + Map project = new HashMap<>(metadata()); + project.put("coverUrl", cover); + Map input = new HashMap<>(importWithUrdf(signature)); + input.put("project", project); + JsonNode task = request(signed(body(post("/admin-api/project-imports"), input)), 202).path("data"); + String code = task.path("projectCode").asText(); + JsonNode pending = request(signed(get("/admin-api/projects/" + code)), 200).path("data").path("project"); + assertThat(pending.path("repoStatus").asText()).isEqualTo("CREATING"); + assertThat(pending.path("coverUrl").asText()).isEqualTo(cover); + assertThat(pending.path("urdfMainUrl").asText()) + .contains("/urdf/" + code + "/" + signature.path("batchCode").asText() + "/") + .endsWith("urdf/%E6%9C%BA%E6%A2%B0%E8%87%82.URDF"); + assertThat(pending.path("publishStatus").asText()).isEqualTo("UNPUBLISHED"); + imports.run(task.path("taskCode").asText()); + JsonNode ready = request(signed(get("/admin-api/projects/" + code)), 200).path("data").path("project"); + assertThat(ready.path("repoStatus").asText()).isEqualTo("READY"); + assertThat(ready.path("urdfMainUrl")).isEqualTo(pending.path("urdfMainUrl")); + assertThat(ready.path("coverUrl").asText()).isEqualTo(cover); + assertThat(ready.path("publishStatus").asText()).isEqualTo("UNPUBLISHED"); + } + + @Test + void migrationRejectsIncompleteOrMismatchedUrdfBeforeCreatingProjectAndTask() throws Exception { + enableOss(); + JsonNode signature = importUrdfSignature(); + JsonNode missing = request(signed(body(post("/admin-api/project-imports"), importWithUrdf(signature))), 400); + assertThat(missing.path("code").asText()).isEqualTo("URDF_FILE_MISSING"); + storeUrdfFiles(signature); + String mainKey = signature.path("files").get(0).path("objectKey").asText(); + ossObjects.objects.put(mainKey, new OssObjectStore.Metadata(13, "test-etag")); + JsonNode mismatch = request(signed(body(post("/admin-api/project-imports"), importWithUrdf(signature))), 400); + assertThat(mismatch.path("code").asText()).isEqualTo("URDF_FILE_SIZE_MISMATCH"); + assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM project", Long.class)).isZero(); + assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM project_import_task", Long.class)).isZero(); + storeUrdfFiles(signature); + SOURCES.incrementAndGet(); + // 同一个批次不能被另一个 GitHub 仓库借用。 + JsonNode otherSource = request(signed(body(post("/admin-api/project-imports"), importWithUrdf(signature))), 400); + assertThat(otherSource.path("code").asText()).isEqualTo("URDF_FILE_MISSING"); + assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM project", Long.class)).isZero(); + } + + @Test + void importUrdfRequiresAdminValidManifestAndNewSource() throws Exception { + Map input = Map.of("repositoryUrl", "https://github.com/example/robot", "files", urdfFiles()); + request(body(post("/admin-api/project-imports/urdf/signature"), input), 401); + String ordinaryToken = tokens.issue(ordinary.getId(), ordinary.getSessionVersion()); + request(body(post("/admin-api/project-imports/urdf/signature"), input) + .header("Authorization", "Bearer " + ordinaryToken), 403); + request(signed(body(post("/admin-api/project-imports/urdf/signature"), input)), 503); + enableOss(); + request(signed(body(post("/admin-api/project-imports/urdf/signature"), + Map.of("repositoryUrl", "https://127.0.0.1/private", "files", urdfFiles()))), 400); + JsonNode invalid = request(signed(body(post("/admin-api/project-imports/urdf/signature"), + Map.of("repositoryUrl", "https://github.com/example/robot", + "files", List.of(Map.of("relativePath", "../robot.urdf", "sizeBytes", 12))))), 400); + assertThat(invalid.path("code").asText()).isEqualTo("BAD_REQUEST"); + request(signed(body(post("/admin-api/project-imports"), + Map.of("repositoryUrl", "https://github.com/example/robot", "project", metadata(), + "urdf", Map.of("batchCode", "invalid", "files", urdfFiles())))), 400); + JsonNode task = createImport(); + JsonNode duplicate = request(signed(body(post("/admin-api/project-imports/urdf/signature"), input)), 409); + assertThat(duplicate.path("code").asText()).isEqualTo("DUPLICATE_SOURCE"); + assertThat(duplicate.path("data").path("projectCode")).isEqualTo(task.path("projectCode")); + } + + @Test + void importUrdfBindingRollsBackWhenTaskCreationFails() throws Exception { + enableOss(); + JsonNode signature = importUrdfSignature(); + storeUrdfFiles(signature); + jdbc.execute("ALTER TABLE project_import_task ADD CONSTRAINT simulate_task_failure CHECK (status <> 'QUEUED')"); + request(signed(body(post("/admin-api/project-imports"), importWithUrdf(signature))), 500); + assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM project", Long.class)).isZero(); + assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM project_import_task", Long.class)).isZero(); + assertThat(gitea.migrations).isZero(); + jdbc.execute("ALTER TABLE project_import_task DROP CONSTRAINT simulate_task_failure"); + request(signed(body(post("/admin-api/project-imports"), importWithUrdf(signature))), 202); + } + @Test void authenticationRolesIsolationAndCodeOnlyResponses() throws Exception { request(get("/admin-api/users"), 401); diff --git a/community-adminapi/src/test/java/com/linkerbot/community/adminapi/FakeOssObjectStore.java b/community-adminapi/src/test/java/com/linkerbot/community/adminapi/FakeOssObjectStore.java new file mode 100644 index 0000000..7c1c044 --- /dev/null +++ b/community-adminapi/src/test/java/com/linkerbot/community/adminapi/FakeOssObjectStore.java @@ -0,0 +1,26 @@ +package com.linkerbot.community.adminapi; + +import com.linkerbot.community.common.BusinessException; +import com.linkerbot.community.service.oss.OssObjectStore; + +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; + +final class FakeOssObjectStore implements OssObjectStore { + final Map objects = new ConcurrentHashMap<>(); + + @Override + public Metadata head(String objectKey) { + Metadata metadata = objects.get(objectKey); + if (metadata == null) + throw new BusinessException(400, "URDF_FILE_MISSING", "URDF 文件未上传完整,请重新上传"); + return metadata; + } + + @Override + public void copy(String sourceKey, String targetKey, String sourceEtag) { + Metadata source = head(sourceKey); + if (!source.etag().equals(sourceEtag)) throw BusinessException.conflict("源文件发生变化"); + objects.put(targetKey, source); + } +} diff --git a/community-bean/src/main/java/com/linkerbot/community/bean/AdminContracts.java b/community-bean/src/main/java/com/linkerbot/community/bean/AdminContracts.java index 3248d6b..7ba728a 100644 --- a/community-bean/src/main/java/com/linkerbot/community/bean/AdminContracts.java +++ b/community-bean/src/main/java/com/linkerbot/community/bean/AdminContracts.java @@ -2,6 +2,8 @@ package com.linkerbot.community.bean; import com.linkerbot.community.bean.Contracts.ProjectInput; import com.linkerbot.community.bean.Contracts.ProjectView; +import com.linkerbot.community.bean.Contracts.UrdfConfirmInput; +import com.linkerbot.community.bean.Contracts.UrdfFile; import jakarta.validation.Valid; import jakarta.validation.constraints.*; @@ -49,10 +51,15 @@ public final class AdminContracts { public record PreviewInput(@NotBlank @Size(max = 2048) String repositoryUrl) {} + public record ImportUrdfUploadInput( + @NotBlank @Size(max = 2048) String repositoryUrl, + @NotNull List<@NotNull @Valid UrdfFile> files) {} + public record ImportInput( @NotBlank @Size(max = 2048) String repositoryUrl, String ownerUserCode, - @NotNull @Valid ProjectInput project) {} + @NotNull @Valid ProjectInput project, + @Valid UrdfConfirmInput urdf) {} public record ImportPreview( String repositoryUrl, diff --git a/community-service/src/main/java/com/linkerbot/community/service/admin/AdminImportService.java b/community-service/src/main/java/com/linkerbot/community/service/admin/AdminImportService.java index 5439382..057095e 100644 --- a/community-service/src/main/java/com/linkerbot/community/service/admin/AdminImportService.java +++ b/community-service/src/main/java/com/linkerbot/community/service/admin/AdminImportService.java @@ -6,6 +6,8 @@ import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.fasterxml.jackson.core.type.TypeReference; import com.fasterxml.jackson.databind.ObjectMapper; import com.linkerbot.community.bean.AdminContracts.*; +import com.linkerbot.community.bean.Contracts.UrdfConfirmInput; +import com.linkerbot.community.bean.Contracts.UrdfUploadSignature; import com.linkerbot.community.bean.entity.*; import com.linkerbot.community.common.*; import com.linkerbot.community.service.config.*; @@ -13,6 +15,7 @@ import com.linkerbot.community.service.gitea.*; import com.linkerbot.community.service.mapper.*; import com.linkerbot.community.service.migration.*; import com.linkerbot.community.service.oss.OssResourcePaths; +import com.linkerbot.community.service.oss.UrdfResources; import com.linkerbot.community.service.support.*; import lombok.RequiredArgsConstructor; @@ -40,6 +43,7 @@ public class AdminImportService { private final AdminProperties settings; private final ProjectLocks locks; private final OssResourcePaths paths; + private final UrdfResources urdfResources; private final ObjectMapper json; private final TransactionTemplate transactions; @@ -83,22 +87,53 @@ public class AdminImportService { new LambdaQueryWrapper().eq(Project::getProjectCode, code)); } + private void requireNewSource(long sourceId) { + Project found = existing(sourceId); + if (found != null) + throw new BusinessException( + 409, + "DUPLICATE_SOURCE", + "该来源已存在项目,请检查现有项目", + Map.of("projectCode", found.getProjectCode())); + } + + public UrdfUploadSignature urdfSignature(ImportUrdfUploadInput input) { + management.requireAdmin(); + urdfResources.requireEnabled(); + GitHubSourceChecks.Repository source = check(input.repositoryUrl()); + requireNewSource(source.id()); + String code = ProjectCodes.github(source.id()); + UrdfUploadSignature signature = urdfResources.sign(code, input.files()); + log.info( + "生成迁移项目 URDF 签名 userCode={} projectCode={} batchCode={} fileCount={}", + ProjectActors.admin().userCode(), code, signature.batchCode(), input.files().size()); + return signature; + } + + private record PreparedUrdf(String prefix, String mainObjectKey, String manifest) {} + + private PreparedUrdf prepareUrdf(String projectCode, UrdfConfirmInput input) { + if (input == null) return null; + // 项目编码由重新校验的 GitHub 稳定标识生成,不能借用其他项目的上传批次。 + // OSS 核验在数据库事务及项目锁之外完成,不依赖尚未创建的 Git 仓库。 + urdfResources.verify(projectCode, input.batchCode(), input.files()); + String prefix = urdfResources.prefix(projectCode, input.batchCode()); + String main = urdfResources.validate(prefix, input.files()); + return new PreparedUrdf(prefix, prefix + main, urdfResources.manifest(input.files())); + } + public TaskView create(ImportInput input) { management.requireAdmin(); ProjectInputs.validate(input.project(), properties); GitHubSourceChecks.Repository source = check(input.repositoryUrl()); - User owner = management.owner(input.ownerUserCode()); String code = ProjectCodes.github(source.id()); + requireNewSource(source.id()); + PreparedUrdf urdf = prepareUrdf(code, input.urdf()); + User owner = management.owner(input.ownerUserCode()); return locks.serial( code, () -> { - Project found = existing(source.id()); - if (found != null) - throw new BusinessException( - 409, - "DUPLICATE_SOURCE", - "该来源已存在项目,请检查现有项目", - Map.of("projectCode", found.getProjectCode())); + requireNewSource(source.id()); try { return transactions.execute( status -> { @@ -112,6 +147,11 @@ public class AdminImportService { : input.project().description()); project.setCoverUrl( paths.coverStorage(input.project().coverUrl())); + if (urdf != null) { + project.setUrdfPrefix(urdf.prefix()); + project.setUrdfMainObjectKey(urdf.mainObjectKey()); + project.setUrdfFiles(urdf.manifest()); + } project.setProjectType(input.project().projectType()); project.setGiteaOwner(properties.getGitea().getOwner()); project.setGiteaRepoName("p_" + code); @@ -140,6 +180,12 @@ public class AdminImportService { task.getOperatorUserCode(), task.getTaskCode(), code); + if (urdf != null) + log.info( + "迁移项目绑定 URDF userCode={} taskCode={} projectCode={}" + + " batchCode={} fileCount={}", + task.getOperatorUserCode(), task.getTaskCode(), code, + input.urdf().batchCode(), input.urdf().files().size()); return view(task); }); } catch (DuplicateKeyException duplicate) { diff --git a/docs/admin-api.md b/docs/admin-api.md index 064fb8b..ea03a41 100644 --- a/docs/admin-api.md +++ b/docs/admin-api.md @@ -800,7 +800,7 @@ async function uploadUrdf(projectCode: string, selected: SelectedFile[]): Promis ## 9. GitHub 项目迁移 -页面流程:**输入地址 → 预检 → 补充项目信息 → 创建任务 → 查看阶段 → 检查文件 → 手动发布**。 +页面流程:**输入地址 → 预检 → 补充信息、可选上传封面和 URDF → 创建任务并绑定资源 → 查看阶段 → 检查文件 → 手动发布**。封面和 URDF 均可在迁移表单内完成,无需等迁移后再去项目列表寻找项目。 ### 9.1 预检 @@ -829,7 +829,67 @@ interface ImportPreview { existingProjectCode 非 null 时提示“已存在项目”,提供进入现有项目详情的入口,不重复创建。预检通过也不保证创建必然成功,创建时仍会重新校验来源和重复记录。 -### 9.2 创建任务 +### 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('/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`。 @@ -841,11 +901,20 @@ existingProjectCode 非 null 时提示“已存在项目”,提供进入现有 "description": "待管理员检查的迁移项目", "projectType": "WHEELED", "coverUrl": null + }, + "urdf": { + "batchCode": "aabbccddeeff00112233445566778899", + "files": [ + { "relativePath": "robot.urdf", "sizeBytes": 2400 }, + { "relativePath": "meshes/body.stl", "sizeBytes": 120000 } + ] } } ``` -ownerUserCode 可选,放在最外层,规则同新建项目。project 字段与普通创建一致;许可证、默认分支不通过创建 body 修改。点击创建时禁用重复提交按钮,收到 202 后进入任务详情页。**202 表示已受理,不是迁移完成。** +ownerUserCode、urdf 可选,均放在最外层;归属规则同新建项目。示例 batchCode 必须替换为本次实际上传返回值,files 使用上传时的原清单;封面上传后把 coverUrl 替换为实际返回地址。project 字段与普通创建一致;许可证、默认分支不通过创建 body 修改。 + +URDF 缺失或大小不符时拒绝创建,不留下项目和任务。收到 202 表示任务已受理,传入的 URDF 已绑定到目标项目;Git 仓库仍在后台迁移,**不表示迁移完成,也不会自动发布**。点击创建时禁用重复提交按钮,成功后进入任务详情页。 ```ts type ImportStatus = 'QUEUED' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'REVIEW'; @@ -886,7 +955,7 @@ interface TaskView { } ``` -### 9.3 任务列表、详情与重试 +### 9.4 任务列表、详情与重试 | 方法和路径 | 请求 | 返回的 data | | --- | --- | --- | @@ -916,7 +985,7 @@ interface TaskView { 不展示百分比进度,接口没有 progress、duration、canRetry 字段。耗时可根据 startedAt、finishedAt 计算,空值显示 `—`。任务查询 HTTP 200、code=OK 只表示查询成功,必须再判断 data.status 是否失败或待核对。 -### 9.4 轮询示例 +### 9.5 轮询示例 建议约 3 秒轮询一次,等待上次请求完成再发下次;离开页面、退出或遇到终态时停止。网络异常显示“获取状态失败”,允许恢复查询,不能把查询失败当作迁移失败。 @@ -956,7 +1025,7 @@ async function watchImport( // 页面卸载时调用 controller.abort();捕获 AbortError 后不弹错误提示。 ``` -### 9.5 重试和功能边界 +### 9.6 重试和功能边界 - FAILED 点击重试后,按返回任务恢复轮询;后端拒绝时显示 409 message,不循环重发。 - REVIEW 可能涉及远端结果不明,需要维护人员核对。部分已确认阶段支持同一 retry 接口安全续跑,但判断所需信息不对前端暴露;默认不显示常规重试按钮,也不要只根据 phase 推断可重试。 @@ -964,7 +1033,7 @@ async function watchImport( - 没有取消任务、强行成功、删除目标仓库、定期同步源仓库的接口。 - 迁移保留 Git 历史、分支、标签并迁移 LFS;不迁移 Issue、PR、Wiki、Release 附件,不递归复制子模块依赖。保留分支不代表后台可切换分支。 - 原默认分支非 main 时进行适配;已有 main 内容冲突会停止,前端展示任务错误和提醒即可。 -- 成功后项目仍未发布;需要管理员查看文件并手动发布。封面和 URDF 需要按前面流程单独上传/绑定。 +- 成功后项目仍未发布;需要管理员查看文件并手动发布。迁移表单已提交的封面和 URDF 会保留,无需再次绑定;后续替换资源仍可使用普通项目接口。不会自动扫描 Git 仓库中的 URDF 并绑定。 ## 10. 错误处理 @@ -973,6 +1042,7 @@ async function watchImport( | 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 | 清除后台会话并回登录页;保留合理的返回路径 | @@ -1009,7 +1079,7 @@ requestId 同时可能出现在响应头 `X-Request-Id`。错误提示可附“ | 文件编辑/上传 | 取得当前 SHA → 提交或上传 → 保存新 SHA → 刷新目录和历史 | | 发布确认 | 读取并检查当前 main 文件 → PUT publication → 刷新详情 | | URDF 设置 | 选目录 → signature → 逐文件 OSS 上传 → PUT urdf → 刷新详情 | -| 迁移创建 | preview → 补充表单 → POST project-imports → 进入任务页 | +| 迁移创建 | preview → 补充表单 → 可选封面及迁移 URDF 签名/OSS 上传 → POST project-imports(含 urdf)→ 进入任务页 | | 迁移任务 | 详情轮询 → SUCCEEDED 后检查项目 → 明确发布 | ### 11.2 联调重点 @@ -1023,4 +1093,5 @@ requestId 同时可能出现在响应头 `X-Request-Id`。错误提示可附“ - 上传或编辑文件后不自动发布;已发布版本与工作区最新 SHA 分开展示。 - 下架后不能发布;解除下架后仍需手动发布。 - 迁移 202 显示已受理;终态停止轮询;不把 FAILED/REVIEW 显示为成功。 +- 在迁移表单上传封面和 URDF 后即可创建任务;不必等待仓库 READY 再绑定 URDF;未完整上传时不能创建任务。 - 重复来源提供现有项目入口;任务失败、超时及待核对不自动重建迁移任务。 diff --git a/docs/admin-deployment.md b/docs/admin-deployment.md index 6fded4a..2d3e786 100644 --- a/docs/admin-deployment.md +++ b/docs/admin-deployment.md @@ -53,6 +53,8 @@ project 表只新增 moderation_reason 和 repo_write_status,来源标识、 迁移成功收据先持久化,再处理分支、关联和就绪状态。迁移保留 Git 历史、分支、标签并请求迁移 LFS;不导入 Issue、PR、Wiki、Release 附件,不递归复制子模块或外链。原默认分支不是 main 时补建 main;已有 main 与源默认分支内容不同则停止,不覆盖。 +迁移表单支持预上传封面及 URDF。URDF 使用现有 OSS 配置与限额,创建任务前检查对象,并使用 project 既有 URDF 字段保存,不需要新增数据库变更。上传后未提交表单的 OSS 对象不会自动清理,沿用现有资源生命周期。 + ## 异常核对 - 超时、进程在 MIGRATING 阶段中断或远端结果不明确时进入 REVIEW。禁止自动重发,也不能仅凭仓库存在判定成功。