图片画布接入 3D 资源：新增 model3d 类别、3D 预览与 3D 生成入口

- 后端资源投影按 asset_kind 分叉，新增 project_editor_client_media_src 与 EDITOR_MODEL3D_ASSET_KIND：model3d 只投影预览图，模型本体只留 objectKey，预览缺失才回落历史口径 - tripo3d 存储新增按字节魔数识别模型 content_type 与扩展名映射，不采信 provider 声明与下载响应头 - editor_project_storage 把 model3d 加入 EDITOR_CANVAS_ASSET_KINDS 白名单 - 前端 CanvasAssetKind 与 image-canvas-core 类型新增 model3d：画布卡片渲染预览图或 3D 占位，类型角标新增「3D模型」，覆盖资格只在它与空类别之间成立 - 新增 model3d-preview 子目录（Model3dViewerModal / Model3dViewerModel），Tailwind 内联、不新增 CSS，失败原因分超限 / 格式不可识别 / 无 WebGL2 三类展示 - 选中工具条新增只读 preview-model3d 能力位，仅 objectKey 为空时置灰；打开预览同时选中图层并暂停画布快捷键与舞台交互 - 查看器包源对象 format 改为可选，新增「声明 Content-Type → 字节魔数 → 地址扩展名」三级格式判定并导出支持格式清单 - 导出工作流新增 3d_models/ 目录，模型下载按真实响应头 MIME 定扩展名、对象键扩展名兜底 - 新增 3D 生成入口：底部工具栏浮动子选项与文生 / 图生 3D 面板，落 projectResource + canvasCompletion，复用占位框与任务侧栏 - 3D 定价只读实时定价查询，段缺失即入口不可提交；幂等键由前端铸造，用户重试必须换键 - 新增 ADR 0003 / 0004 与实施计划、里程碑文档；更新 Tripo 技术方案、后端架构、CONTEXT 术语、decision-log 与 pitfalls - .gitignore 忽略仓库根目录手工下载的 3D 样例模型
2026-09-22 10:10:00 +08:00
parent 9fc55a5cac
commit 61fe4c48af
64 changed files with 4964 additions and 119 deletions
@@ -8909,3 +8909,27 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 边界：预检只按主键定点查引用，禁止拉取当前用户的完整工程列表或素材库，也禁止在提交路径上执行 provider 副作用（上传 `file_token`、submit）。该口径适用于所有「服务端站内引用 → provider 输入」的生成入口，Tripo 是首个按此收口的类别。
 - 验证：`cargo test -p api-server` 1085 通过（含新增的 `tripo3d::image_source` 源码钉住用例，断言预检与定点解析只调用窄查询、不含列工程 / 列素材库 / 读正文 / 上传）；`cargo check -p api-server` 无 tripo3d 警告；`npm run check:encoding`、`node scripts/check-doc-index.mjs`、`git diff --check` 通过。真实 provider 端到端仍未跑。
 - 关联文档：[技术方案 Tripo 3D生成API集成](../../technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md)、[实施计划 Tripo生成Worker执行链路与API路由](../plans/【实施计划】Tripo生成Worker执行链路与API路由-2026-09-21.md)。
+
+## 2026-09-21 3D 资源的客户端媒体投影按类别分叉，模型格式真相只在内容类型与查看器能力各一处
+
+- 背景：Tripo 生成的 `model3d` 资源同时持有模型本体（`objectKey`）与预览图（`imageSrc` / `thumbnailSrc`），而客户端媒体投影历史口径是「`objectKey` 非空就以它充当 `imageSrc`」，于是画布卡片、素材缩略图与后台都会把 `.glb` 交给图片渲染器。
+- 决策：投影收口成一个函数（`project_editor_client_media_src`）：`model3d` 只投影预览图（`thumbnail_src` → `image_src`），模型本体只留在 `objectKey`；其它类别保持原口径，预览缺失才回落。写入 `asset_object.content_type` 前按字节魔数识别真实产物（GLB 的 `glTF` 头、FBX 的 `Kaydara FBX Binary` 头、glTF 的 JSON 正文），对象键扩展名由内容类型派生。客户端不抄格式清单、也不按扩展名预判放行：画布只认「`assetKind=model3d` 且 `objectKey` 非空」，格式判定跟着解析器走——`packages/model3d-viewer` 依次采信读接口声明的 `Content-Type`、字节魔数、地址扩展名，格式在该包里是可选输入，判不出来即 `unsupported-format` 并把原因显示在模态里。
+- 边界：`model3d` 是独立媒体族，标签覆盖只在它与空类别之间成立；快速编辑与改造都不进入。画布工具条新增只读 capability 位 `preview-model3d`，AGC 项目画布不声明；导出 3D 图层落 `3d_models/` 目录；AGC 项目画布自带的两份格式判断本期不动，后续统一收敛到查看器包；素材库行、后台 renderer、精选 read model、公开 grant 与 External v1 本期不进入。
+- 验证：`cargo test --locked -p api-server` 的媒体投影与 Tripo 存储用例通过；前端 `model3d-preview`、选中工具条、画布视图、编辑器模型与导出工作流用例通过；`npm run check:encoding`、`node scripts/check-doc-index.mjs`、`git diff --check` 通过。真实 provider 端到端与素材库 / 后台 renderer 仍未接。
+- 关联文档：[ADR 0003](../../adr/【ADR】0003-3D资源客户端媒体投影与格式真实性-2026-09-21.md)、[技术方案 Tripo 3D生成API集成](../../technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md)、[实施计划 Tripo生成结果前端预览接入](../plans/【实施计划】Tripo生成结果前端预览接入-2026-09-21.md)。
+
+## 2026-09-21 3D 生成入口落在画布生成链路，价格只读实时定价查询，幂等键由前端铸造
+
+- 背景：Tripo 两个 submit API 与 worker 已就绪，需要在前端开一个「生成 3D 模型」入口。3D 是资产型产出（没有 runtime、单局、胜负、作品架语义），而画布已经把 `model3d` 当作 `CanvasAssetKind`，并由只读「3D 预览」承接消费。
+- 决策：宿主固定为图片画布工程 `/editor/canvas` 的底部工具栏，形态照 `music` / `spec` 的「一项入口 → 浮动子选项 → 各自一个提交面板」，两个子项为「文生 3D 模型」「图生 3D 模型」（文案对齐后端 `phaseLabel`）；落点固定 `projectResource` + `canvasCompletion`，复用既有占位框、入队、任务侧栏与终态刷新回填；参数永远全量非空提交；图生只接受一张平台内图片（画布资源或素材库资产，经既有参考图来源菜单收敛成 `resource` / `asset` 引用）。不新建独立生成页 / 结果页 / runtime / 作品架 / 广场 / 统计，不接 multiview，不接画布 Agent 对话，不做素材库落点入口（前端不暴露 `target = assetLibrary`）。
+- 价格与幂等（见 ADR 0004）：提交前价格只来自 `GET /api/editor/generation-pricing` 的 `model3d` 段，段缺失即入口不可提交且不发请求，前端零 3D 兜底数值；`Idempotency-Key` 由前端铸造（画布链路首次需要该头），用户主动重试必须铸造新键——同键同 payload 只会返回原 operation，而 Tripo 队列 `max_attempts = 1`，不存在「同键重跑」。
+- 边界：该条记录的是文档先行阶段（ADR 0004、里程碑与实施计划、`CONTEXT.md` 术语「3D 模型生成工具」与「3D 生成定价」）；前端实现已在同日落地，见下一条。后端 `model3d` 定价段仍未写入运行环境配置，入口上线前必须先把数值落到配置。
+- 关联文档：[ADR 0004](../../adr/【ADR】0004-3D生成入口价格与幂等身份-2026-09-21.md)、[里程碑 Tripo生成前端入口](../plans/【里程碑】Tripo生成前端入口-2026-09-21.md)、[实施计划 Tripo生成前端入口](../plans/【实施计划】Tripo生成前端入口-2026-09-21.md)、[技术方案 Tripo 3D生成API集成](../../technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md)。
+
+## 2026-09-21 3D 生成入口实现落地：新代码收在 `model3d-generation/` 深目录，幂等键按内容定址
+
+- 背景：按上一条决策实现画布侧 3D 生成入口。既要沿用既有生成链路（占位框、入队、任务侧栏、终态回填），又要求新代码不混进画布那些千行大文件。
+- 决策：新代码全部落在 `src/components/image-editor/model3d-generation/`（`Model3dGenerationFormModel` / `Model3dGenerationSubmission` / `useModel3dGenerationTask` / `Model3dGenerationForm` / `Model3dGenerationModal`，测试文件与被测文件同名、不带 `ImageCanvas` 前缀），画布只做工具栏入口、子选项菜单、对话框 mode、定价读取与请求客户端的接线。`Idempotency-Key` 的落地形态是「尝试代次 + 请求内容指纹」，而不是「在每处参数变更里重铸键」——后者要覆盖参考图的上传 / 画布点选 / 素材库三条路径，漏一处就会出现同键换内容的 409。图生 3D 的参考图上限收口成 `usesSingleImageReferenceSlot`，单槽位下素材库选择是替换而不是追加。
+- 边界：不改后端、不改 schema、不新增公开 API；不动素材库落点、后台 renderer、精选 read model、公开 grant、External v1 与画布 Agent 对话；移动端画布不承诺（跟随现状）。
+- 验证：`src/components/image-editor/model3d-generation` 四个测试文件 38 个用例通过；`ImageCanvasGenerationModel` / `ImageCanvasGenerationDialogModel` / `ImageCanvasUploadModel` / `projectAssetReferencePickerModel` 的定向用例通过；`npm run typecheck`、`npx eslint`（`model3d-generation` 与接线文件）、`npm run check:encoding`、`node scripts/check-doc-index.mjs`、`git diff --check` 通过。真实扣费与排队回填需在写入 `model3d` 定价段的联调环境验证。
+- 关联文档：[实施计划 Tripo生成前端入口](../plans/【实施计划】Tripo生成前端入口-2026-09-21.md)、[ADR 0004](../../adr/【ADR】0004-3D生成入口价格与幂等身份-2026-09-21.md)、[技术方案 Tripo 3D生成API集成](../../technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md)。
@@ -5718,3 +5718,35 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **处理（现行口径）**：改 `spacetime-client` 的模块前先 `rg -n '#\\[path = "active/' server-rs/crates/spacetime-client/src/active.rs` 确认该模块的真实文件；只有 `active/` 下的文件参与编译。历史死副本 `src/external_generation.rs` 已在 `ac08ccbe3` 删除，不要再以「两边都改一遍」的方式维持同步。
 - **验证**：`cargo check -p spacetime-client` 与 `cargo check -p api-server` 同时通过，且 `rg --files server-rs/crates/spacetime-client/src` 中同名文件只剩一份。
 - **关联**：`server-rs/crates/spacetime-client/src/active.rs`、`server-rs/crates/spacetime-client/src/active/external_generation.rs`、`server-rs/crates/spacetime-client/src/active/mapper.rs`。
+
+## 2026-09-21 「`objectKey` 非空就覆盖 `imageSrc`」的投影会把模型文件当图片
+
+- **风险**：3D 资源（`assetKind=model3d`）的 `objectKey` 是模型本体、`imageSrc` 是预览图，但后端历史投影不分类别地用 `objectKey` 覆盖 `imageSrc`，于是画布卡片、素材缩略图、后台列表会一起去加载 `.glb`。
+- **处理（现行口径）**：客户端可见媒体投影按 `asset_kind` 分叉（`model3d` 只投影预览图，模型本体只留 `objectKey`），模型格式的权威是写入前按字节魔数识别出的 `content_type`，扩展名由它派生。画布图层没有内容类型字段，所以画布只按「`assetKind=model3d` 且 `objectKey` 非空」放行，格式判定交给查看器包（声明 `Content-Type` → 字节魔数 → 地址扩展名，判不出来即 `unsupported-format` 并展示原因）；下载侧用真实响应头 MIME、对象键扩展名兜底。
+- **易错点**：① 不要为了「预览缺失也能开」把模型文件喂给图片元素，预览缺失应显示占位与错误信息；② 不要新增 `model_format` 列，也不要在画布 / 素材库各抄一份格式清单或在画布侧按扩展名预判放行，两处真相一定会分叉；③ `EDITOR_CANVAS_ASSET_KINDS` 与前端 `CANVAS_ASSET_KIND_TAG_OPTIONS` 必须同步，任一侧多出或少一份都算接入未完成；④ 不要在 `assetKind` 为空时按扩展名兜底（后端投影缺陷会被掩盖），也不要直接照抄 AGC 画布那两份旧判断。
+- **关联**：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/tripo3d/storage.rs`、`src/components/image-editor/model3d-preview/`。
+
+## 2026-09-21 复用旧 `Idempotency-Key` 的「重试」不会重跑 3D 生成
+
+- **现象**：3D 生成失败后，用同一次请求（同 `Idempotency-Key` + 同 payload）再提交一次，接口返回 accepted 与**同一个** `operationId`，但任务永远停在原来的失败终态，用户以为「已经重试过了」。
+- **成因**：两个 Tripo submit 端点把 `Idempotency-Key` 当作唯一幂等身份（dedupe key = sha256(owner + job_kind + key)），同键同 payload 直接返回既有 operation，同键不同 payload 才 409；而 Tripo job 固定 `max_attempts = 1`，失败即终态。因此这个键上不存在「再跑一次」的可能。
+- **处理（现行口径）**：用户主动重试必须铸造新的 `Idempotency-Key`（画布侧由前端生成并绑定当次请求内容，改参数即视为新请求），不要把它做成「复用同键的可重试」。
+- **实现口径**：画布侧的键是「尝试代次 + 请求内容指纹」两段拼成（`resolveModel3dRequestKey`）。不要改成「只在档位 / 开关 / 提示词的 onChange 里重铸键」——参考图还有上传、画布点选、素材库选择三条路径，漏一条就会出现同键换内容的 409；也不要去掉代次，那样用户点「重试」会回到原来那个终态 operation。
+- **验证**：`cargo test -p api-server` 的 tripo3d 队列用例；前端 `model3d-generation` 的重试用例断言两次提交的键不同。
+- **关联**：`server-rs/crates/api-server/src/tripo3d/queue.rs`、`server-rs/crates/api-server/src/editor_generation_queue.rs`、`src/components/image-editor/model3d-generation/`。
+
+## 2026-09-21 3D 生成价格不能照抄图片模型的「前端内置兜底」
+
+- **风险**：图片 / 视频 / 音频一族在前端有内置兜底定价（`EDITOR_MODEL_MUD_POINT_CONFIG`），定价接口异常时价格照常显示。3D 入口若照抄这条习惯，会在 `model3d` 段缺失时继续展示一个价格，而后端是 fail closed（503 `model3d-pricing-unavailable`，不扣费不入队），用户看到「面板有价、提交被拒」。
+- **处理（现行口径）**：3D 价格只读 `GET /api/editor/generation-pricing` 的 `model3d` 段；该段缺失即入口不可提交且不发请求，既不写死数值也不按 0 元放行。前端只保留「档位 → 六个必填参数」的映射与加和逻辑，所有数值来自查询。
+- **易错点**：① 缺价时不要「先发请求让后端兜底」，那会把 503 变成用户可见的失败；② 不要拿图片模型的 `prices` 给 3D 兜底；③ 前端这份加和逻辑与后端 `model3d_add_ons` 是两份实现，必须用同一组参数组合的用例对齐。
+- **关联**：`docs/adr/【ADR】0004-3D生成入口价格与幂等身份-2026-09-21.md`、`src/services/image-editor/editorProjectClient.ts`、`src/components/image-editor/ImageCanvasGenerationModel.ts`。
+
+## 2026-09-21 画布新生成工具漏在「参考图来源」的 mode 列表外，表现为点了菜单没反应
+
+- **现象**：新工具面板里的参考图来源菜单（从画布中选择 / 上传图片 / 从项目素材中选择）点下去没有任何反应，既不报错也不进参考图；`ImageCanvasGenerationSurface` 的入口与子选项菜单却一切正常。
+- **成因**：参考图的三条写入路径都按**显式 mode 列表**分流，而不是按「谁的对话框打开了」：画布点选走 `ImageCanvasGenerationDialogModel.appendGenerationReference`，上传走 `ImageCanvasUploadModel.applyGenerationReferenceUpload`（`target === 'generation-reference'`），素材库走 `ImageCanvasGenerationDialogModel.replaceProjectAssetPickerReferences`。三处各自维护一份 `dialog.mode === 'generate' || 'scene' || ...` 列表，新 mode 不在列表里就被安静地原样返回。
+- **处理（现行口径）**：新增画布生成工具时，除工具栏与子选项菜单外，必须把新 mode 同步进这三处，并在 `resolveDialogExtraImageReferenceLimit` 给出参考图上限；单图槽位（如 `model3d-image-to-model`）用 `usesSingleImageReferenceSlot` 标注，素材库选择按替换而不是追加处理。改完必须有用例覆盖「点选 / 上传 / 素材库各进一次参考图字段」。
+- **易错点**：① 不要只在面板里 `console.warn` 或靠 UI 文案兜底，这类遗漏在自动检查里是静默的；② 单槽位工具不要让「画布点选 vs 素材库选择」互相挤占——留着旧的会让用户这次的选择看起来没生效；③ 参考图上限不要沿用图片生成的默认值（图生 3D 只接受一张）。
+- **验证**：`src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts`、`src/components/image-editor/ImageCanvasUploadModel.test.ts`、`src/components/image-editor/projectAssetReferencePickerModel.test.ts`、`src/components/image-editor/ImageCanvasGenerationModel.test.ts` 中针对 `model3d-image-to-model` 的用例。
+- **关联**：`src/components/image-editor/ImageCanvasGenerationDialogModel.ts`、`src/components/image-editor/ImageCanvasUploadModel.ts`、`src/components/image-editor/ImageCanvasGenerationModel.ts`、`docs/project-memory/plans/【实施计划】Tripo生成前端入口-2026-09-21.md`。