Genarrative/docs/technical/MY_TAB_REFERRAL_AND_COMMUNITY_IMPLEMENTATION_2026-04-25.md

我的 Tab 邀请与玩家社区首期落地方案

更新时间：2026-05-01

目标

在现有“我的”Tab 功能入口区（常用功能）落地三个轻量入口，入口顺序固定为 邀请好友、填邀请码、玩家社区：

1. 邀请好友：弹出面板展示当前账号绑定的邀请码、邀请奖励规则和成功邀请用户列表。
2. 填邀请码：弹出面板填写邀请码，成功后邀请者与被邀请者各获得 30 光点。
3. 玩家社区：弹出面板展示微信群与 QQ 群正式二维码图片。

后端边界

• 邀请码、邀请关系与奖励发放全部存入 server-rs/crates/spacetime-module。
• Axum 只做鉴权、参数转发与响应映射，不在 API 层自行计算奖励。
• 前端只读取后端状态与调用提交接口，不做本地加光点。
• 钱包余额继续复用 profile_dashboard_state.wallet_balance。
• 奖励流水继续复用 profile_wallet_ledger，新增来源类型：
  • invite_inviter_reward
  • invite_invitee_reward
• API 返回钱包流水时，sourceType 必须复用 server-rs/crates/shared-contracts/src/runtime.rs 中的常量，避免 SpacetimeDB 枚举映射和前端合同字符串漂移。

SpacetimeDB 表设计

profile_invite_code

• user_id：主键，账号 ID。
• invite_code：唯一邀请码。
• created_at / updated_at：创建与更新时间。

profile_referral_relation

• invitee_user_id：主键，被邀请账号 ID。保证每个用户最多填写一次邀请码。
• inviter_user_id：邀请者账号 ID。
• invite_code：绑定时使用的邀请码快照。
• inviter_reward_granted：邀请者本次是否获得奖励。
• invitee_reward_granted：被邀请者是否获得奖励。
• bound_at：绑定时间。

业务规则

• 每个用户拥有一个稳定邀请码，首次进入邀请中心时自动生成。
• 用户不能填写自己的邀请码。
• 用户最多填写一个邀请码，成功后不可修改。
• 被邀请者绑定成功后获得 30 光点。
• 邀请者每天最多获得 10 次邀请奖励，超过后关系仍可绑定，被邀请者仍获得奖励，邀请者当次不再加分。
• 每次奖励都写入钱包流水，钱包余额以后端返回为准。

API

GET /api/runtime/profile/referrals/invite-center

返回当前用户的邀请码、邀请链接、今日奖励次数、剩余奖励次数、已绑定状态、奖励参数与成功邀请用户列表。

成功邀请用户列表字段：

{
  "invitedUsers": [
    {
      "userId": "user_001",
      "displayName": "百梦玩家",
      "avatarUrl": null,
      "boundAt": "2026-05-01T08:00:00Z"
    }
  ]
}

• invitedUsers 只包含当前账号作为邀请人的关系。
• 列表按 boundAt 倒序返回，最多展示最近 20 位成功邀请用户。
• 昵称与头像从 user_account 读取；缺失昵称时前端回退展示 玩家。

POST /api/runtime/profile/referrals/redeem-code

请求体：

{
  "inviteCode": "ABCD1234"
}

返回绑定后的邀请中心状态与本次奖励发放结果。

落地状态

• server-rs/crates/spacetime-module 已新增邀请码与邀请关系表，邀请中心读取和填码绑定均通过 SpacetimeDB procedure 执行。
• server-rs/crates/api-server 已挂接 /api/runtime/profile/referrals/* 与 /api/profile/referrals/* 两组路由。
• 前端“我的”Tab 三个功能入口均打开独立弹窗，玩家社区使用 media/social-media-group/wechat.png 与 media/social-media-group/qq.png 两张正式二维码图片。
• 复制邀请会复制邀请码和邀请链接；填码成功后刷新个人看板光点。
• 邀请好友弹窗展示 邀请一个用户注册，双方都可获得 30 光点。每日最多获得十次邀请奖励。，不再展示“邀请 / 已奖 / 今日”三项统计。
• 邀请好友弹窗底部展示成功邀请用户头像和昵称列表；没有成功邀请时展示短空状态。
• “我的”页 邀请好友 按钮副标题展示 双方得30（光点icon）；玩家社区 按钮副标题展示 每日领福利。
• “我的”页功能入口区不展示 常用功能 标题和 快捷入口 副标题，避免首屏重复说明类文案。

前端交互

• 三个入口继续放在“我的”Tab 功能入口区（常用功能），不新增页面。
• 邀请好友 弹窗展示邀请码、复制按钮、邀请奖励规则和成功邀请用户头像昵称列表。
• 填邀请码 入口只在账号注册后 24 小时内且尚未填写过邀请码时展示；若 auth.user.createdAt 缺失或解析失败，前端按已超时处理并隐藏入口。
• 填邀请码 弹窗在未绑定时展示输入框；成功绑定后刷新邀请中心与个人看板，并隐藏常用功能里的入口。
• 玩家社区 弹窗展示两个紧凑二维码图片区，保留微信群与 QQ 群短标签。
• 弹窗文案只保留必要标签和短提示；本次邀请奖励规则属于必要交易说明，固定展示在邀请码下方。