Files

高物 548db78ca7 Update Match3D/image-generation docs & code

Adds/updates documentation, assets and implementation for Match3D and puzzle image generation workflows. Key changes: decision logs and pitfalls updated to prefer VectorEngine Gemini for Match3D material sheets and to require edits (multipart) for 1:1 container reference images; guidance added for when to use APIMart vs VectorEngine. .env.example clarified APIMart/Responses config. Many new public assets and PPT visuals added. Code changes across frontend and backend: updated shared contracts, server-rs match3d/puzzle/image-generation handlers, VectorEngine/OpenAI image generation clients, and multiple React components/tests to handle UI/background/container image signing, edits workflow, and puzzle UI background resolution. Added src/services/puzzle-runtime/puzzleUiBackgroundSource.ts and related test updates. Includes notes about multipart HTTP/1.1 requirement and test/verification commands in docs.

2026-05-14 20:34:45 +08:00

5.9 KiB

Raw Blame History

资产操作泥点消耗接入方案

背景

当前泥点钱包余额、充值流水与邀请奖励已经收口到 server-rs/crates/spacetime-module/src/runtime/profile.rs。资产图片生成和作品发布由 Axum API 调用外部模型或写入业务状态，SpacetimeDB reducer/procedure 不能直接执行外部网络生成，因此计费需要拆成两层：

SpacetimeDB 负责钱包余额和流水的原子变更。
Axum 资产操作服务负责在执行业务资产操作前扣费，并在生成、持久化或发布失败时补偿退款。

首期范围

首期接入带 Bearer 身份、能明确归属真实用户的资产操作入口：

POST /api/custom-world/scene-image
POST /api/custom-world/cover-image
POST /api/runtime/custom-world/cover-image
POST /api/runtime/custom-world-library/{profile_id}/publish
自定义世界 Agent 动作 publish_world
Big Fish Agent 正式图片生成动作 big_fish_generate_level_main_image、big_fish_generate_level_motion、big_fish_generate_stage_background
Big Fish Agent 动作 big_fish_publish_game
Puzzle Agent 图片生成动作 compile_puzzle_draft、generate_puzzle_images
Puzzle Agent 动作 publish_puzzle_work
Match3D / 抓大鹅草稿生成动作 match3d_compile_draft
拼图 / 抓大鹅结果页 UI 背景与抓大鹅批量新增物品素材；背景音乐和点击音效生成入口当前临时关闭，不进入计费范围

暂不接入以下入口：

旧资产工坊角色主形象/动作生成接口：当前仍使用 asset-tool 作为兼容归属，无法确认真实用户。
手动上传封面：不调用外部生成模型，不消耗泥点。
自定义世界草稿自动补图链路：属于后台补全流程，避免一次用户操作触发多笔不可预期扣费。
文本实体、NPC 生成：本次需求聚焦图片资产和发布资产操作，首期只覆盖可明确归属的入口。

计费规则

每次可计费资产操作消耗 1 枚泥点。
例外：Match3D / 抓大鹅草稿生成是一次完整草稿外部生成动作，固定消耗 10 枚泥点；流水仍复用 asset_operation_consume / asset_operation_refund，asset_kind = match3d_draft_generation。
例外：拼图 / 抓大鹅 UI 背景重新生成固定消耗 2 枚泥点。
例外：抓大鹅结果页批量新增物品素材按实际可新增物品名计费，每 5 个消耗 2 枚泥点，不足 5 个向上按 5 个计。重复名称、作品中已有名称和超过容量上限的名称不进入计费数量。
图片生成和作品发布都按资产操作计费；余额不足时禁止继续执行。
在调用外部图片生成或发布 mutation 前预扣，余额不足时直接返回业务错误，不继续调用后续资产操作。
如果图片生成、远程下载、OSS 写入、资产记录确认或发布 mutation 失败，资产操作服务自动发起同额退款。
如果退款失败，原始错误仍返回给调用方，同时服务端日志记录退款失败，便于后续人工核对。

前端确认交互

所有前端可见且会消耗泥点的按钮，点击后必须先弹出独立确认面板，面板标题使用 确认消耗泥点，正文只展示本次消耗数量，例如 消耗 2 泥点。用户点击 确定 后才允许调用后端扣费动作；点击 取消 或关闭面板不得触发接口。

2026-05-14 当前已覆盖的草稿页入口包括：

拼图入口 AI重绘=true 的 生成拼图游戏草稿：2 泥点；AI重绘=false 直接使用上传图，不显示泥点确认。
拼图结果页关卡 生成画面 / 重新生成画面：2 泥点。
拼图结果页 素材配置 > UI 的 生成UI背景 / 重新生成：2 泥点。
拼图结果页发布按钮：1 泥点，发布确认面板必须显示本次消耗数量。
抓大鹅入口 生成抓大鹅草稿：10 泥点。
抓大鹅结果页 素材配置 > 物品 的批量新增与批量重新生成：按实际计费数量展示动态泥点数。
抓大鹅结果页 素材配置 > UI 与 素材配置 > 容器形象 的 重新生成：各 2 泥点。

钱包流水

公开两个流水来源类型，统一覆盖“资产生成”和“资产发布”这两类资产操作。流水金额由具体资产操作成本决定，不再假定所有资产操作都是 1 枚泥点：

asset_operation_consume：资产操作预扣，amount_delta = -points_cost。
asset_operation_refund：资产操作失败退款，amount_delta = +points_cost。

wallet_ledger_id 由 Axum 传入，格式：

扣费：asset_operation_consume:{user_id}:{asset_kind}:{asset_id}
退款：asset_operation_refund:{user_id}:{asset_kind}:{asset_id}

SpacetimeDB procedure 对 ledger_id 做幂等保护：如果同一个流水 ID 已存在，则直接返回当前钱包快照，不重复变更余额。

工程落点

module-runtime：新增钱包调整输入、钱包调整结果、流水来源枚举。
spacetime-module：新增 consume_profile_wallet_points_and_return 与 refund_profile_wallet_points_and_return procedure，并扩展钱包变更 helper 支持负数。
spacetime-client：新增对应调用方法和绑定类型。
api-server：资产操作服务提供统一可计费执行入口，自定义世界、Big Fish、Puzzle 业务 handler 只声明资产操作，不直接调用钱包扣费或退款。
shared-contracts：新增 API 流水来源常量，保证“我的-钱包流水”输出使用稳定契约字符串。
packages/shared 与前端：统一使用 asset_operation_consume / asset_operation_refund 展示钱包流水。

非目标

本次不做分档价格、不做会员免扣，也不迁移旧 server-node 逻辑。旧资产工坊角色主形象/动作生成与发布接口仍需要先补齐 Bearer 身份归属后再纳入扣费范围。旧资产生成流水 source 不再作为公开契约兼容。

5.9 KiB Raw Blame History Unescape Escape