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..24c2335e4 --- /dev/null +++ b/docs/project-memory/plans/【实施计划】Tripo生成Worker执行链路与API路由-2026-09-21.md @@ -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`（流式直传 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 字段保持向后兼容，不需要回滚。 diff --git a/docs/project-memory/plans/【里程碑】Tripo生成API契约与数据模型-2026-09-21.md b/docs/project-memory/plans/【里程碑】Tripo生成API契约与数据模型-2026-09-21.md index 8d0b00c91..0b4d37c4c 100644 --- a/docs/project-memory/plans/【里程碑】Tripo生成API契约与数据模型-2026-09-21.md +++ b/docs/project-memory/plans/【里程碑】Tripo生成API契约与数据模型-2026-09-21.md @@ -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` ## 目标 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 e2e2bdbcf..6b00a8925 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 @@ -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` 验收通过。 - 生产泥点定价数值已确认并写入默认配置。 -