---
name: genarrative-profile-invite-flow
description: 在 Genarrative 中排查或修改邀请码、邀请好友、首次登录后填写邀请码、我的页签邀请码兑换链路时使用。
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [Genarrative, 邀请码, referral, auth, profile, query-params, 前端]
    related_skills: []
---

# Genarrative 邀请码与邀请好友流程

用于排查或修改 Genarrative 的邀请码读取、填写、兑换、邀请中心与“我的”页签相关能力。

## 适用场景

- 判断 URL query 参数中的邀请码是否被读取。
- 修改邀请码填写入口、首次登录后引导或“我的”页签兑换入口。
- 排查邀请码预填、兑换、已填写状态、邀请好友复制链接。
- 修改邀请中心 API client 或前端 referral UI。
- 回答用户关于“邀请码在哪里填 / 从哪里配置 / query 是否支持”的问题。

## 先做代码核对，不要只凭旧记忆回答

邀请码流程近期发生过迁移：不要默认认为登录窗口可填写邀请码。回答前优先搜索并核对当前代码，尤其是：

```bash
cd <repo-root>
python3 - <<'PY'
from pathlib import Path
root=Path('src')
terms=['RegistrationInviteModal','readInviteCodeFromLocation','referralRedeemCode','redeemRpgProfileReferralInviteCode','邀请码','inviteCode']
for term in terms:
    print('\n---', term)
    for p in root.rglob('*'):
        if p.is_file() and p.suffix in ['.ts', '.tsx']:
            try:
                txt=p.read_text('utf-8')
            except Exception:
                continue
            if term in txt:
                for i, line in enumerate(txt.splitlines(), 1):
                    if term in line:
                        print(f'{p}:{i}:{line.strip()[:180]}')
```

## 当前前端链路口径

### 1. AuthGate 中仍有旧 query 读取逻辑

文件：
- `src/components/auth/AuthGate.tsx`

重点函数 / 状态：
- `readInviteCodeFromLocation()`
- `pendingInviteCode`
- `showRegistrationInviteModal`
- `RegistrationInviteModal`

当前旧逻辑会读取：
- `?inviteCode=...`
- `?invite_code=...`

并把值清洗为大写字母数字形式。

### 2. 登录窗口本身不再填写邀请码

不要回答“登录窗口可填写邀请码”。当前登录弹窗 `LoginScreen` 只负责登录 / 注册账号；邀请码填写已迁移到登录后的流程。

### 3. 新版“我的”页签兑换入口在 RpgEntryHomeView

文件：
- `src/components/rpg-entry/RpgEntryHomeView.tsx`

重点常量 / 函数 / 状态：
- `PROFILE_INVITE_QUERY_KEYS`：新版 query 支持 `inviteCode` / `invite_code`。
- `normalizeProfileInviteQueryCode()`：去掉非字母数字并转大写。
- `readProfileInviteCodeFromLocationSearch()`：从 `window.location.search` 读取并 normalize。
- `pendingProfileInviteCode`：组件初始化时读取 query 邀请码。
- `referralCenter`
- `referralRedeemCode`
- `setReferralRedeemCode`
- `openProfilePopupPanel('redeem')`
- `submitReferralRedeemCode()`
- `canShowReferralRedeemShortcut`
- `isWithinProfileInviteRedeemWindow(authUi?.user?.createdAt)`

UI 中“填邀请码”面板会使用 `referralRedeemCode` 作为输入值，并通过 `submitReferralRedeemCode()` 提交。当前新版实现会在首次打开“填邀请码”面板时用 `pendingProfileInviteCode` 预填输入框；例如 `/?inviteCode=spring-2026` 会预填为 `SPRING2026`。

### 4. 新版兑换 API client

文件：
- `src/services/rpg-entry/rpgProfileClient.ts`

函数：
- `getRpgProfileReferralInviteCenter()` -> `GET /profile/referrals/invite-center`
- `redeemRpgProfileReferralInviteCode(inviteCode)` -> `POST /profile/referrals/redeem-code`

## 判断 query 参数是否真正接入新版流程

回答这类问题时要区分两层：

1. “是否存在旧 query 读取代码”：看 `AuthGate.tsx` 的 `readInviteCodeFromLocation()`。
2. “query 是否接到新版填写入口”：看 `RpgEntryHomeView.tsx` 是否存在 `pendingProfileInviteCode` / `readProfileInviteCodeFromLocationSearch()`，以及打开 `openProfilePopupPanel('redeem')` 时是否把该值写回 `referralRedeemCode`。

当前新版流程已经支持 `inviteCode` / `invite_code` query 预填“我的”页签的“填邀请码”弹窗；登录窗口仍不填写邀请码。

如果未来代码只看到 AuthGate 读 query，但没有看到 `RpgEntryHomeView` 的 `referralRedeemCode` 从 query 初始化，就应回答：

> 代码里仍支持读取 `inviteCode` / `invite_code`，但新版“第一次登录后 / 我的页签”的填写入口未必已经完整接入该 query 值；需要继续把 query 值传入新版 profile referral redeem 流程。

## 修改建议顺序

如果要把 query 邀请码完整接入新版流程，建议按这个顺序做：

1. 先确定 query 参数规范：继续支持 `inviteCode` / `invite_code`，并统一 normalize。
2. 在 `RpgEntryHomeView.tsx` 内用 `readProfileInviteCodeFromLocationSearch(window.location.search)` 初始化 `pendingProfileInviteCode`。
3. 用 `pendingProfileInviteCode` 初始化 `referralRedeemCode`，并在 `openProfilePopupPanel('redeem')` 时重新写回，避免关闭后再次打开被清空。
4. 如产品要求自动弹出：
   - 有 `pendingProfileInviteCode` 且未登录时，自动调用 `authUi?.openLoginModal()` 打开登录窗口；登录窗口仍不承接邀请码输入。
   - 有 `pendingProfileInviteCode` 且已登录时，自动将 `referralRedeemCode` 设为该 query 邀请码，并 `setProfilePopupPanel('redeem')` 直接打开“填邀请码”面板。
   - 用 `useRef` 记录是否已处理过当前 query，避免组件重渲染或 `authUi` 对象变化导致重复弹窗。
   - 当前项目实现已从“只预填、不自动弹”调整为上述行为。
5. 兑换成功后清理输入态；是否清理 URL query 需由产品决定，避免破坏分享链接归因。
6. 补测试覆盖：未登录访问带 query、已登录访问带 query 自动打开填写面板、我的页签手动打开、已填写邀请码、过期窗口、空/非法 query。当前已有 `RpgEntryHomeView.recharge.test.tsx` 覆盖：
   - `invite query opens login modal for logged out users`
   - `invite query opens redeem modal directly for logged in users`
   - `profile redeem invite modal reads query invite code after login`

## 常见坑

1. 不要把旧 `RegistrationInviteModal` 误认为当前唯一入口。
2. 不要说“登录窗口可以填写邀请码”，除非当前代码重新把邀请码输入放回 `LoginScreen`。
3. `AuthGate` 读到 query 不等于新版 `RpgEntryHomeView` 已经预填。
4. “第一次登录后”与“我的页签”可能是两个入口；修改时要同时检查自动引导和手动入口。
5. `canShowReferralRedeemShortcut` 受登录态、创建时间窗口、邀请中心初始化、已兑换状态共同影响。
6. 邀请码 URL 通常由 `inviteLinkPath` 生成，复制逻辑在 `copyInviteInfo()`，不要只改兑换入口而忘记分享链接格式。

## 参考资料

- `references/query-invite-code-flow-2026-05-07.md`：本次会话确认的邀请码 query 与新版 profile referral 入口关系。

## 验证标准

- 能明确回答当前 query 参数读取位置与参数名。
- 能区分旧 AuthGate 邀请弹窗与新版“我的”页签 referral redeem。
- 若实现改动，测试覆盖带 query 的登录后预填/弹窗行为，以及已填写邀请码时不再提示。