项目新增URDF字段
This commit is contained in:
@@ -13,6 +13,7 @@
|
||||
- [类型与项目列表](#类型与项目列表)
|
||||
- [我的项目管理](#我的项目管理)
|
||||
- [项目封面与 OSS 直传](#项目封面与-oss-直传)
|
||||
- [项目 URDF 文件夹](#项目-urdf-文件夹)
|
||||
- [目录和文件读取](#目录和文件读取)
|
||||
- [文件编辑与上传提交](#文件编辑与上传提交)
|
||||
- [社区发布和撤回](#社区发布和撤回)
|
||||
@@ -110,6 +111,9 @@ Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。
|
||||
| GET | `/api/workspace/projects/{projectCode}` | 是 | Project |
|
||||
| PATCH | `/api/workspace/projects/{projectCode}` | 是 | Project |
|
||||
| DELETE | `/api/workspace/projects/{projectCode}` | 是 | null |
|
||||
| POST | `/api/workspace/projects/{projectCode}/urdf/signature` | 是 | UrdfUploadSignature |
|
||||
| PUT | `/api/workspace/projects/{projectCode}/urdf` | 是 | Project |
|
||||
| DELETE | `/api/workspace/projects/{projectCode}/urdf` | 是 | null |
|
||||
| GET | `/api/workspace/projects/{projectCode}/tree` | 是 | Tree |
|
||||
| GET | `/api/workspace/projects/{projectCode}/files` | 是 | ProjectFile 或下载二进制 |
|
||||
| POST | `/api/workspace/projects/{projectCode}/commits` | 是 | Commit |
|
||||
@@ -185,6 +189,8 @@ export interface Project {
|
||||
name: string;
|
||||
description: string;
|
||||
coverUrl: string | null; // 固定公开 HTTPS 图片地址,支持 OSS/CDN 和外部图片
|
||||
urdfMainUrl: string | null; // 当前 URDF 主文件公开地址,无资源时为 null
|
||||
urdfBaseUrl: string | null; // 当前资源包公开目录地址,以 / 结尾,无资源时为 null
|
||||
projectType: string;
|
||||
owner: PublicUser;
|
||||
repoStatus: 'CREATING' | 'READY' | 'FAILED';
|
||||
@@ -208,6 +214,23 @@ export interface CoverUploadSignature {
|
||||
formFields: Record<string, string>;
|
||||
}
|
||||
|
||||
export interface UrdfFile {
|
||||
relativePath: string;
|
||||
sizeBytes: number;
|
||||
}
|
||||
|
||||
export interface UrdfUploadSignature {
|
||||
batchCode: string;
|
||||
mainRelativePath: string;
|
||||
uploadUrl: string;
|
||||
expiresAt: UtcDateTime; // 无时区后缀,按 UTC 解释
|
||||
files: Array<{
|
||||
relativePath: string;
|
||||
objectKey: string;
|
||||
formFields: Record<string, string>;
|
||||
}>;
|
||||
}
|
||||
|
||||
export interface TreeEntry {
|
||||
path: string; // 从仓库根目录开始的完整相对路径
|
||||
name: string;
|
||||
@@ -262,6 +285,8 @@ export interface Comment {
|
||||
"name": "机器人示例项目",
|
||||
"description": "模型、配置和说明文件",
|
||||
"coverUrl": "https://images.example.com/vibemake/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png",
|
||||
"urdfMainUrl": null,
|
||||
"urdfBaseUrl": null,
|
||||
"projectType": "GENERAL",
|
||||
"owner": {
|
||||
"userCode": "11111111111111111111111111111111",
|
||||
@@ -292,6 +317,7 @@ export interface Comment {
|
||||
| sourceProjectCode / sourceCommitSha | Fork 来源及复制的源版本;普通新项目为 null |
|
||||
| liked | 当前请求用户是否点赞,匿名访问为 false |
|
||||
| coverUrl | 固定公开封面地址,null 时展示前端默认图;工作区、社区、Fork 和 AI 卡片共用此字段 |
|
||||
| urdfMainUrl / urdfBaseUrl | 当前 URDF 主文件与资源目录的公开地址,无资源时均为 null;工作区、社区、AI 卡片均返回,Fork 使用独立副本 |
|
||||
|
||||
工作区归属由 `owner.userCode` 判断,不存在 `workspaceCode`。`updatedAt` 不代表仓库最新提交时间。来源项目撤回或删除后,sourceProjectCode 仍可能存在,访问该来源的社区详情会返回 404。
|
||||
|
||||
@@ -545,6 +571,115 @@ OSS 控制台配置步骤:
|
||||
|
||||
协议参考:[OSS POST V4 签名](https://www.alibabacloud.com/help/en/oss/developer-reference/signature-version-4-recommend)、[服务端签名直传](https://www.alibabacloud.com/help/en/oss/user-guide/obtain-signature-information-from-the-server-and-upload-data-to-oss)。
|
||||
|
||||
## 项目 URDF 文件夹
|
||||
|
||||
URDF 为可选项目资源,不进入 Gitea,也不生成 Commit。先创建项目取得 `projectCode`,再选择整个文件夹直传 OSS。文件夹内必须恰好有一个 `.urdf` 文件(扩展名忽略大小写,可位于子目录);没有或多个都直接提示失败,无需用户手动选择主文件。前端提前检查,后端在签名、确认时独立校验。
|
||||
|
||||
保留所选文件夹内部层级:`relativePath` 去掉浏览器选择的最外层文件夹名称,以资源包根目录为基准;不要扁平化、重命名或改写 URDF 引用。例如 `robot-assets/urdf/robot.urdf` 对应 `urdf/robot.urdf`,`robot-assets/meshes/base.stl` 对应 `meshes/base.stl`。
|
||||
|
||||
### 获取 URDF 签名
|
||||
|
||||
`POST /api/workspace/projects/{projectCode}/urdf/signature`,需要登录且为项目所有者,项目必须 READY。JSON 请求:
|
||||
|
||||
```json
|
||||
{
|
||||
"files": [
|
||||
{"relativePath": "urdf/robot.urdf", "sizeBytes": 1234},
|
||||
{"relativePath": "meshes/base.stl", "sizeBytes": 5678},
|
||||
{"relativePath": "textures/base.png", "sizeBytes": 2048}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
成功 data 为 `UrdfUploadSignature`。`batchCode` 为后端生成的 32 位小写十六进制编码,`mainRelativePath` 自动识别。`uploadUrl` 为 OSS 表单上传地址;每个文件具有独立的 `objectKey`、`formFields`。签名有效 15 分钟,`expiresAt` 为所有文件签名的最早过期时间,响应禁止缓存。Policy 精确绑定对象键、文件声明大小、Content-Type 及成功状态 200,不允许客户端修改;MIME 由后端生成,主文件为 `application/xml`。
|
||||
|
||||
对象键为 `{环境根目录}/urdf/{projectCode}/{batchCode}/{relativePath}`:test 根目录为 `vibemake_dev`,prod 为 `vibemake`。每次签名产生新批次,不覆盖旧批次。将每个文件的 `formFields` 原样放入 FormData,最后追加该文件,再 POST 到 `uploadUrl`;不手动设置 multipart Content-Type,不携带平台 Authorization,OSS 成功应为 HTTP 200,响应体为空。
|
||||
|
||||
### 确认、替换和清除
|
||||
|
||||
全部文件上传成功后调用 `PUT /api/workspace/projects/{projectCode}/urdf`:
|
||||
|
||||
```json
|
||||
{
|
||||
"batchCode": "33333333333333333333333333333333",
|
||||
"files": [
|
||||
{"relativePath": "urdf/robot.urdf", "sizeBytes": 1234},
|
||||
{"relativePath": "meshes/base.stl", "sizeBytes": 5678},
|
||||
{"relativePath": "textures/base.png", "sizeBytes": 2048}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
提交签名响应的真实 `batchCode` 和最初的完整清单,不提交 URL、目录前缀或主文件对象键。后端重新识别唯一主文件,生成当前环境、本项目的路径,通过 OSS 核验所有文件存在且实际大小一致后,一次性保存资源记录。成功 data 为更新后的 Project,包含 `urdfMainUrl`、`urdfBaseUrl`;URL 已编码,前端不要再次整体编码。未确认、上传失败、取消或核验失败均不会替换原绑定。
|
||||
|
||||
替换重复执行“签名 → 直传 → 确认”,并发以最后一次成功确认生效。签名过期时重新申请新批次并重新上传,不修改旧签名。没有上传会话或后台任务查询接口。
|
||||
|
||||
`DELETE /api/workspace/projects/{projectCode}/urdf` 清空当前绑定,无请求体,成功 data 为 null;重复清除也成功,OSS 未开启时仍可清除。未上传、清除后 `urdfMainUrl`、`urdfBaseUrl` 都为 null。项目创建和 PATCH 请求不接收 URDF 字段。
|
||||
|
||||
URDF 替换或清除立即影响社区,不需要重新发布仓库。Fork 在创建时读取当前 URDF 并复制到新项目目录,复制成功后才返回 READY;失败响应包含新项目的 `projectCode`,按现有初始化失败规则核对。源项目后续替换、清除不影响 Fork。替换、清除、删除项目均不自动删除 OSS 对象,旧公开 URL 仍可读取;撤回社区也不使已知的公开资源 URL 失效。
|
||||
|
||||
### 限制、错误与部署
|
||||
|
||||
| 项目 | 默认值 |
|
||||
| --- | --- |
|
||||
| 单文件 | 50 MiB,`URDF_MAX_FILE_BYTES=52428800` |
|
||||
| 整包总量 | 200 MiB,`URDF_MAX_TOTAL_BYTES=209715200` |
|
||||
| 文件数量 | 500,`URDF_MAX_FILES=500` |
|
||||
| 对象键 | 最多 512 个 Java 字符且 UTF-8 最多 1023 字节;前缀占用也计入 |
|
||||
|
||||
URDF 直传不受仓库上传的 multipart 10 MiB / 52 MiB 限制影响。路径必须是唯一相对路径,不能包含绝对路径、空段、`.`、`..`、反斜杠、控制字符、`.git` 目录或冒号。系统不解析 URDF 语义、不执行 Xacro、不自动修复 `package://` 等引用;渲染器的资源解析由前端处理。
|
||||
|
||||
| HTTP / code | 提示与处理 |
|
||||
| --- | --- |
|
||||
| 400 URDF_MAIN_FILE_INVALID | 没有:文件夹中未找到 URDF 文件;多个:文件夹中存在多个 URDF 文件,请仅保留一个后重新上传 |
|
||||
| 400 BAD_REQUEST | 清单、路径、批次编码或字节数不合法 |
|
||||
| 400 URDF_FILE_MISSING | URDF 文件未上传完整,请重新上传 |
|
||||
| 400 URDF_FILE_SIZE_MISMATCH | URDF 文件大小不符,请重新上传 |
|
||||
| 401 UNAUTHORIZED / 404 NOT_FOUND | 登录或检查项目归属、删除状态 |
|
||||
| 409 CONFLICT | 项目尚未就绪,或 Fork 复制时源资源发生变化 |
|
||||
| 413 URDF_UPLOAD_TOO_LARGE | 文件数量或大小超过限制 |
|
||||
| 502 OSS_ERROR / 503 OSS_UNAVAILABLE | OSS 访问失败或未启用;保留原资源 |
|
||||
|
||||
复用封面的 OSS 凭据及公开基础地址配置。上线前先执行 [URDF 加字段 SQL](database.md#已有数据库增加项目-urdf)。RAM 用户增加当前环境 `urdf/*` 范围的 `oss:PutObject`、`oss:GetObject` 权限,用于上传、元信息核验和服务端复制;不需要开放整个 Bucket 写权限。对 URDF 目录配置公开读取或使用公开 CDN,并为真实前端 Origin 配置 POST、GET、HEAD 的 CORS。应用不修改 Bucket ACL 或版本控制配置。表单附带禁止覆盖参数;Bucket 已开启或暂停版本控制时 OSS 不保证该参数有效,按新批次上传且不要复用成功签名修改资源。
|
||||
|
||||
### 浏览器文件夹上传示例
|
||||
|
||||
页面使用 `<input type="file" webkitdirectory multiple>` 选择文件夹。以下示例复用本文的 `request` 方法;可直接展示抛出的错误消息,不提供主文件选择交互。
|
||||
|
||||
```ts
|
||||
async function uploadProjectUrdf(projectCode: string, selected: FileList, token: string) {
|
||||
const entries = Array.from(selected).map(file => {
|
||||
const path = file.webkitRelativePath || file.name;
|
||||
return { file, relativePath: file.webkitRelativePath ? path.slice(path.indexOf('/') + 1) : path };
|
||||
});
|
||||
const count = entries.filter(item => item.relativePath.toLowerCase().endsWith('.urdf')).length;
|
||||
if (count === 0) throw new Error('文件夹中未找到 URDF 文件');
|
||||
if (count > 1) throw new Error('文件夹中存在多个 URDF 文件,请仅保留一个后重新上传');
|
||||
const files: UrdfFile[] = entries.map(item => ({ relativePath: item.relativePath, sizeBytes: item.file.size }));
|
||||
const endpoint = `/workspace/projects/${encodeURIComponent(projectCode)}/urdf`;
|
||||
const signature = await request<UrdfUploadSignature>(`${endpoint}/signature`, {
|
||||
method: 'POST', token, body: { files },
|
||||
});
|
||||
const byPath = new Map(entries.map(item => [item.relativePath, item.file]));
|
||||
for (const item of signature.files) {
|
||||
const form = new FormData();
|
||||
for (const [key, value] of Object.entries(item.formFields)) form.append(key, value);
|
||||
form.append('file', byPath.get(item.relativePath)!);
|
||||
const uploaded = await fetch(signature.uploadUrl, { method: 'POST', body: form });
|
||||
if (uploaded.status !== 200) throw new Error(`URDF 上传失败:HTTP ${uploaded.status}`);
|
||||
}
|
||||
return request<Project>(endpoint, {
|
||||
method: 'PUT', token, body: { batchCode: signature.batchCode, files },
|
||||
});
|
||||
}
|
||||
|
||||
async function clearProjectUrdf(projectCode: string, token: string) {
|
||||
return request<null>(`/workspace/projects/${encodeURIComponent(projectCode)}/urdf`, {
|
||||
method: 'DELETE', token,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## 目录和文件读取
|
||||
|
||||
### 工作区目录
|
||||
@@ -1102,6 +1237,8 @@ const result = await chatAi(
|
||||
| 我的工作区 | users/me → workspace/projects,分别显示仓库状态和发布状态 |
|
||||
| 创建项目 | POST workspace/projects → 使用返回 projectCode 进入详情 → tree 获取当前版本 |
|
||||
| 上传封面 | uploads/project-covers/signature → 浏览器直接 POST OSS → 成功后将 coverUrl 写入项目创建或修改接口 |
|
||||
| 上传或替换 URDF | 校验文件夹唯一主文件 → urdf/signature → 全部文件直传 OSS → PUT urdf 确认绑定 |
|
||||
| 清除 URDF | DELETE urdf → 刷新项目详情 |
|
||||
| 文件编辑 | workspace 详情与 tree → files → 判断 editable → commits → 刷新版本、目录和文件 |
|
||||
| 上传文件 | tree 获取基准 SHA → uploads/commit → 刷新目录和当前版本 |
|
||||
| 发布或更新社区 | 获取最新工作区 SHA → publication → 刷新项目和社区页面 |
|
||||
|
||||
+24
-1
@@ -1,6 +1,6 @@
|
||||
# 数据库初始化
|
||||
|
||||
业务数据库名为 `community`,只包含以下四张表。由人工执行;应用不运行迁移或自动建表。以下 SQL 面向 MySQL 8。
|
||||
业务数据库名为 `community`,只包含以下四张表。由人工执行;应用不运行迁移或自动建表。以下 SQL 面向 MySQL 8.0.13 及以上(URDF JSON 默认值使用表达式)。
|
||||
|
||||
```sql
|
||||
CREATE DATABASE IF NOT EXISTS community CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
@@ -26,6 +26,9 @@ CREATE TABLE project (
|
||||
name VARCHAR(100) NOT NULL COMMENT '项目名称',
|
||||
description TEXT NOT NULL COMMENT '项目描述',
|
||||
cover_url VARCHAR(2048) NULL COMMENT '封面图片 HTTPS 地址',
|
||||
urdf_main_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'URDF主文件OSS对象键,不保存完整URL',
|
||||
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资源OSS目录前缀,包含环境根目录和上传批次,以斜杠结尾',
|
||||
project_type VARCHAR(64) NOT NULL COMMENT '配置中的项目类型编码',
|
||||
gitea_repo_id BIGINT NULL COMMENT 'Gitea 仓库标识',
|
||||
gitea_owner VARCHAR(100) NOT NULL COMMENT 'Gitea 仓库所属组织',
|
||||
@@ -92,3 +95,23 @@ ALTER TABLE project
|
||||
```
|
||||
|
||||
历史项目的封面为 NULL。字段保存固定公开地址,可以来自 OSS、CDN 或外部 HTTPS 图片;不存储临时签名下载地址。替换、清除封面和删除项目不会自动删除 OSS 对象,Fork 可能共用同一地址。
|
||||
|
||||
## 已有数据库增加项目 URDF
|
||||
|
||||
先在对应业务库手动执行以下 SQL,再部署应用;新建数据库已包含三个字段,不重复执行。不要在应用启动时自动迁移。
|
||||
|
||||
```sql
|
||||
ALTER TABLE project
|
||||
ADD COLUMN urdf_main_object_key VARCHAR(512)
|
||||
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
|
||||
COMMENT 'URDF主文件OSS对象键,不保存完整URL',
|
||||
ADD COLUMN urdf_files JSON NOT NULL DEFAULT (JSON_ARRAY())
|
||||
COMMENT 'URDF文件清单数组,元素包含relativePath和sizeBytes,相对路径以urdf_prefix为基准',
|
||||
ADD COLUMN urdf_prefix VARCHAR(512)
|
||||
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
|
||||
COMMENT 'URDF资源OSS目录前缀,包含环境根目录和上传批次,以斜杠结尾';
|
||||
```
|
||||
|
||||
未上传或已清除时,两个字符串均为 `''`,文件清单为 `[]`。每个项目只绑定一个当前资源包,包内必须恰好有一个 `.urdf`(忽略扩展名大小写)。清单包含全部文件,例如 `[{"relativePath":"urdf/robot.urdf","sizeBytes":1234},{"relativePath":"meshes/base.stl","sizeBytes":5678}]`。
|
||||
|
||||
前缀为 `{环境根目录}/urdf/{projectCode}/{batchCode}/`,主文件对象键为此前缀加主文件相对路径。数据库不保存完整 URL;接口根据 OSS/CDN 配置生成并编码 URL。替换、清除、删除项目不物理删除对象,公开旧链接仍可读取;Fork 复制到新项目的独立目录,不共用源前缀。URDF 不进入 Gitea、不生成 Commit,更新立即影响社区展示。
|
||||
|
||||
Reference in New Issue
Block a user