Genarrative/docs/technical/PUZZLE_WORK_POINT_INCENTIVE_2026-05-01.md

拼图作品积分激励链路设计

更新时间：2026-05-01

1. 目标

1. 拼图草稿页“新增关卡”按钮下方显示一行小字：“获得更多积分激励”。
2. 创作页的已发布拼图作品卡展示当前作品的积分激励总数、待领取积分数和领取按钮。
3. 用户在他人已发布拼图作品中消耗陶泥币时，作品作者获得消耗陶泥币数量的一半作为积分激励。
4. 作者领取时只能领取整数个陶泥币，待领取值向下取整；未满 1 个陶泥币的半数余额继续保留。

2. 数据模型

拼图作品激励归属到 puzzle_work_profile。

1. point_incentive_total_half_points: u64
   • 记录该作品累计获得的激励，单位为“半个陶泥币”。
   • 每消耗 N 个陶泥币，增加 N 个 half points；当前拼图道具每次消耗 1 个陶泥币，因此每次为作者增加 0.5。
2. point_incentive_claimed_points: u64
   • 记录作者已领取的整数陶泥币数量。
3. 前端展示：
   • 激励总数 = pointIncentiveTotalHalfPoints / 2，允许展示一位小数。
   • 待领取积分 = floor(pointIncentiveTotalHalfPoints / 2) - pointIncentiveClaimedPoints。
   • 领取按钮仅在待领取积分大于 0 时可用。

3. 后端事务

1. 拼图运行道具扣费成功、道具效果成功落库后，后端根据 run 的当前作品 profile_id 查找作者。
2. 若使用者不是作品作者，则给该作品累积 consumed_points 个 half points。
3. 若使用者是作者本人，视为作者自测，不产生积分激励。
4. 若后续业务操作失败并触发扣费退款，不写入激励。
5. 领取接口：
   • 只允许作品作者领取。
   • 计算可领取整数 claimable = total_half_points / 2 - claimed_points。
   • claimable <= 0 时拒绝领取。
   • 同一事务内更新作品 claimed_points += claimable，并向作者钱包增加 claimable 陶泥币，钱包流水来源使用 puzzle_author_incentive_claim。

4. API 与前端

1. PuzzleWorkSummary / PuzzleWorkProfile 增加：
   • pointIncentiveTotalHalfPoints
   • pointIncentiveClaimedPoints
   • pointIncentiveTotalPoints
   • pointIncentiveClaimablePoints
2. 新增领取接口：
   • POST /api/runtime/puzzle/works/{profile_id}/point-incentive/claim
   • 返回更新后的 PuzzleWorkProfile。
3. 创作页仅对已发布拼图作品显示积分激励块；RPG、大鱼和草稿卡不显示。
4. 领取成功后刷新对应拼图作品列表状态，按钮立即禁用或显示新的待领取数，并同步刷新个人钱包看板。
5. spacetime-client 映射层继续兼容历史拼图运行快照：旧 run_json 若缺少 started_at_ms，API 记录回填为非 0 值，避免前端计时器拿到无效开始时间。

5. 验收点

1. 拼图草稿页新增关卡按钮下方显示“获得更多积分激励”。
2. 已发布拼图作品卡展示“积分激励总数”和“待领取”两个数值。
3. 待领取积分为 0 时领取按钮禁用。
4. 非作者游玩他人拼图并使用付费道具后，该作品累计 half points 增加。
5. 作者领取后钱包增加向下取整后的整数陶泥币，作品待领取数归零或保留不足 1 的小数余额。
6. 领取成功后顶部/我的页钱包余额随个人看板刷新。
7. 修改后运行编码检查、SpacetimeDB 绑定生成、Rust 检查和必要前端测试。