项目整机拼装与资源文件上传

This commit is contained in:
lxp
2026-10-28 17:49:54 +08:00
parent 4e7d11d586
commit 0dd39eb23d
32 changed files with 964 additions and 29 deletions
+91
View File
@@ -338,6 +338,12 @@ interface ProjectView {
coverUrl: string | null;
urdfMainUrl: string | null;
urdfBaseUrl: string | 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;
@@ -362,6 +368,12 @@ interface ManagedProjectView {
deleted: boolean;
}
interface ResourceFileView {
relativePath: string;
sizeBytes: number;
url: string;
}
interface TypeView {
code: string;
name: string;
@@ -433,6 +445,12 @@ interface TypeView {
"coverUrl": null,
"urdfMainUrl": null,
"urdfBaseUrl": null,
"modelGlbUrl": null,
"modelPartsBaseUrl": null,
"modelPartsFiles": [],
"assemblyJsonUrl": null,
"walkingResourcesBaseUrl": null,
"walkingResourcesFiles": [],
"projectType": "WHEELED",
"owner": { "userCode": "c3d4e5f6a7b8", "nickname": "社区官方" },
"repoStatus": "READY",
@@ -804,6 +822,78 @@ async function uploadUrdf(projectCode: string, selected: SelectedFile[]): Promis
任一文件失败时不要确认绑定;保留失败状态并检查上传结果。签名过期可重新申请完整批次;同批次已成功文件禁止覆盖,不要无条件重传。移除 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: UtcDateTime;
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 仍使用原独立复制规则。
部署前执行 [项目资源增量 SQL](admin-database.md#已有数据库增加四类项目资源字段)。RAM 用户对当前环境 `project-resources/*` 增加 `oss:PutObject` 和 `oss:GetObject` 权限;配置资源公开读取或公开 CDN,真实前端 Origin 的 OSS CORS 允许 POST、GET、HEAD,允许 Content-Type。无需为新增资源开通复制或删除权限,应用不修改 Bucket 配置。
## 9. GitHub 项目迁移
页面流程:**输入地址 → 预检 → 补充信息、可选上传封面和 URDF → 创建任务并绑定资源 → 查看阶段 → 检查文件 → 手动发布**。封面和 URDF 均可在迁移表单内完成,无需等迁移后再去项目列表寻找项目。
@@ -1096,6 +1186,7 @@ requestId 同时可能出现在响应头 `X-Request-Id`。错误提示可附“
| 文件编辑/上传 | 取得当前 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 后检查项目 → 明确发布 |
+33 -1
View File
@@ -6,7 +6,39 @@
## 项目字段收敛
project 只新增 moderation_reason(管理员下架原因)和 repo_write_status(跨进程写入状态)两个字段。下架直接使用现有 publish_status=BLOCKED,不再增加独立治理状态。GitHub来源标识、地址、默认分支和许可证属于迁移任务,统一放在 project_import_task;第一版只支持GitHub,不存平台类型,也不额外区分用户创建与后台创建。
治理相关字段为 moderation_reason(管理员下架原因)和 repo_write_status(跨进程写入状态)。下架直接使用现有 publish_status=BLOCKED,不再增加独立治理状态。GitHub来源标识、地址、默认分支和许可证属于迁移任务,统一放在 project_import_task;第一版只支持GitHub,不存平台类型,也不额外区分用户创建与后台创建。
## 已有数据库增加四类项目资源字段
在已完成原有部署的数据库中手工执行以下 SQL,再升级社区端、管理端和导入工具。新建数据库的 `database.md` 建表语句已包含这些字段,不要重复执行。
```sql
ALTER TABLE project
ADD COLUMN model_glb_object_key VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '整机GLB环境相对路径,不含域名和环境根目录',
ADD COLUMN model_glb_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0
COMMENT '整机GLB文件大小,单位字节',
ADD COLUMN model_parts_prefix VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '零件模型环境相对目录,以斜杠开头和结尾',
ADD COLUMN model_parts_files JSON NOT NULL DEFAULT (JSON_ARRAY())
COMMENT '零件GLB文件清单,包含relativePath和sizeBytes',
ADD COLUMN assembly_json_object_key VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '拼装步骤JSON环境相对路径,不含域名和环境根目录',
ADD COLUMN assembly_json_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0
COMMENT '拼装步骤JSON文件大小,单位字节',
ADD COLUMN walking_resources_prefix VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '行走资源环境相对目录,以斜杠开头和结尾',
ADD COLUMN walking_resources_files JSON NOT NULL DEFAULT (JSON_ARRAY())
COMMENT '行走资源文件清单,包含relativePath和sizeBytes';
```
路径为未编码的 `/project-resources/{projectCode}/{resourceType}/{batchCode}/{relativePath}`,不含域名和环境根目录。目录字段以 `/` 结尾,清单内路径相对于对应目录。未绑定或清除后路径为 `''`、大小为 `0`、清单为 `[]`。
Fork 直接复制这八个字段并复用原 OSS 对象,因此副本保存的路径可以包含源项目编码。读取不校验路径属于当前项目;新上传和确认只能使用当前项目的目录。替换、清除和删除项目均保留 OSS 对象,避免破坏其他副本的引用。后续如增加资源清理任务,必须检查所有项目的共享引用。
## 已有数据库增加字段
+4 -1
View File
@@ -1,6 +1,6 @@
# Vibemake 管理端部署与运维
管理端为独立 Spring Boot 应用 `vibemake-adminapi`,默认端口 8994,接口前缀 `/admin-api`。项目文件复用现有 Gitea 私有组织仓库,封面与 URDF 复用 OSS;不需要新建 Gitea 账号或组织。前端对接见 [管理后台接口文档](admin-api.md)。
管理端为独立 Spring Boot 应用 `vibemake-adminapi`,默认端口 8994,接口前缀 `/admin-api`。项目文件复用现有 Gitea 私有组织仓库,封面、URDF 及四类模型/行走资源复用 OSS;不需要新建 Gitea 账号或组织。前端对接见 [管理后台接口文档](admin-api.md)。
## 部署与初始化
@@ -25,6 +25,7 @@ SPRING_PROFILES_ACTIVE=prod java -jar vibemake-adminapi/target/vibemake-adminapi
| --- | --- |
| `ADMIN_SERVER_PORT` | 8994;独立于社区端 `SERVER_PORT` |
| `ADMIN_ALLOWED_ORIGINS` | 空;完整前端来源用英文逗号分隔,不使用通配符 |
| `PROJECT_RESOURCE_SIGNATURE_VALIDITY` | 1h;整机、零件、拼装 JSON、行走资源直传签名有效期 |
| `ADMIN_IMPORT_WORKER_ENABLED` | true;维护期间可关闭消费 |
| `ADMIN_IMPORT_CONCURRENCY` | 2,范围 1~4 |
| `ADMIN_MIGRATION_TIMEOUT` | 30m,仅迁移请求使用,普通 Gitea 超时不变 |
@@ -59,6 +60,8 @@ project 表只新增 moderation_reason 和 repo_write_status,来源标识、
迁移表单支持预上传封面及 URDF。URDF 使用现有 OSS 配置与限额,创建任务前检查对象,并使用 project 既有 URDF 字段保存,不需要新增数据库变更。上传后未提交表单的 OSS 对象不会自动清理,沿用现有资源生命周期。
整机 GLB、零件 GLB 文件夹、拼装 JSON 和行走资源在项目 READY 后通过项目资源接口上传。升级前先手工执行 [八字段增量 SQL](admin-database.md#已有数据库增加四类项目资源字段)。RAM 用户需拥有当前环境 `project-resources/*` 的 `oss:PutObject`、`oss:GetObject` 权限,配置公开读取/CDN 及真实前端 Origin 的 POST、GET、HEAD CORS。新资源签名和确认清单不设置应用正文配额,反向代理须允许实际清单大小;文件内容由浏览器直接上传 OSS。Fork 对这四类资源只继承数据库引用,不调用 OSS;旧对象保留,后续任何清理机制均需检查共享引用。
## 异常核对
- 超时、进程在 MIGRATING 阶段中断或远端结果不明确时进入 REVIEW。禁止自动重发,也不能仅凭仓库存在判定成功。
+90
View File
File diff suppressed because one or more lines are too long
+8
View File
@@ -32,6 +32,14 @@ CREATE TABLE project (
urdf_main_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'URDF主文件环境相对路径,以斜杠开头,不含域名和环境根目录',
urdf_files JSON NOT NULL DEFAULT (JSON_ARRAY()) COMMENT 'URDF文件清单数组,元素包含relativePath和sizeBytes,相对路径以urdf_prefix为基准',
urdf_prefix VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'URDF资源环境相对目录,包含上传批次,以斜杠开头和结尾',
model_glb_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '整机GLB环境相对路径,不含域名和环境根目录',
model_glb_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '整机GLB文件大小,单位字节',
model_parts_prefix VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '零件模型环境相对目录,以斜杠开头和结尾',
model_parts_files JSON NOT NULL DEFAULT (JSON_ARRAY()) COMMENT '零件GLB文件清单,包含relativePath和sizeBytes',
assembly_json_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '拼装步骤JSON环境相对路径,不含域名和环境根目录',
assembly_json_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '拼装步骤JSON文件大小,单位字节',
walking_resources_prefix VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '行走资源环境相对目录,以斜杠开头和结尾',
walking_resources_files JSON NOT NULL DEFAULT (JSON_ARRAY()) COMMENT '行走资源文件清单,包含relativePath和sizeBytes',
project_type VARCHAR(64) NOT NULL COMMENT '配置中的项目类型编码',
gitea_repo_id BIGINT NULL COMMENT 'Gitea 仓库标识',
gitea_owner VARCHAR(100) NOT NULL COMMENT 'Gitea 仓库所属组织',
+28
View File
@@ -195,6 +195,12 @@ export interface ProjectType {
name: string;
}
export interface ResourceFileView {
relativePath: string;
sizeBytes: number;
url: string; // 已编码的完整公开地址
}
export interface Project {
projectCode: string;
name: string;
@@ -202,6 +208,12 @@ export interface Project {
coverUrl: string | null; // 固定公开 HTTPS 图片地址,支持 OSS/CDN 和外部图片
urdfMainUrl: string | null; // 当前 URDF 主文件公开地址,无资源时为 null
urdfBaseUrl: string | null; // 当前资源包公开目录地址,以 / 结尾,无资源时为 null
modelGlbUrl: string | null;
modelPartsBaseUrl: string | null; // 目录地址以 / 结尾
modelPartsFiles?: ResourceFileView[]; // 详情始终返回,列表省略
assemblyJsonUrl: string | null;
walkingResourcesBaseUrl: string | null;
walkingResourcesFiles?: ResourceFileView[]; // 详情始终返回,列表省略
projectType: string;
owner: PublicUser;
repoStatus: 'CREATING' | 'READY' | 'FAILED';
@@ -300,6 +312,12 @@ export interface Comment {
"coverUrl": "https://images.example.com/vibemake/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png",
"urdfMainUrl": null,
"urdfBaseUrl": null,
"modelGlbUrl": null,
"modelPartsBaseUrl": null,
"modelPartsFiles": [],
"assemblyJsonUrl": null,
"walkingResourcesBaseUrl": null,
"walkingResourcesFiles": [],
"projectType": "GENERAL",
"owner": {
"userCode": "111111111111",
@@ -698,6 +716,16 @@ async function clearProjectUrdf(projectCode: string, token: string) {
}
```
## 管理员配置的模型、拼装及行走资源
`GET /api/workspace/projects/{projectCode}` 和 `GET /api/community/projects/{projectCode}` 返回当前绑定的整机 GLB、零件目录及清单、拼装步骤 JSON、行走资源目录及清单,字段见 Project 定义。未绑定时地址为 null,文件清单为 `[]`。列表保留四类资源地址,但省略两个文件清单;需要加载零件或行走资源时请求详情。
直接使用 `modelGlbUrl` 加载整机、`assemblyJsonUrl` 读取步骤 JSON,文件夹逐项使用清单中的 `url`,不需要列举 OSS 目录。`relativePath` 保留子目录及文件名大小写,目录地址以 `/` 结尾,URL 已编码,不要再次整体编码。行走资源不保证含 `robot.json`,需要由使用方自行识别;后端不校验拼装 JSON 的业务结构。
这四类资源只由管理端上传、替换和清除,用户端不提供上传接口,项目创建或 PATCH 也不接收对应资源字段。管理端成功确认后立即更新社区详情,不依赖仓库发布版本。
Fork 直接继承这四类资源的数据库字段和原资源地址,不访问 OSS,不复制或下载这些文件,因此大资源不会增加 Fork 的文件传输耗时。来源和副本独立保存绑定,任一方替换、清除或删除项目都不会改变另一方的绑定;旧 OSS 对象保留。URDF 继续按照上一节规则独立复制。
## 目录和文件读取
### 工作区目录