Implement registration invite code flow and admin invite codes

docs/technical/PROFILE_INVITE_CODE_REGISTRATION_AND_ADMIN_2026-04-30.md

@@ -0,0 +1,55 @@
+# 注册环节邀请码与管理员邀请码方案
+
+更新时间：`2026-04-30`
+
+## 背景
+
+旧版“我的 Tab 填邀请码”设计把邀请码绑定放在登录后的个人面板中，容易让老账号重复发现入口，也不利于承接带邀请码的分享链接。本方案将邀请码填写收口到注册链路：未登录用户打开带 `inviteCode` 或 `invite_code` 查询参数的链接时，前端自动打开注册弹窗并预填邀请码。
+
+## 落地边界
+
+1. 注册入口复用当前手机号验证码登录自动建号能力，不新增独立注册系统。
+2. 已登录用户不自动弹注册弹窗；登录后的“我的 Tab”只保留“邀请好友”，不再提供“填邀请码”入口。
+3. 邀请码只在本次手机号验证码登录创建新账号时尝试绑定。老账号登录时即使请求体带邀请码，也不会绑定。
+4. 链接邀请码无效或不可用时不阻断注册，登录响应返回短错误提示，由前端展示；不写邀请关系、不发邀请奖励。
+5. 普通登录态下的 `/api/profile/referrals/redeem-code` 不再允许手动填码，统一返回“邀请码仅注册时填写”。
+
+## 数据与接口
+
+`profile_invite_code` 增加 `metadata_json` 字段，默认 `{}`，用于保存渠道、活动、批次等元数据。旧迁移导入数据缺失该字段时由 `migration.rs` 补 `{}`。
+
+新增管理员接口：
+
+- `POST /admin/api/profile/invite-codes`
+
+请求：
+
+```json
+{
+  "inviteCode": "SPRING2026",
+  "metadata": {
+    "campaign": "spring"
+  }
+}
+```
+
+管理员邀请码写入 SpacetimeDB 时使用虚拟主体：
+
+```text
+admin:{管理员用户名}:{邀请码}
+```
+
+管理员码只做归因和被邀请人奖励，不给虚拟主体写邀请人钱包流水。
+
+手机号登录响应新增：
+
+- `created`：本次登录是否创建新账号。
+- `referral`：注册邀请码绑定结果；仅当本次提交了邀请码时返回。
+
+## 验收标准
+
+1. 未登录用户访问 `/?inviteCode=ABC123` 自动打开注册弹窗并预填 `ABC123`。
+2. 有效邀请码注册成功后，被邀请人获得陶泥币奖励，邀请关系落库。
+3. 无效邀请码注册成功但不绑定，并返回短提示。
+4. 管理员可添加邀请码并写入 metadata，重复提交同管理员同码更新 metadata。
+5. 管理员邀请码被使用时不产生 `admin:*` 虚拟主体的钱包流水。