From 931be509f17d363d80f10ba74fdd5d63434193ac 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 13:59:53 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E8=AE=B0Tripo=20model3d=E7=9A=84asset?= =?UTF-8?q?Kind=E6=8E=A5=E5=85=A5=E6=B8=85=E5=8D=95=E5=AF=B9=E7=85=A7=20-?= =?UTF-8?q?=20=E4=B8=BB=E8=A7=84=E8=8C=83=E6=96=B0=E5=A2=9E=20assetKind=20?= =?UTF-8?q?=E6=8E=A5=E5=85=A5=E6=B8=85=E5=8D=95=E5=AF=B9=E7=85=A7=E8=A1=A8?= =?UTF-8?q?=EF=BC=8C=E9=80=90=E8=A1=8C=E7=99=BB=E8=AE=B0=E5=90=8E=E7=AB=AF?= =?UTF-8?q?-only=20=E7=B1=BB=E5=88=AB=E7=9A=84=E8=A7=A6=E7=A2=B0=E7=82=B9?= =?UTF-8?q?=E5=8F=A3=E5=BE=84=20-=20=E4=B8=BB=E8=A7=84=E8=8C=83=E6=98=8E?= =?UTF-8?q?=E7=A1=AE=E5=8E=9F=E5=AD=90=E8=90=BD=E5=BA=93=20operation=5Fkin?= =?UTF-8?q?d=20=E7=99=BD=E5=90=8D=E5=8D=95=E5=BF=85=E9=A1=BB=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=E4=B8=A4=E4=B8=AA=20Tripo=20job=20kind=EF=BC=8C?= =?UTF-8?q?=E7=94=BB=E5=B8=83=E5=9B=9E=E5=A1=AB=E5=8F=AA=E8=B5=B0=20placem?= =?UTF-8?q?ent-only=20-=20=E4=B8=BB=E8=A7=84=E8=8C=83=E7=99=BB=E8=AE=B0?= =?UTF-8?q?=E7=94=A8=E6=88=B7=E6=A0=87=E7=AD=BE=E8=A6=86=E7=9B=96=E3=80=81?= =?UTF-8?q?=E5=BF=AB=E9=80=9F=E7=BC=96=E8=BE=91=E4=B8=8E=E6=94=B9=E9=80=A0?= =?UTF-8?q?=20capability=20=E4=B8=89=E9=A1=B9=E7=BB=93=E8=AE=BA=E5=9D=87?= =?UTF-8?q?=E4=B8=BA=E4=B8=8D=E8=BF=9B=E5=85=A5=EF=BC=8C=E5=B9=B6=E5=86=99?= =?UTF-8?q?=E6=98=8E=E5=90=8E=E7=BB=AD=E6=8E=A5=E5=89=8D=E7=AB=AF=E9=9C=80?= =?UTF-8?q?=E9=87=8D=E8=AF=84=20-=20=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92?= =?UTF-8?q?=E6=8A=8A=20provider=20=E9=85=8D=E7=BD=AE=E6=96=87=E4=BB=B6?= =?UTF-8?q?=E8=A1=8C=E6=9B=B4=E6=AD=A3=E4=B8=BA=20provider.rs=EF=BC=8C?= =?UTF-8?q?=E5=B9=B6=E5=9C=A8=E4=BA=A7=E7=89=A9=E8=90=BD=E5=BA=93=E6=AD=A5?= =?UTF-8?q?=E9=AA=A4=E8=A1=A5=E7=99=BD=E5=90=8D=E5=8D=95=E4=B8=8E=20placem?= =?UTF-8?q?ent=20=E5=8F=A3=E5=BE=84=E9=AA=8C=E6=94=B6=20-=20=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=E6=9E=B6=E6=9E=84=E6=96=87=E6=A1=A3=E8=A1=A5=E5=85=85?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=EF=BC=9A=E4=B8=8D=E8=B5=B0=E7=BC=96=E8=BE=91?= =?UTF-8?q?=E5=99=A8=E5=89=8D=E7=AB=AF=E7=9A=84=E7=94=9F=E6=88=90=E7=B1=BB?= =?UTF-8?q?=E5=88=AB=E5=90=8C=E6=A0=B7=E9=80=82=E7=94=A8=E6=B8=85=E5=8D=95?= =?UTF-8?q?=EF=BC=8C=E4=B8=8D=E8=83=BD=E9=9D=A0=E6=97=A0=E5=89=8D=E7=AB=AF?= =?UTF-8?q?=E5=85=A5=E5=8F=A3=E8=B7=B3=E8=BF=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...】Tripo生成Worker执行链路与API路由-2026-09-21.md | 4 +++- ...技术方案】Tripo 3D生成API集成-2026-09-21.md | 17 +++++++++++++++++ ...构】server-rs与SpacetimeDB数据契约-2026-05-15.md | 1 + 3 files changed, 21 insertions(+), 1 deletion(-) 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 index 24c2335e4..4fcefa4ce 100644 --- a/docs/project-memory/plans/【实施计划】Tripo生成Worker执行链路与API路由-2026-09-21.md +++ b/docs/project-memory/plans/【实施计划】Tripo生成Worker执行链路与API路由-2026-09-21.md @@ -19,7 +19,7 @@ Milestone Spec: `docs/project-memory/plans/【里程碑】Tripo生成Worker执 | `tripo3d/routes.rs` | 两个 POST 处理入口与执行顺序（解析 → 校验 → 定价 → 入队） | | `tripo3d/errors.rs` | `Model3dRequestError`、`TripoError` 到 HTTP 的映射 | | `tripo3d/image_source.rs` | `source` 分支归属校验与 provider 图片输入解析 | -| `tripo3d/config.rs` | 从 `AppConfig` 构造 `TripoSettings` 与 provider client，缺配置即拒绝 | +| `tripo3d/provider.rs` | 从 `AppConfig` 构造 `TripoSettings` 与 provider client，缺配置即拒绝 | | `tripo3d/artifacts.rs` | provider 产物下载、OSS 写入与产物元数据 | | `tripo3d/result.rs` | 按端点构造严格结果与落点引用，写 `result_payload_json` | | `tripo3d/worker.rs` | checkpoint 判定、submit、轮询、下载落库与 job 收口 | @@ -50,6 +50,8 @@ Milestone Spec: `docs/project-memory/plans/【里程碑】Tripo生成Worker执 5. **产物落库** - provider 产物下载用 `next_chunk` 收进 `Vec`（流式直传 OSS 留 TODO），模型与预览分别 OSS 写入并记录 `content_type` / `content_length` / `sha256`。 - 复用现有原子落库路径写入 `assetKind = "model3d"` 的资源 / 素材、预览图引用与 job 终态；不新增资源列。 + - 按「新增编辑器 `assetKind` 接入清单」对照表执行：把两个 Tripo job kind 加进 `EDITOR_GENERATION_OPERATION_KINDS`（否则原子落库整笔事务被拒）；画布回填只走 placement-only，`model3d` 不进 `EDITOR_CANVAS_ASSET_KINDS`，也不动前端 `CANVAS_ASSET_KIND_TAG_OPTIONS`。 + - 验收：两个 job kind 在白名单内；`canvasCompletion` 回填的 layer 只有 `layerId` / `resourceId`，无 `assetKind` / `src` / `objectKey`；用户标签覆盖、快速编辑、改造 capability 三项保持不进入。 - 验收：`assetLibrary` 分支产出 `assetId`，`projectResource` 分支产出 `resourceId` 且 `content_length` 与实际对象一致。 6. **worker 执行与收口** diff --git a/docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md b/docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md index 37a947908..08b9323c3 100644 --- a/docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md +++ b/docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md @@ -149,6 +149,23 @@ width/height = 预览图像素尺寸 `external_generation_job.phase` 的取值集合不变，仍只允许现有两种执行阶段；阶段文案由 api-server 映射，不扩展 schema 常量。 +## assetKind 接入清单对照 + +对照 [`【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`](../【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md) 的「新增编辑器 `assetKind` 接入清单」，`model3d` 是**后端-only 类别**：本期不接编辑器前端，只对实际经过的链路做决策，其余行显式登记为不进入。 + +| 清单触碰点 | 本期口径 | +| --- | --- | +| 资源 / 素材 `assetKind` 与 upsert 参数 | `assetKind = "model3d"` 由 worker 在服务端写入，调用方无法指定；Rust 侧 `asset_kind` 是自由字符串，不动共享契约的闭集枚举 | +| schema 与 migration | 不新增类别专属列，复用 `imageSrc` / `thumbnailSrc` / `AssetObject` 元数据；无 `model3d` 存量数据，不写数据迁移 | +| 原子落库 `operation_kind` 白名单 | **必须**把两个 Tripo job kind 加入 `EDITOR_GENERATION_OPERATION_KINDS`，否则 `persist_editor_generation_result_and_return` 整笔事务被拒；这是本期唯一必须改的白名单 | +| 画布回填 | `projectResource` 的 `canvasCompletion` 只走 placement-only（`build_editor_canvas_resource_placement_item`），layer 只拿 `layerId` / `resourceId`，`assetKind`、`src`、`objectKey` 全部归资源所有；因此 `model3d` 不进 `EDITOR_CANVAS_ASSET_KINDS` | +| 用户标签覆盖资格 | 不允许。该白名单必须与前端 `CANVAS_ASSET_KIND_TAG_OPTIONS` 同步，本期无前端入口 | +| 快速编辑资格 | 不允许。3D 结果没有图片快速编辑语义，不进入快速编辑正向白名单 | +| “改造” capability 与 V2 配方 | 不进入改造 allowlist，不定义 V2 `action` / `fields[].id` / `references[].id`，不发 `canvasCompletion` 之外的可重放配方 | +| 素材库 / 后台 / 精选 read model / 公开 grant / External OpenAPI | 本期不改。素材库与后台沿用现有按 `assetKind` 派生 renderer 的行为，`model3d` 未接 renderer 前只保证字段正确，不承诺展示；公开 grant 与 External v1 均不涉及 | + +清单第 3 条要求的“用户标签覆盖”与“快速编辑”两项资格评估，以及 capability 决策，结论均为**不进入**，理由是本期为后端-only 集成、无前端入口、3D 无 quick-edit 语义。后续接前端时，四项都必须重新评估并单独补齐前端白名单与 renderer。 + ## 兼容与迁移 - 旧 `/api/assets/hyper3d/*` 与 `platform-hyper3d` 保持原样，不因本能力上线而改变行为，也不做 provider 静默切换。 diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md index 694ea1dea..311f4fc0e 100644 --- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md +++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md @@ -498,6 +498,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复 - `assetKind` 是数据库、Rust DTO 和对外 JSON 的可选语义类别真相；普通静态图片必须为空。不要新增或返回并列的 `mediaType`；前端 renderer 可以保留内部派生媒体类型，但不得回写后端。 - 每次新增 `assetKind` 都必须分别完成“用户标签覆盖”和“快速编辑”两项资格评估；两者互不推导。可被用户选择不等于可快速编辑，属于图片媒体族也不等于自动进入快速编辑正向白名单。 - `assetKind` 只描述素材类别，不代表生成配方可执行或允许“改造”；新增类别必须单独完成上表的 capability 决策和验收。 +- 不走编辑器前端的后端生成类别（当前只有 Tripo 3D 的 `model3d`）同样适用本清单：四项资格评估、原子落库 `operation_kind` 白名单和画布回填口径都必须在对应技术方案里显式登记，未登记即视为未接入，不能靠“前端还没入口”跳过。生成类结果落库前 `EDITOR_GENERATION_OPERATION_KINDS` 必须已包含该 job kind，否则整笔事务被拒；画布回填只允许走 placement-only 口径（`build_editor_canvas_resource_placement_item`），不得把后端-only 类别写进 `EDITOR_CANVAS_ASSET_KINDS`，因为该白名单必须与前端 `CANVAS_ASSET_KIND_TAG_OPTIONS` 同步。 - 只是新增分类或 renderer 且现有媒体字段足够时，不改 schema。只有必须跨刷新、复用、审核或公开保留的数据才新增类别专属字段。 - legacy 数据必须先通过有界、可审计、带 dry-run/hash/apply 门禁的数据库迁移收口；迁移后的 api-server、mapper、主站、后台和画布只读取正式字段，不保留运行时 fallback。