From 6db10796100eea9d3a7629b8d8d032ade2c15a4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Mon, 21 Sep 2026 12:29:29 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9ETripo=E7=94=9F=E6=88=90API?= =?UTF-8?q?=E7=9A=84=E9=87=8C=E7=A8=8B=E7=A2=91=E8=A7=84=E8=8C=83=E4=B8=8E?= =?UTF-8?q?=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92=20-=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E5=A5=91=E7=BA=A6=E4=B8=8E=E6=95=B0=E6=8D=AE=E6=A8=A1=E5=9E=8B?= =?UTF-8?q?=E9=87=8C=E7=A8=8B=E7=A2=91=EF=BC=8C=E9=94=81=E5=AE=9A=E8=8C=83?= =?UTF-8?q?=E5=9B=B4=E3=80=81=E4=B8=8D=E5=81=9A=E9=A1=B9=E4=B8=8E=E9=AA=8C?= =?UTF-8?q?=E6=94=B6=E6=A0=87=E5=87=86=20-=20=E6=96=B0=E5=A2=9E=20Worker?= =?UTF-8?q?=20=E6=89=A7=E8=A1=8C=E9=93=BE=E8=B7=AF=E4=B8=8E=20API=20?= =?UTF-8?q?=E8=B7=AF=E7=94=B1=E9=87=8C=E7=A8=8B=E7=A2=91=EF=BC=8C=E6=A0=87?= =?UTF-8?q?=E6=B3=A8=20pending=20=E4=B8=8E=E5=AE=9A=E4=BB=B7=E5=89=8D?= =?UTF-8?q?=E7=BD=AE=E4=BE=9D=E8=B5=96=20-=20=E6=96=B0=E5=A2=9E=E5=A5=91?= =?UTF-8?q?=E7=BA=A6=E9=87=8C=E7=A8=8B=E7=A2=91=E5=AE=9E=E6=96=BD=E8=AE=A1?= =?UTF-8?q?=E5=88=92=EF=BC=8C=E5=9B=BA=E5=AE=9A=E6=AD=A5=E9=AA=A4=E9=A1=BA?= =?UTF-8?q?=E5=BA=8F=E3=80=81=E9=AA=8C=E8=AF=81=E5=91=BD=E4=BB=A4=E4=B8=8E?= =?UTF-8?q?=E5=9B=9E=E9=80=80=E8=8C=83=E5=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...划】Tripo生成API契约与数据模型-2026-09-21.md | 64 +++++++++++++++++++ ...碑】Tripo生成API契约与数据模型-2026-09-21.md | 43 +++++++++++++ ...Tripo生成Worker执行链路与API路由-2026-09-21.md | 36 +++++++++++ 3 files changed, 143 insertions(+) create mode 100644 docs/project-memory/plans/【实施计划】Tripo生成API契约与数据模型-2026-09-21.md create mode 100644 docs/project-memory/plans/【里程碑】Tripo生成API契约与数据模型-2026-09-21.md create mode 100644 docs/project-memory/plans/【里程碑】Tripo生成Worker执行链路与API路由-2026-09-21.md diff --git a/docs/project-memory/plans/【实施计划】Tripo生成API契约与数据模型-2026-09-21.md b/docs/project-memory/plans/【实施计划】Tripo生成API契约与数据模型-2026-09-21.md new file mode 100644 index 000000000..fafbb825f --- /dev/null +++ b/docs/project-memory/plans/【实施计划】Tripo生成API契约与数据模型-2026-09-21.md @@ -0,0 +1,64 @@ +# Tripo 生成 API 契约与数据模型实施计划 + +Version: 1.0 +Status: active +Date: 2026-09-21 +Milestone Spec: `docs/project-memory/plans/【里程碑】Tripo生成API契约与数据模型-2026-09-21.md` + +## 步骤 + +1. **API 契约** + - `shared-contracts::model3d` 分两层：provider 生成参数（`Model3dTextToModelParams` / `Model3dImageToModelParams`）与 API 层请求（`Model3dTextToModelRequest` / `Model3dImageToModelRequest` = `generation` + 平台字段 + `target`）。 + - 两层都保持 `deny_unknown_fields`，不使用 `flatten`：serde 的 `deny_unknown_fields` 与 `flatten` 不兼容，展开会让顶层未知字段静默通过。 + - `common/` 新增平台字段类型：`Model3dGenerationSource`（resource / asset 二选一）、`Model3dGenerationTarget`（projectResource / assetLibrary 二选一，画布占位框复用既有载荷）、结果落点引用与产物元数据类型。 + - 图片输入不属于 provider 参数：客户端只能给 `source`，`input` 由服务端解析后注入 provider 调用，避免绕过归属校验传任意 URL。 + - 新增按端点的严格结果 payload 类型（模型 artifact + 预览 artifact），二者都只携带正式资源引用与对象元数据。 + - 交付：类型定义、serde 组合测试（缺 `folderId` / `label` / `projectId` 拒绝，`source` 两个 ID 同现拒绝）。 + - 验收：`cargo test --locked -p shared-contracts --manifest-path server-rs/Cargo.toml` 通过。 + +2. **ts-rs 目录绑定** + - 目录常量沿用 `model3d_ts_export_dir!`，新类型导出到既有 `packages/shared/src/contracts/model3d/` 子目录，更新 `index.ts` 导出。 + - 交付：`npm run contracts:model3d:generate` 后对生成目录执行 prettier。 + - 验收：生成产物与 Rust 类型一致，`packages/shared` barrel 可引用新类型。 + +3. **provider checkpoint 数据模型** + - `spacetime-module/src/external_generation.rs` 在 `ExternalGenerationJob` 结构体末尾追加 `providerKind`、`providerTaskId`（显式默认值），同步各 snapshot / mapper。 + - 新增受租约栅栏保护的 checkpoint 写入 procedure，并在 `spacetime-client` 增加对应 facade 方法与错误映射。 + - 交付：`migration.rs`、表目录与生成绑定同步。 + - 验收：`npm run check:spacetime-schema` 通过；新 procedure 对过期租约与错误 lease token 返回拒绝。 + +4. **泥点定价结构** + - `api-server/src/editor_generation_config.rs` 增加 `model3d` 段：底价按 `endpoint × modelVersion × 是否有贴图`，add-on 按固定键表；`validate` 要求两个端点 × 每个受支持模型版本 × 两种贴图态全部存在。 + - 新增价格解析函数：输入端点、模型版本、贴图态与命中的 add-on 集合，返回泥点价格；缺键返回错误，不回退默认值。 + - 默认配置文件的生产数值待业务提供；在此之前只落地结构与校验，配置测试使用测试夹具，不写入臆测价格。 + - 验收：缺键加载失败、add-on 命中断言、`fast` / `standard` 不加价的单测通过。 + +5. **组合校验规则** + - 平台规则（定价相关参数必填、`texture=false` 禁止 `textureQuality` 且要求 `pbr=false`、`texture=true` 要求 `textureQuality`）落在 `api-server/src/tripo3d/validation.rs`。 + - provider 能力组合规则（模型档位 × 贴图/几何/quad/smart-low-poly/generate-parts 的互斥与取值范围）不复制，改为复用 `platform-tripo` 暴露的请求校验入口，作为唯一真相源。 + - 校验在调用任何 provider 方法与扣费之前执行；provider 抛出的参数错误按字段映射为 400。 + - 验收：非法组合单测覆盖平台规则与 provider 规则各一例。 + +6. **文档同步** + - 主规范、里程碑规范、ADR 已在本次一并落地；表目录文档同步新字段。 + - 验收：`node scripts/check-doc-index.mjs` 通过。 + +## 验证命令 + +```bash +cargo test --locked -p shared-contracts --manifest-path server-rs/Cargo.toml +cargo check --locked -p platform-tripo --manifest-path server-rs/Cargo.toml +npm run contracts:model3d:generate +npm run check:spacetime-schema +npm run check:encoding +node scripts/check-doc-index.mjs +git diff --check +``` + +## 风险与回退 + +- **共用队列表加列**：字段追加在末尾并带默认值，旧行可读；回退只需停止读取新列，不执行字段删除。 +- **定价数值未定**：结构可以先落地，但接口在真实价格写入前不得开放；里程碑二以此为前置依赖。 +- **契约目录扩张**：新类型只落在 `model3d` 既有目录内，不引入新的顶层契约目录，避免 barrel 维护成本上升。 +- **回退点**：本里程碑不新增路由、不改 worker 分支，回退范围为契约、schema 追加字段与定价结构三处。 + diff --git a/docs/project-memory/plans/【里程碑】Tripo生成API契约与数据模型-2026-09-21.md b/docs/project-memory/plans/【里程碑】Tripo生成API契约与数据模型-2026-09-21.md new file mode 100644 index 000000000..68b83f251 --- /dev/null +++ b/docs/project-memory/plans/【里程碑】Tripo生成API契约与数据模型-2026-09-21.md @@ -0,0 +1,43 @@ +# Tripo 生成 API 契约与数据模型 + +Version: 1.0 +Status: active +Date: 2026-09-21 +Parent Spec: `docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md` + +## 目标 + +在动手做路由与 worker 之前，把 Tripo 生成 API 的请求与结果契约、provider checkpoint 的数据模型、泥点定价结构与组合校验先固定下来，让后续执行链路只依赖已评审的契约。 + +## 范围 + +- `shared-contracts::model3d` 新增 API 层请求与结果类型：provider 生成参数与 API 请求分层，图片输入 `source` tagged enum、结果落点 `target` tagged enum、按端点的严格结果类型。 +- `external_generation_job` 追加 `providerKind` / `providerTaskId`，并新增受租约栅栏保护的 checkpoint 写入 procedure 与 `spacetime-client` facade。 +- 定价配置新增 `model3d` 段：底价按 `endpoint × modelVersion × 是否有贴图`，add-on 按参数判定叠加，加载即校验全部底价键存在。 +- 定价相关参数的必填口径与组合校验规则，前置于 provider 副作用；provider 能力组合规则复用 `platform-tripo` 校验入口，不复制第二份。 +- ts-rs 目录化 TypeScript binding 与导出索引。 + +## 不做 + +- 不新增 HTTP 路由，不改 worker 任务分支。 +- 不接前端与 `packages/model3d-viewer`。 +- 不动 `platform-hyper3d` 与 `/api/assets/hyper3d/*`。 +- 不提供生产定价数值；数值由业务给出后写入默认配置。 +- 不改 `platform-oss` 为流式上传。 + +## 验收标准 + +1. API 请求与结果契约可编译，并通过 ts-rs 生成到 `packages/shared/src/contracts/model3d/` 的对应目录；生成产物经 prettier 后提交。 +2. `target` 的 `assetLibrary` 分支缺少 `folderId` 或 `label` 时反序列化即失败；`projectResource` 分支缺少 `projectId` 同理。 +3. `source` 同时给出两个 ID、或使用裸字符串时被拒绝。 +4. `external_generation_job` 新字段追加在结构体末尾且带显式默认值；`migration.rs`、表目录与生成绑定同步，`npm run check:spacetime-schema` 通过。 +5. checkpoint procedure 只在租约有效且 lease token 匹配时写入；过期或错误 token 被拒。 +6. 定价配置缺少任一底价键时加载失败；add-on 判定对贴图四档、几何质量、quad、smart-low-poly、generate-parts 均有单测覆盖，且 `fast` / `standard` 不加价。 +7. 组合校验拒绝 `texture=false` 同现 `textureQuality`（平台规则）与 `generateParts=true` 同现 `texture=true`（provider 规则）等非法组合，且校验发生在任何 provider 调用与扣费之前。 +8. `npm run check:encoding`、`node scripts/check-doc-index.mjs`、`git diff --check` 通过。 + +## 依赖 + +- 主规范 `docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md`。 +- 现有 `platform-tripo` provider DTO 与组合校验（`platform-tripo/src/common/validation.rs`）。 +- 现有定价配置与校验入口（`api-server/src/editor_generation_config.rs`）。 diff --git a/docs/project-memory/plans/【里程碑】Tripo生成Worker执行链路与API路由-2026-09-21.md b/docs/project-memory/plans/【里程碑】Tripo生成Worker执行链路与API路由-2026-09-21.md new file mode 100644 index 000000000..e2e2bdbcf --- /dev/null +++ b/docs/project-memory/plans/【里程碑】Tripo生成Worker执行链路与API路由-2026-09-21.md @@ -0,0 +1,36 @@ +# Tripo 生成 Worker 执行链路与 API 路由 + +Version: 1.0 +Status: pending +Date: 2026-09-21 +Parent Spec: `docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md` + +## 目标 + +把已固定的契约接到执行链路上：两个 submit 内部 API 完成校验、定价与入队，worker 按 at-most-once submit 规则推进 Tripo 任务，完成后把模型与预览落 OSS 并登记为正式资源，全程真实扣费与失败退款。 + +## 范围 + +- 两个 Bearer 路由：`/api/assets/tripo/text-to-model`、`/api/assets/tripo/image-to-model`，含 `Idempotency-Key` 校验与错误映射。 +- 两个 Tripo job kind 的 worker 分支：submit、单次 `get_task` 轮询、下载、OSS 写入、资源登记、严格结果序列化。 +- checkpoint 规则：无 checkpoint 才 submit，submit 成功后先落 checkpoint 再轮询，已有 checkpoint 只续跑；submit 成功但 checkpoint 落库失败的 attempt 终态失败。 +- 图片输入的归属校验与 OSS 对象解析；结果落点的两个分支。 +- 提交时定价扣费、attempt 级退款、幂等重放不重复扣费。 +- 真实 Provider smoke 与端到端验收证据。 + +## 不做 + +- 不接 multiview、Splat、rig 等其它能力。 +- 不做取消接口。 +- 不进入 `/api/external/v1`。 +- 不接前端与查看器。 + +## 验收标准 + +主规范“验收标准”第 1 至 11 条全部满足，其中必须包含 text-to-model 与 image-to-model 各一次真实 Provider 调用与产物下载校验。 + +## 依赖 + +- `docs/project-memory/plans/【里程碑】Tripo生成API契约与数据模型-2026-09-21.md` 验收通过。 +- 生产泥点定价数值已确认并写入默认配置。 +