61 lines
3.3 KiB
Markdown
61 lines
3.3 KiB
Markdown
# 拼图作品积分激励链路设计
|
||
|
||
更新时间：`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 检查和必要前端测试。
|