init with react+axum+spacetimedb

docs/technical/MY_TAB_REFERRAL_AND_COMMUNITY_IMPLEMENTATION_2026-04-25.md

@@ -0,0 +1,80 @@
+# 我的 Tab 邀请与玩家社区首期落地方案
+
+更新时间：`2026-04-25`
+
+## 目标
+
+在现有“我的”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`
+
+## 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`
+
+返回当前用户的邀请码、邀请链接、今日奖励次数、剩余奖励次数、已绑定状态与奖励参数。
+
+### `POST /api/runtime/profile/referrals/redeem-code`
+
+请求体：
+
+```json
+{
+  "inviteCode": "ABCD1234"
+}
+```
+
+返回绑定后的邀请中心状态与本次奖励发放结果。
+
+## 落地状态
+
+- `server-rs/crates/spacetime-module` 已新增邀请码与邀请关系表，邀请中心读取和填码绑定均通过 SpacetimeDB procedure 执行。
+- `server-rs/crates/api-server` 已挂接 `/api/runtime/profile/referrals/*` 与 `/api/profile/referrals/*` 两组路由。
+- 前端“我的”Tab 三个快捷入口均打开独立弹窗，玩家社区先使用空白二维码占位。
+- 复制邀请会复制邀请码和邀请链接；填码成功后刷新个人看板叙世币。
+
+## 前端交互
+
+- 三个入口继续放在“我的”Tab 常用功能区，不新增页面。
+- `邀请好友` 弹窗展示邀请码、复制按钮、邀请链接。
+- `填邀请码` 弹窗在未绑定时展示输入框；已绑定时展示短状态。
+- `玩家社区` 弹窗展示两个紧凑二维码占位区。
+- 弹窗文案只保留必要标签和短提示，不放长规则说明。