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

更新时间：`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:*` 虚拟主体的钱包流水。