From 800da43a8d330c2c1d0ce7bf4bd064636f4cc341 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Sat, 19 Sep 2026 14:14:14 +0800 Subject: [PATCH] =?UTF-8?q?=E8=AF=B4=E6=98=8E=E7=94=9F=E6=88=90=E7=BB=93?= =?UTF-8?q?=E6=9E=9C=20DTO=20=E7=9A=84=20number=20=E7=B2=BE=E5=BA=A6?= =?UTF-8?q?=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 为 poll_after_ms、updated_at_micros、size_bytes 补充注释，说明其量级远低于 2^53，按 TS number 导出即可精确表示 重新生成 TypeScript 绑定，把上述说明同步为 JSDoc 技术方案补充同一说明，明确不做 bigint/string 特殊处理 --- .../【技术方案】Tripo文本到3D模型Provider集成-2026-09-18.md | 2 ++ .../src/contracts/model3d/text-to-model/Model3dArtifact.ts | 3 +++ .../contracts/model3d/text-to-model/Model3dGenerationJob.ts | 3 +++ .../model3d/text-to-model/Model3dGenerationSubmission.ts | 3 +++ .../shared-contracts/src/model3d/text_to_model/response.rs | 3 +++ 5 files changed, 14 insertions(+) diff --git a/docs/technical/【技术方案】Tripo文本到3D模型Provider集成-2026-09-18.md b/docs/technical/【技术方案】Tripo文本到3D模型Provider集成-2026-09-18.md index 5c59eb64f..8d909d1ec 100644 --- a/docs/technical/【技术方案】Tripo文本到3D模型Provider集成-2026-09-18.md +++ b/docs/technical/【技术方案】Tripo文本到3D模型Provider集成-2026-09-18.md @@ -20,6 +20,8 @@ provider task 结果与产品资源结果分离。provider adapter 不生成 `re task 尚未完成时 `output` 为空；完成后 `output` 必须是与 task type 一致的 enum variant，不使用把不同 endpoint 字段揉在一起的通用可选字段结构。真实 provider smoke 确认：text-to-model 结果固定包含 `model_url`、`rendered_image_url`、`generated_image_url`；image-to-model 和 multiview-to-model 结果固定包含 `model_url`、`rendered_image_url`。这些字段在各自结果 struct 中均为必填 `TripoUrl`；缺失、URL 非法或 task type 不受支持时返回 `TripoError::OutputSchema`。 +生成结果 DTO 中的 `poll_after_ms`、`updated_at_micros` 与 `size_bytes` 以 TypeScript `number` 导出：毫秒级轮询间隔与几十 MB 的产物字节数远低于 2^53，微秒时间戳在 2^53 内也可精确表示（约到公元 2255 年），因此不做 `bigint`/`string` 特殊处理；若将来出现超过 2^53 的取值再评估。 + ## 请求与类型 三个生成请求使用官方文档已确认的 enum：模型版本、纹理版本、纹理质量（含 `fast`）、几何质量、纹理对齐、输入方向、导出方向和压缩类型（`geometry`）。文档未将 `style` 列为这三个 endpoint 的请求字段，因此不再保留占位 enum。请求可选字段在 Rust 侧为 `Option`，TypeScript 绑定对应 `field?: T | null`，调用方既可省略字段也可显式传 `null`。TypeScript 绑定仍按目录生成到 `packages/shared/src/contracts/model3d/`，并由该目录的 `index.ts` 与 `packages/shared` 的 barrel 统一再导出；生成命令 `npm run contracts:model3d:generate` 写入的是未格式化的 ts-rs 输出，需再执行 `prettier --write packages/shared/src/contracts/model3d` 后提交。 diff --git a/packages/shared/src/contracts/model3d/text-to-model/Model3dArtifact.ts b/packages/shared/src/contracts/model3d/text-to-model/Model3dArtifact.ts index d3fed8219..041d131d0 100644 --- a/packages/shared/src/contracts/model3d/text-to-model/Model3dArtifact.ts +++ b/packages/shared/src/contracts/model3d/text-to-model/Model3dArtifact.ts @@ -5,6 +5,9 @@ export type Model3dArtifact = { resourceId: string; format: Model3dOutputFormat; contentType: string; + /** + * 产物字节数，当前单模型产物为几十 MB，远低于 2^53，按 TS number 导出。 + */ sizeBytes: number; sha256: string; previewResourceId?: string | null; diff --git a/packages/shared/src/contracts/model3d/text-to-model/Model3dGenerationJob.ts b/packages/shared/src/contracts/model3d/text-to-model/Model3dGenerationJob.ts index 510b02868..9c5298c71 100644 --- a/packages/shared/src/contracts/model3d/text-to-model/Model3dGenerationJob.ts +++ b/packages/shared/src/contracts/model3d/text-to-model/Model3dGenerationJob.ts @@ -9,5 +9,8 @@ export type Model3dGenerationJob = { progress: number; error?: string | null; result?: Model3dGenerationResult | null; + /** + * 更新时间（Unix 微秒）；2^53 微秒约到公元 2255 年，按 TS number 导出即可精确表示。 + */ updatedAtMicros: number; }; diff --git a/packages/shared/src/contracts/model3d/text-to-model/Model3dGenerationSubmission.ts b/packages/shared/src/contracts/model3d/text-to-model/Model3dGenerationSubmission.ts index dcd97a66a..75f27282d 100644 --- a/packages/shared/src/contracts/model3d/text-to-model/Model3dGenerationSubmission.ts +++ b/packages/shared/src/contracts/model3d/text-to-model/Model3dGenerationSubmission.ts @@ -5,5 +5,8 @@ export type Model3dGenerationSubmission = { operationId: string; status: Model3dTaskStatus; statusUrl: string; + /** + * 轮询间隔（毫秒），量级为分钟级，远低于 2^53，按 TS number 导出。 + */ pollAfterMs: number; }; diff --git a/server-rs/crates/shared-contracts/src/model3d/text_to_model/response.rs b/server-rs/crates/shared-contracts/src/model3d/text_to_model/response.rs index 0427d946b..6f562b0bf 100644 --- a/server-rs/crates/shared-contracts/src/model3d/text_to_model/response.rs +++ b/server-rs/crates/shared-contracts/src/model3d/text_to_model/response.rs @@ -12,6 +12,7 @@ pub struct Model3dGenerationSubmission { pub operation_id: String, pub status: Model3dTaskStatus, pub status_url: String, + /// 轮询间隔（毫秒），量级为分钟级，远低于 2^53，按 TS number 导出。 #[ts(type = "number")] pub poll_after_ms: u64, } @@ -29,6 +30,7 @@ pub struct Model3dGenerationJob { pub error: Option, #[serde(default, skip_serializing_if = "Option::is_none")] pub result: Option, + /// 更新时间（Unix 微秒）；2^53 微秒约到公元 2255 年，按 TS number 导出即可精确表示。 #[ts(type = "number")] pub updated_at_micros: i64, } @@ -51,6 +53,7 @@ pub struct Model3dArtifact { pub resource_id: String, pub format: Model3dOutputFormat, pub content_type: String, + /// 产物字节数，当前单模型产物为几十 MB，远低于 2^53，按 TS number 导出。 #[ts(type = "number")] pub size_bytes: u64, pub sha256: String,