多视图请求 DTO 补齐字段级说明并重生成绑定

- Model3dMultiviewToModelRequest 每个字段补一行中文语义说明与取值范围
- 结构体补严格反序列化与组合校验归属的说明
- 重新生成 ts-rs TS 绑定，注释同步进 Model3dMultiviewToModelRequest.ts

packages/shared/src/contracts/model3d/multiview-to-model/Model3dMultiviewToModelRequest.ts

@@ -9,25 +9,91 @@ import type { Model3dTextureQuality } from '../common/Model3dTextureQuality';
 import type { Model3dTextureVersion } from '../common/Model3dTextureVersion';
 import type { Model3dMultiviewInputs } from './Model3dMultiviewInputs';
 
+/**
+ * 多视图生 3D 的请求：`inputs` 必填，其余生成参数可选。
+ *
+ * 严格反序列化：顶层与 `inputs` 分支都不接受未知字段，字段取值非法在反序列化阶段即拒绝；
+ * 组合合法性（模型能力、参数互斥）由 provider 侧提交前统一校验。
+ */
 export type Model3dMultiviewToModelRequest = {
+  /**
+   * 视图输入：`views` 直接给多视图，`taskId` 复用已有任务的视图数据。
+   */
   inputs: Model3dMultiviewInputs;
+  /**
+   * 模型版本；决定模型家族与可用的生成能力。
+   */
   model: Model3dModelVersion;
+  /**
+   * 模型随机种子；固定后可复现同一几何体。
+   */
   modelSeed?: bigint | null;
+  /**
+   * 贴图随机种子；固定后可复现同一贴图。
+   */
   textureSeed?: bigint | null;
+  /**
+   * 是否生成贴图；`false` 时只产出白模几何体。
+   */
   texture?: boolean | null;
+  /**
+   * 是否生成 PBR 材质；依赖贴图，`generateParts=true` 时必须为 `false`。
+   */
   pbr?: boolean | null;
+  /**
+   * 贴图质量；`fast` 必须显式配 `textureVersion=v3.5-20260815`。
+   */
   textureQuality?: Model3dTextureQuality | null;
+  /**
+   * 贴图模型版本；SDK params 未命名该字段，由 provider 侧按 extra 透传。
+   */
   textureVersion?: Model3dTextureVersion | null;
+  /**
+   * 是否去除输入图光照；SDK params 未命名该字段，由 provider 侧按 extra 透传。
+   */
   delight?: boolean | null;
+  /**
+   * 几何质量；仅 v3.1 / v3.0 家族接受 `detailed`。
+   */
   geometryQuality?: Model3dGeometryQuality | null;
+  /**
+   * 贴图对齐方式：`originalImage` 保留输入图朝向，`geometry` 对齐到几何体。
+   */
   textureAlignment?: Model3dTextureAlignment | null;
+  /**
+   * 面数上限；允许区间随模型版本、`quad` 与 `smartLowPoly` 变化，取值不超过 2_000_000。
+   */
   faceLimit?: number | null;
+  /**
+   * 是否按真实尺度自动缩放输出；v2.5 家族不支持。
+   */
   autoSize?: boolean | null;
+  /**
+   * 输入视图的朝向口径；`alignImage` 按图片方向对齐。
+   */
   orientation?: Model3dInputOrientation | null;
+  /**
+   * 是否输出四边面网格；仅 v3.x 与 P2 家族支持。
+   */
   quad?: boolean | null;
+  /**
+   * 是否启用智能低模；仅 v3.x 家族支持。
+   */
   smartLowPoly?: boolean | null;
+  /**
+   * 是否拆分模型部件；要求 `texture=false`、`pbr=false`，且不能与 `quad` / `smartLowPoly` 同用。
+   */
   generateParts?: boolean | null;
+  /**
+   * 几何体压缩方式；仅 v3.x 家族支持。
+   */
   compress?: Model3dCompression | null;
+  /**
+   * 是否在产物里导出 UV。
+   */
   exportUv?: boolean | null;
+  /**
+   * 产物朝向，取值 `+x` / `-x` / `+y` / `-y`。
+   */
   exportOrientation?: Model3dExportOrientation | null;
 };

server-rs/crates/shared-contracts/src/model3d/multiview_to_model/request.rs

@@ -42,47 +42,71 @@ pub enum Model3dMultiviewInputs {
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 #[derive(ts_rs::TS)]
 #[ts(export, export_to = MODEL3D_TS_EXPORT_DIR)]
+/// 多视图生 3D 的请求：`inputs` 必填，其余生成参数可选。
+///
+/// 严格反序列化：顶层与 `inputs` 分支都不接受未知字段，字段取值非法在反序列化阶段即拒绝；
+/// 组合合法性（模型能力、参数互斥）由 provider 侧提交前统一校验。
 pub struct Model3dMultiviewToModelRequest {
+    /// 视图输入：`views` 直接给多视图，`taskId` 复用已有任务的视图数据。
     pub inputs: Model3dMultiviewInputs,
+    /// 模型版本；决定模型家族与可用的生成能力。
     pub model: Model3dModelVersion,
     // seed 是 i64，JS `number` 表示不了全部取值，因此按 bigint 导出，避免静默舍入。
+    /// 模型随机种子；固定后可复现同一几何体。
     #[ts(type = "bigint | null")]
     #[ts(optional = nullable)]
     pub model_seed: Option<i64>,
+    /// 贴图随机种子；固定后可复现同一贴图。
     #[ts(type = "bigint | null")]
     #[ts(optional = nullable)]
     pub texture_seed: Option<i64>,
+    /// 是否生成贴图；`false` 时只产出白模几何体。
     #[ts(optional = nullable)]
     pub texture: Option<bool>,
+    /// 是否生成 PBR 材质；依赖贴图，`generateParts=true` 时必须为 `false`。
     #[ts(optional = nullable)]
     pub pbr: Option<bool>,
+    /// 贴图质量；`fast` 必须显式配 `textureVersion=v3.5-20260815`。
     #[ts(optional = nullable)]
     pub texture_quality: Option<Model3dTextureQuality>,
+    /// 贴图模型版本；SDK params 未命名该字段，由 provider 侧按 extra 透传。
     #[ts(optional = nullable)]
     pub texture_version: Option<Model3dTextureVersion>,
+    /// 是否去除输入图光照；SDK params 未命名该字段，由 provider 侧按 extra 透传。
     #[ts(optional = nullable)]
     pub delight: Option<bool>,
+    /// 几何质量；仅 v3.1 / v3.0 家族接受 `detailed`。
     #[ts(optional = nullable)]
     pub geometry_quality: Option<Model3dGeometryQuality>,
+    /// 贴图对齐方式：`originalImage` 保留输入图朝向，`geometry` 对齐到几何体。
     #[ts(optional = nullable)]
     pub texture_alignment: Option<Model3dTextureAlignment>,
+    /// 面数上限；允许区间随模型版本、`quad` 与 `smartLowPoly` 变化，取值不超过 2_000_000。
     #[ts(type = "number | null")]
     #[ts(optional = nullable)]
     pub face_limit: Option<i64>,
+    /// 是否按真实尺度自动缩放输出；v2.5 家族不支持。
     #[ts(optional = nullable)]
     pub auto_size: Option<bool>,
+    /// 输入视图的朝向口径；`alignImage` 按图片方向对齐。
     #[ts(optional = nullable)]
     pub orientation: Option<Model3dInputOrientation>,
+    /// 是否输出四边面网格；仅 v3.x 与 P2 家族支持。
     #[ts(optional = nullable)]
     pub quad: Option<bool>,
+    /// 是否启用智能低模；仅 v3.x 家族支持。
     #[ts(optional = nullable)]
     pub smart_low_poly: Option<bool>,
+    /// 是否拆分模型部件；要求 `texture=false`、`pbr=false`，且不能与 `quad` / `smartLowPoly` 同用。
     #[ts(optional = nullable)]
     pub generate_parts: Option<bool>,
+    /// 几何体压缩方式；仅 v3.x 家族支持。
     #[ts(optional = nullable)]
     pub compress: Option<Model3dCompression>,
+    /// 是否在产物里导出 UV。
     #[ts(optional = nullable)]
     pub export_uv: Option<bool>,
+    /// 产物朝向，取值 `+x` / `-x` / `+y` / `-y`。
     #[ts(optional = nullable)]
     pub export_orientation: Option<Model3dExportOrientation>,
 }