5.0 KiB
5.0 KiB
我的 Tab 邀请与玩家社区首期落地方案
更新时间：2026-05-01
目标
在现有“我的”Tab 功能入口区（常用功能）落地三个轻量入口，入口顺序固定为 邀请好友、填邀请码、玩家社区：
邀请好友：弹出面板展示当前账号绑定的邀请码、邀请奖励规则和成功邀请用户列表。填邀请码：弹出面板填写邀请码，成功后邀请者与被邀请者各获得30光点。玩家社区：弹出面板展示微信群与 QQ 群正式二维码图片。
后端边界
- 邀请码、邀请关系与奖励发放全部存入
server-rs/crates/spacetime-module。 - Axum 只做鉴权、参数转发与响应映射，不在 API 层自行计算奖励。
- 前端只读取后端状态与调用提交接口，不做本地加光点。
- 钱包余额继续复用
profile_dashboard_state.wallet_balance。 - 奖励流水继续复用
profile_wallet_ledger，新增来源类型：invite_inviter_rewardinvite_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 群短标签。- 弹窗文案只保留必要标签和短提示；本次邀请奖励规则属于必要交易说明，固定展示在邀请码下方。