新增Tripo生成Worker执行链路实施计划
- 固定 api-server 侧 tripo3d 目录的文件切分与各文件职责 - 明确提交路由执行顺序、幂等口径与图片输入解析边界 - 记录 Tripo job 固定 max_attempts=1 与 checkpoint 收口语义 - 里程碑二转 active 并回链实施计划，里程碑一补实施计划入口
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
# Tripo 生成 Worker 执行链路与 API 路由实施计划
|
||||
|
||||
Version: 1.0
|
||||
Status: active
|
||||
Date: 2026-09-21
|
||||
Milestone Spec: `docs/project-memory/plans/【里程碑】Tripo生成Worker执行链路与API路由-2026-09-21.md`
|
||||
|
||||
## 边界
|
||||
|
||||
新代码只落在 `server-rs/crates/api-server/src/tripo3d/`，按职责拆成小文件；api-server 其余部分只做必要接线（配置文件、路由 merge、worker 分支、超时表）。不复用 `platform-hyper3d`、`hyper3d_generation.rs` 或 `/api/assets/hyper3d/*`，不接 `/api/external/v1`，不接前端。
|
||||
|
||||
## 文件切分
|
||||
|
||||
| 文件 | 职责 |
|
||||
| --- | --- |
|
||||
| `tripo3d/mod.rs` | 模块声明与 `router(state)`，不承载业务逻辑 |
|
||||
| `tripo3d/job.rs` | 两个 job kind、端点与 job kind 映射、队列载荷类型与 `max_attempts` 口径 |
|
||||
| `tripo3d/queue.rs` | `Idempotency-Key` 幂等身份、入队参数、accepted 响应 |
|
||||
| `tripo3d/routes.rs` | 两个 POST 处理入口与执行顺序（解析 → 校验 → 定价 → 入队） |
|
||||
| `tripo3d/errors.rs` | `Model3dRequestError`、`TripoError` 到 HTTP 的映射 |
|
||||
| `tripo3d/image_source.rs` | `source` 分支归属校验与 provider 图片输入解析 |
|
||||
| `tripo3d/config.rs` | 从 `AppConfig` 构造 `TripoSettings` 与 provider client，缺配置即拒绝 |
|
||||
| `tripo3d/artifacts.rs` | provider 产物下载、OSS 写入与产物元数据 |
|
||||
| `tripo3d/result.rs` | 按端点构造严格结果与落点引用，写 `result_payload_json` |
|
||||
| `tripo3d/worker.rs` | checkpoint 判定、submit、轮询、下载落库与 job 收口 |
|
||||
|
||||
## 步骤
|
||||
|
||||
1. **配置接入**
|
||||
- `AppConfig` 增加 Tripo base url / API Key / 请求超时 / 重试，沿用 provider 示例的环境变量口径。
|
||||
- `tripo3d/config.rs` 负责构造 `TripoSettings` 与 `TripoProviderClient`；未配置时返回 503 且不扣费、不入队。
|
||||
- 验收：缺 key 的提交返回 503，不产生 job。
|
||||
|
||||
2. **job kind 与队列载荷**
|
||||
- 新增 `model3d_text_to_model` / `model3d_image_to_model` 两个 job kind；端点与 job kind 的唯一映射放在 `tripo3d/job.rs`。
|
||||
- 队列载荷是 API 请求本身，不额外嵌套平台字段；`request_payload_json` 沿用现有 fingerprint 注入方式。
|
||||
- Tripo job 固定 `max_attempts = 1`：任何 attempt 失败即终态失败并冲正扣费，崩溃后租约到期同样按耗尽结算，因此不存在第二次 submit 的窗口。
|
||||
- 验收：入队参数断言 `max_attempts == 1`。
|
||||
|
||||
3. **幂等提交路由**
|
||||
- 两个路由要求 Bearer 与 `Idempotency-Key`；复用现有外部生成幂等身份与 payload fingerprint，同键同请求返回原 operation，同键不同请求 409。
|
||||
- 执行顺序固定为：解析 JSON → 平台组合校验（含 provider 预检）→ 查价 → 入队；任何一步失败都在扣费与 provider 调用之前返回。
|
||||
- 验收：缺头 400、缺价格段 fail closed、同键重放不新增扣费。
|
||||
|
||||
4. **图片输入解析**
|
||||
- `source` 只接受站内资源或素材 ID；按分支校验归属并解析 OSS 对象，再生成供 provider 读取的地址，不接受客户端直给 URL。
|
||||
- 解析失败按 400 返回，不扣费、不入队。
|
||||
- 验收：跨 owner 的资源 / 素材被拒绝。
|
||||
|
||||
5. **产物落库**
|
||||
- provider 产物下载用 `next_chunk` 收进 `Vec<u8>`（流式直传 OSS 留 TODO），模型与预览分别 OSS 写入并记录 `content_type` / `content_length` / `sha256`。
|
||||
- 复用现有原子落库路径写入 `assetKind = "model3d"` 的资源 / 素材、预览图引用与 job 终态；不新增资源列。
|
||||
- 验收：`assetLibrary` 分支产出 `assetId`，`projectResource` 分支产出 `resourceId` 且 `content_length` 与实际对象一致。
|
||||
|
||||
6. **worker 执行与收口**
|
||||
- 执行分支：无 checkpoint 才 submit，submit 成功后先落 checkpoint 再轮询；已有 checkpoint 只查询、下载与落库；checkpoint 写入失败按失败收口。
|
||||
- 轮询在单次 attempt 内进行并按现有心跳续租，超时按现有 worker 预算语义处理。
|
||||
- provider 成功但落库失败按失败收口并冲正扣费，checkpoint 保留供对账。
|
||||
- 验收：崩溃重放不产生第二次 submit；落库失败不退化成“已交付”。
|
||||
|
||||
7. **接线与文档**
|
||||
- `app.rs` merge 新路由；`external_generation_worker.rs` 增加两个分支并纳入长任务超时；`tripo3d/mod.rs` 去掉里程碑一的 `dead_code` 豁免。
|
||||
- 主规范把 `max_attempts = 1` 与 checkpoint 的实际语义写实，里程碑状态同步。
|
||||
- 验收：`node scripts/check-doc-index.mjs`、`npm run check:encoding`、`git diff --check` 通过。
|
||||
|
||||
## 验证命令
|
||||
|
||||
```bash
|
||||
cargo check --locked -p api-server --manifest-path server-rs/Cargo.toml
|
||||
cargo test --locked -p api-server --manifest-path server-rs/Cargo.toml tripo
|
||||
npm run check:encoding
|
||||
node scripts/check-doc-index.mjs
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## 风险与回退
|
||||
|
||||
- **真实扣费**：定价数值未写入前 `model3d` 段缺失，提交 fail closed；接口开放前必须先完成定价配置。
|
||||
- **provider 长任务**：单次 attempt 内轮询依赖 lease 续租与长任务超时；超时按现有语义收口为失败并退款。
|
||||
- **共用 worker 分支**：新分支只消费自己的 job kind，不改既有分支的入队与写回路径。
|
||||
- **回退点**：删除路由 merge、worker 分支与 `tripo3d/` 新文件即可回退；schema 上的 checkpoint 字段保持向后兼容，不需要回滚。
|
||||
@@ -4,6 +4,7 @@ Version: 1.0
|
||||
Status: active
|
||||
Date: 2026-09-21
|
||||
Parent Spec: `docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md`
|
||||
Implementation Plan: `docs/project-memory/plans/【实施计划】Tripo生成API契约与数据模型-2026-09-21.md`
|
||||
|
||||
## 目标
|
||||
|
||||
|
||||
@@ -1,9 +1,10 @@
|
||||
# Tripo 生成 Worker 执行链路与 API 路由
|
||||
|
||||
Version: 1.0
|
||||
Status: pending
|
||||
Status: active
|
||||
Date: 2026-09-21
|
||||
Parent Spec: `docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md`
|
||||
Implementation Plan: `docs/project-memory/plans/【实施计划】Tripo生成Worker执行链路与API路由-2026-09-21.md`
|
||||
|
||||
## 目标
|
||||
|
||||
@@ -33,4 +34,3 @@ Parent Spec: `docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-2
|
||||
|
||||
- `docs/project-memory/plans/【里程碑】Tripo生成API契约与数据模型-2026-09-21.md` 验收通过。
|
||||
- 生产泥点定价数值已确认并写入默认配置。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user