> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/rewards-and-referrals.md).

# 奖励与推荐

OpenHuman 将三种松散相关的增长机制整合在一个界面下：一个 **推荐计划** （分享一个代码，好友转化后赚取积分）， **促销优惠券** （兑换代码以获得促销积分），以及一个 **社区奖励** 追踪（绑定 Discord，随着你达成使用里程碑解锁角色）。邀请码管理位于独立页面。

所有这些都需要已登录的后端会话。在仅本地会话下，Rewards 页面会显示一个空状态，提示你登录——这些功能在离线时都不可用。

***

## Rewards 页面

位于 `/rewards` ，有三个标签页。中间的 **奖励** （社区）标签页默认选中。

| 标签页     | 作用                      |
| ------- | ----------------------- |
| **推荐**  | 你的推荐代码、收益和被推荐用户活动       |
| **奖励**  | Discord 连接、进度环和可解锁的社区角色 |
| **优惠券** | 兑换促销代码以获得促销积分 + 兑换历史    |

***

## 推荐

每个账户只有一个 **推荐代码**。复制它，或使用 **分享** （原生分享表单，回退到剪贴板）发送一条预填充的消息，其中包含你的代码和应用下载链接。

该标签页显示四个卡片：你的代码、 **总收益** （美元）， **待处理推荐**，以及 **已完成** 推荐。它们下方有一个 **活动表** 列出每个被推荐用户（脱敏身份，例如 `j***@gmail.com`），状态徽标、奖励金额和时间戳。

| 推荐状态 | 含义                 |
| ---- | ------------------ |
| 已加入  | 被推荐用户已注册，但尚未转化     |
| 已完成  | 被推荐用户已转化 - 推荐奖励已记入 |
| 已过期  | 关系失效（保留；由后端驱动）     |

如果你是被别人推荐的，并且仍然符合资格，则会有一个 **申请** 表单允许你输入他们的代码。资格（`canApplyReferral`）由后端决定——通常只有尚未订阅或尚未应用代码的用户才能领取。应用后，表单会被已关联代码的确认信息替代。

奖励金额、转化规则和资格都在 **服务器端**执行。这里桌面核心只是一个薄适配层。

### 底层实现

推荐领域（`src/openhuman/referral/`）是一个无状态的 RPC 适配器，不是业务逻辑。之所以存在，是因为桌面 WebView 的 `fetch` 可能会以通用的“Load failed”（CORS/TLS/WebKit）失败，因此这些调用复用了与计费相同的服务器端 `reqwest` 路径。

| RPC                  | 后端调用                   | 用途                    |
| -------------------- | ---------------------- | --------------------- |
| `referral.get_stats` | `GET /referral/stats`  | 代码、总计和被推荐用户行          |
| `referral.claim`     | `POST /referral/claim` | 应用推荐代码（可选设备指纹，用于滥用信号） |

两者在以下情况下都会失败并关闭： `没有后端会话令牌` 当未存储会话时。

***

## 优惠券（兑换）

Coupons 标签页用于兑换 **促销代码** 以获得促销积分——这与推荐奖励分开。两个卡片显示你的 **促销积分余额** （美元）以及 **已兑换代码数量**。输入代码并兑换；兑换要么立即生效，要么作为 **待处理** 在其取决于后续操作时被接受。

一个 **最近兑换** 表列出每个代码、其奖励金额、状态以及兑换时间。

| 优惠券状态 | 含义           |
| ----- | ------------ |
| 已应用   | 已完成 - 积分已到账  |
| 待执行操作 | 等待触发操作的条件优惠券 |
| 已兑换   | 已接受，尚未完成     |

***

## 社区奖励与 Discord

奖励标签页将使用过程游戏化。一个 **进度环** 展示你在总成就中已解锁多少，并且一个 **角色与奖励** 列表描述每个里程碑（有些附带可选美元积分）。状态徽标（当前连胜、累计代币）在底部概括你的活动。

奖励以 **Discord 角色**的形式发放，因此该标签页围绕绑定你的 Discord 账户构建：

1. **连接 Discord** 运行 OAuth 授权流程（`openhuman.auth.oauth_connect` ，提供方为 `discord`）；成功后快照会刷新并显示你的 Discord 用户名。
2. **加入 Discord** 打开社区服务器邀请。
3. **断开连接** 解除账户关联（清除已存储的 Discord ID，幂等）。

一旦关联，每个已解锁成就都会显示其 Discord 角色分配状态：

| 角色状态  | 含义                    |
| ----- | --------------------- |
| 已分配   | 角色已在服务器上授予            |
| 待处理   | 已解锁，但角色尚未分配           |
| 加入以领取 | 已关联但不在服务器中 - 加入以接收该角色 |

如果你已解锁带有角色的成就但尚未加入服务器，会出现一个 **领取横幅** 提示你加入。成员状态之一是 `member`, `not_in_guild`, `not_linked`，或 `unavailable`.

> 基于 GitHub 的贡献者奖励是一种 **独立的** 机制：一个 GitHub Actions 工作流（`.github/workflows/contributor-rewards.yml`），当贡献者的第一个 PR 合并时，会发布一条 Discord/周边邀请评论。它不属于应用内 Rewards 页面，也不使用应用内 GitHub OAuth。

***

## 邀请码

该 **邀请** 页面（`/invites`）与推荐代码不同。它管理个人 **邀请码** ，用于限制新用户注册：

* **兑换**  - 如果你还没有被邀请，输入邀请码以领取你的名额。
* **你的邀请码**  - 分配给你的代码列表。每一行显示代码（等宽字体）、复制按钮以及 **启用/禁用** 状态。一旦使用次数耗尽，代码就会变为禁用（`currentUses >= maxUses`），并显示是谁领取的。

邀请码包含一个 `类型` (`USER` 或 `CAMPAIGN`), `maxUses`/`currentUses` 计数器，以及一个 `usageHistory` ，记录谁在何时兑换了它们。

***

## 另见

* [计费与使用](/openhuman/zh/gong-neng/billing-and-usage.md)  - 推荐、优惠券和成就积分在这里被消耗。
* [欢迎](/openhuman/zh/gai-shu/readme.md)  - 文档主页。