3.7 KiB
3.7 KiB
资产生成叙世币消耗接入方案
背景
当前叙世币钱包余额、充值流水与邀请奖励已经收口到 server-rs/crates/spacetime-module/src/runtime/profile.rs。资产图片生成由 Axum API 调用外部模型并写入 OSS，SpacetimeDB reducer/procedure 不能直接执行外部网络生成，因此扣费需要拆成两层：
- SpacetimeDB 负责钱包余额和流水的原子变更。
- Axum 负责在发起外部生成前扣费，并在生成或持久化失败时补偿退款。
首期范围
首期接入带 Bearer 身份、能明确归属真实用户的资产生成与发布入口：
POST /api/custom-world/scene-imagePOST /api/custom-world/cover-imagePOST /api/runtime/custom-world/cover-imagePOST /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
暂不接入以下入口：
- 旧资产工坊角色主形象/动作生成接口：当前仍使用
asset-tool作为兼容归属，无法确认真实用户。 - 手动上传封面：不调用外部生成模型，不消耗叙世币。
- 自定义世界草稿自动补图链路：属于后台补全流程，避免一次用户操作触发多笔不可预期扣费。
- 文本实体、NPC 生成：本次需求聚焦资产生成，首期只覆盖图片资产。
计费规则
- 每次图片资产生成请求消耗
1枚叙世币。 - 每次作品发布请求消耗
1枚叙世币；余额不足时禁止发布。 - 在调用外部图片生成前预扣，余额不足时直接返回业务错误，不调用外部模型。
- 发布请求在写入发布状态前预扣，余额不足时直接返回业务错误，不调用发布 mutation。
- 如果图片生成、远程下载、OSS 写入、资产记录确认或发布 mutation 失败，Axum 自动发起同额退款。
- 如果退款失败，原始错误仍返回给调用方，同时服务端日志记录退款失败，便于后续人工核对。
钱包流水
新增两个流水来源类型，首期同时覆盖“资产生成”和“资产发布”这两类资产操作：
asset_generation_consume：资产生成预扣，amount_delta = -1。asset_generation_refund：资产生成失败退款，amount_delta = +1。
wallet_ledger_id 由 Axum 传入，格式：
- 扣费：
asset_generation_consume:{user_id}:{asset_kind}:{asset_id} - 退款：
asset_generation_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_returnprocedure，并扩展钱包变更 helper 支持负数。spacetime-client：新增对应调用方法和绑定类型。api-server：在自定义世界图片生成与发布入口前扣费，错误分支退款。shared-contracts：新增 API 流水来源常量，保证“我的-钱包流水”输出使用稳定契约字符串。
非目标
本次不做分档价格、不做会员免扣、不做前端计费展示改造，也不迁移旧 server-node 逻辑。旧资产工坊角色主形象/动作生成与发布接口仍需要先补齐 Bearer 身份归属后再纳入扣费范围。