1

docs/technical/MY_TAB_REFERRAL_AND_COMMUNITY_IMPLEMENTATION_2026-04-25.md

@@ -1,20 +1,20 @@
 # 我的 Tab 邀请与玩家社区首期落地方案
 
-更新时间：`2026-04-29`
+更新时间：`2026-05-01`
 
 ## 目标
 
-在现有“我的”Tab 常用功能区落地三个轻量入口：
+在现有“我的”Tab 功能入口区（常用功能）落地三个轻量入口，入口顺序固定为 `邀请好友`、`填邀请码`、`玩家社区`：
 
-1. `邀请好友`：弹出面板展示当前账号绑定的邀请码。
-2. `填邀请码`：弹出面板填写邀请码，成功后邀请者与被邀请者各获得 `30` 陶泥币。
+1. `邀请好友`：弹出面板展示当前账号绑定的邀请码、邀请奖励规则和成功邀请用户列表。
+2. `填邀请码`：弹出面板填写邀请码，成功后邀请者与被邀请者各获得 `30` 光点。
 3. `玩家社区`：弹出面板展示微信群与 QQ 群正式二维码图片。
 
 ## 后端边界
 
 - 邀请码、邀请关系与奖励发放全部存入 `server-rs/crates/spacetime-module`。
 - Axum 只做鉴权、参数转发与响应映射，不在 API 层自行计算奖励。
-- 前端只读取后端状态与调用提交接口，不做本地加陶泥币。
+- 前端只读取后端状态与调用提交接口，不做本地加光点。
 - 钱包余额继续复用 `profile_dashboard_state.wallet_balance`。
 - 奖励流水继续复用 `profile_wallet_ledger`，新增来源类型：
   - `invite_inviter_reward`
@@ -43,7 +43,7 @@
 - 每个用户拥有一个稳定邀请码，首次进入邀请中心时自动生成。
 - 用户不能填写自己的邀请码。
 - 用户最多填写一个邀请码，成功后不可修改。
-- 被邀请者绑定成功后获得 `30` 陶泥币。
+- 被邀请者绑定成功后获得 `30` 光点。
 - 邀请者每天最多获得 `10` 次邀请奖励，超过后关系仍可绑定，被邀请者仍获得奖励，邀请者当次不再加分。
 - 每次奖励都写入钱包流水，钱包余额以后端返回为准。
 
@@ -51,7 +51,26 @@
 
 ### `GET /api/runtime/profile/referrals/invite-center`
 
-返回当前用户的邀请码、邀请链接、今日奖励次数、剩余奖励次数、已绑定状态与奖励参数。
+返回当前用户的邀请码、邀请链接、今日奖励次数、剩余奖励次数、已绑定状态、奖励参数与成功邀请用户列表。
+
+成功邀请用户列表字段：
+
+```json
+{
+  "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`
 
@@ -69,13 +88,18 @@
 
 - `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` 两张正式二维码图片。
-- 复制邀请会复制邀请码和邀请链接；填码成功后刷新个人看板陶泥币。
+- 前端“我的”Tab 三个功能入口均打开独立弹窗，玩家社区使用 `media/social-media-group/wechat.png` 与 `media/social-media-group/qq.png` 两张正式二维码图片。
+- 复制邀请会复制邀请码和邀请链接；填码成功后刷新个人看板光点。
+- 邀请好友弹窗展示 `邀请一个用户注册，双方都可获得 30 光点。每日最多获得十次邀请奖励。`，不再展示“邀请 / 已奖 / 今日”三项统计。
+- 邀请好友弹窗底部展示成功邀请用户头像和昵称列表；没有成功邀请时展示短空状态。
+- “我的”页 `邀请好友` 按钮副标题展示 `双方得30（光点icon）`；`玩家社区` 按钮副标题展示 `每日领福利`。
+- “我的”页功能入口区不展示 `常用功能` 标题和 `快捷入口` 副标题，避免首屏重复说明类文案。
 
 ## 前端交互
 
-- 三个入口继续放在“我的”Tab 常用功能区，不新增页面。
-- `邀请好友` 弹窗展示邀请码、复制按钮、邀请链接。
-- `填邀请码` 弹窗在未绑定时展示输入框；已绑定时展示短状态。
+- 三个入口继续放在“我的”Tab 功能入口区（常用功能），不新增页面。
+- `邀请好友` 弹窗展示邀请码、复制按钮、邀请奖励规则和成功邀请用户头像昵称列表。
+- `填邀请码` 入口只在账号注册后 `24` 小时内且尚未填写过邀请码时展示；若 `auth.user.createdAt` 缺失或解析失败，前端按已超时处理并隐藏入口。
+- `填邀请码` 弹窗在未绑定时展示输入框；成功绑定后刷新邀请中心与个人看板，并隐藏常用功能里的入口。
 - `玩家社区` 弹窗展示两个紧凑二维码图片区，保留微信群与 QQ 群短标签。
-- 弹窗文案只保留必要标签和短提示，不放长规则说明。
+- 弹窗文案只保留必要标签和短提示；本次邀请奖励规则属于必要交易说明，固定展示在邀请码下方。