Merge pull request #3 from codex/coin-consume
# Conflicts: # packages/shared/src/contracts/runtime.ts # server-rs/crates/module-runtime/src/lib.rs # server-rs/crates/shared-contracts/src/runtime.rs # server-rs/crates/spacetime-client/src/module_bindings/runtime_profile_wallet_ledger_source_type_type.rs # src/components/rpg-entry/RpgEntryHomeView.tsx
This commit is contained in:
@@ -1,15 +1,15 @@
|
||||
# 资产生成叙世币消耗接入方案
|
||||
# 资产操作叙世币消耗接入方案
|
||||
|
||||
## 背景
|
||||
|
||||
当前叙世币钱包余额、充值流水与邀请奖励已经收口到 `server-rs/crates/spacetime-module/src/runtime/profile.rs`。资产图片生成由 Axum API 调用外部模型并写入 OSS，SpacetimeDB reducer/procedure 不能直接执行外部网络生成，因此扣费需要拆成两层：
|
||||
当前叙世币钱包余额、充值流水与邀请奖励已经收口到 `server-rs/crates/spacetime-module/src/runtime/profile.rs`。资产图片生成和作品发布由 Axum API 调用外部模型或写入业务状态，SpacetimeDB reducer/procedure 不能直接执行外部网络生成，因此计费需要拆成两层：
|
||||
|
||||
- SpacetimeDB 负责钱包余额和流水的原子变更。
|
||||
- Axum 负责在发起外部生成前扣费，并在生成或持久化失败时补偿退款。
|
||||
- Axum 资产操作服务负责在执行业务资产操作前扣费，并在生成、持久化或发布失败时补偿退款。
|
||||
|
||||
## 首期范围
|
||||
|
||||
首期接入带 Bearer 身份、能明确归属真实用户的资产生成与发布入口：
|
||||
首期接入带 Bearer 身份、能明确归属真实用户的资产操作入口：
|
||||
|
||||
- `POST /api/custom-world/scene-image`
|
||||
- `POST /api/custom-world/cover-image`
|
||||
@@ -26,28 +26,27 @@
|
||||
- 旧资产工坊角色主形象/动作生成接口：当前仍使用 `asset-tool` 作为兼容归属，无法确认真实用户。
|
||||
- 手动上传封面：不调用外部生成模型，不消耗叙世币。
|
||||
- 自定义世界草稿自动补图链路：属于后台补全流程，避免一次用户操作触发多笔不可预期扣费。
|
||||
- 文本实体、NPC 生成：本次需求聚焦资产生成，首期只覆盖图片资产。
|
||||
- 文本实体、NPC 生成：本次需求聚焦图片资产和发布资产操作，首期只覆盖可明确归属的入口。
|
||||
|
||||
## 计费规则
|
||||
|
||||
- 每次图片资产生成请求消耗 `1` 枚叙世币。
|
||||
- 每次作品发布请求消耗 `1` 枚叙世币；余额不足时禁止发布。
|
||||
- 在调用外部图片生成前预扣，余额不足时直接返回业务错误，不调用外部模型。
|
||||
- 发布请求在写入发布状态前预扣，余额不足时直接返回业务错误，不调用发布 mutation。
|
||||
- 如果图片生成、远程下载、OSS 写入、资产记录确认或发布 mutation 失败，Axum 自动发起同额退款。
|
||||
- 每次可计费资产操作消耗 `1` 枚叙世币。
|
||||
- 图片生成和作品发布都按资产操作计费；余额不足时禁止继续执行。
|
||||
- 在调用外部图片生成或发布 mutation 前预扣，余额不足时直接返回业务错误，不继续调用后续资产操作。
|
||||
- 如果图片生成、远程下载、OSS 写入、资产记录确认或发布 mutation 失败，资产操作服务自动发起同额退款。
|
||||
- 如果退款失败，原始错误仍返回给调用方，同时服务端日志记录退款失败，便于后续人工核对。
|
||||
|
||||
## 钱包流水
|
||||
|
||||
新增两个流水来源类型，首期同时覆盖“资产生成”和“资产发布”这两类资产操作：
|
||||
公开两个流水来源类型，统一覆盖“资产生成”和“资产发布”这两类资产操作：
|
||||
|
||||
- `asset_generation_consume`：资产生成预扣，`amount_delta = -1`。
|
||||
- `asset_generation_refund`：资产生成失败退款，`amount_delta = +1`。
|
||||
- `asset_operation_consume`：资产操作预扣，`amount_delta = -1`。
|
||||
- `asset_operation_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}`
|
||||
- 扣费：`asset_operation_consume:{user_id}:{asset_kind}:{asset_id}`
|
||||
- 退款：`asset_operation_refund:{user_id}:{asset_kind}:{asset_id}`
|
||||
|
||||
SpacetimeDB procedure 对 `ledger_id` 做幂等保护：如果同一个流水 ID 已存在，则直接返回当前钱包快照，不重复变更余额。
|
||||
|
||||
@@ -56,9 +55,10 @@ 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`：在自定义世界图片生成与发布入口前扣费，错误分支退款。
|
||||
- `api-server`：资产操作服务提供统一可计费执行入口，自定义世界、Big Fish、Puzzle 业务 handler 只声明资产操作，不直接调用钱包扣费或退款。
|
||||
- `shared-contracts`：新增 API 流水来源常量，保证“我的-钱包流水”输出使用稳定契约字符串。
|
||||
- `packages/shared` 与前端：统一使用 `asset_operation_consume` / `asset_operation_refund` 展示钱包流水。
|
||||
|
||||
## 非目标
|
||||
|
||||
本次不做分档价格、不做会员免扣、不做前端计费展示改造，也不迁移旧 `server-node` 逻辑。旧资产工坊角色主形象/动作生成与发布接口仍需要先补齐 Bearer 身份归属后再纳入扣费范围。
|
||||
本次不做分档价格、不做会员免扣，也不迁移旧 `server-node` 逻辑。旧资产工坊角色主形象/动作生成与发布接口仍需要先补齐 Bearer 身份归属后再纳入扣费范围。旧资产生成流水 source 不再作为公开契约兼容。
|
||||
|
||||
Reference in New Issue
Block a user