Genarrative/docs/technical/PROFILE_INVITE_CODE_REGISTRATION_AND_ADMIN_2026-04-30.md

注册环节邀请码与管理员邀请码方案

更新时间：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

请求：

{
  "inviteCode": "SPRING2026",
  "metadata": {
    "campaign": "spring"
  }
}

管理员邀请码写入 SpacetimeDB 时使用虚拟主体：

admin:{管理员用户名}:{邀请码}

管理员码只做归因和被邀请人奖励，不给虚拟主体写邀请人钱包流水。

手机号登录响应新增：

• created：本次登录是否创建新账号。
• referral：注册邀请码绑定结果；仅当本次提交了邀请码时返回。

验收标准

1. 未登录用户访问 /?inviteCode=ABC123 自动打开注册弹窗并预填 ABC123。
2. 有效邀请码注册成功后，被邀请人获得陶泥币奖励，邀请关系落库。
3. 无效邀请码注册成功但不绑定，并返回短提示。
4. 管理员可添加邀请码并写入 metadata，重复提交同管理员同码更新 metadata。
5. 管理员邀请码被使用时不产生 admin:* 虚拟主体的钱包流水。