补记Tripo model3d的assetKind接入清单对照
- 主规范新增 assetKind 接入清单对照表，逐行登记后端-only 类别的触碰点口径 - 主规范明确原子落库 operation_kind 白名单必须新增两个 Tripo job kind，画布回填只走 placement-only - 主规范登记用户标签覆盖、快速编辑与改造 capability 三项结论均为不进入，并写明后续接前端需重评 - 实施计划把 provider 配置文件行更正为 provider.rs，并在产物落库步骤补白名单与 placement 口径验收 - 后端架构文档补充说明：不走编辑器前端的生成类别同样适用清单，不能靠无前端入口跳过
This commit is contained in:
@@ -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<u8>`（流式直传 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 执行与收口**
|
||||
|
||||
@@ -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 静默切换。
|
||||
|
||||
@@ -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。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user