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

docs/technical/README.md

@@ -5,6 +5,7 @@
 ## 文档列表
 
 - [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)：冻结 SpacetimeDB 表结构变更约束、自动迁移可接受范围、冲突后的系统行为，以及保留旧数据的增量迁移流程；凡涉及 `spacetime publish`、表字段调整或 `migration.rs` 对齐时优先参考。
+- [PROFILE_INVITE_CODE_REGISTRATION_AND_ADMIN_2026-04-30.md](./PROFILE_INVITE_CODE_REGISTRATION_AND_ADMIN_2026-04-30.md)：冻结邀请码从“我的 Tab 填写”迁到注册环节的前后端边界、`profile_invite_code.metadata_json` 表结构扩展、管理员邀请码虚拟主体和奖励规则。
 - [PLATFORM_MOBILE_BOTTOM_DOCK_VIEWPORT_FIX_2026-04-30.md](./PLATFORM_MOBILE_BOTTOM_DOCK_VIEWPORT_FIX_2026-04-30.md)：记录平台首页底部 dock 在手机浏览器地址栏展开时脱离可见区域的根因，以及 `100dvh`、固定底部锚点和安全区占位的修复口径。
 - [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md)：记录 SpacetimeDB private 表迁移 JSON 导出/导入 procedure、迁移操作员授权、HTTP 413 分片导入、Jenkins 自动迁移回灌和导入脚本参数。
 - [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)：记录 `Genarrative-Database-Export` / `Genarrative-Database-Import` 两条 SCM-backed 数据库迁移流水线参数、默认 dry-run、token 边界和 `CHUNK_SIZE` 413 规避参数。