新增Tripo生成API的里程碑规范与实施计划
- 新增契约与数据模型里程碑，锁定范围、不做项与验收标准 - 新增 Worker 执行链路与 API 路由里程碑，标注 pending 与定价前置依赖 - 新增契约里程碑实施计划，固定步骤顺序、验证命令与回退范围
This commit is contained in:
@@ -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 追加字段与定价结构三处。
|
||||
|
||||
@@ -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`）。
|
||||
@@ -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` 验收通过。
|
||||
- 生产泥点定价数值已确认并写入默认配置。
|
||||
|
||||
Reference in New Issue
Block a user