推荐小程序 - 用户指南
推荐小程序为每位现有会员生成一个 6 位的个人邀请码。当朋友使用该邀请码完成 VIO 注册时，邀请人和被邀请人都会收到来自同一活动配置的代币奖励。会员在 Member App 中分享并查看邀请；运营人员通过 Ops 后台选择奖励代币、设置奖励数量与每日上限。
说明： 会员通过 Member App 中的 Referral 入口进入小程序；运营人员通过 Admin Portal 进入 Referral Ops Portal。
目录
1. 如何进入
会员端
- 打开 VIO Member App 并登录。
- 在首页 Mini Apps 区域，点击 Referral 入口。
- Referral 首页打开后会显示个人邀请码与奖励说明。无需重新登录——会复用当前 VIO 会话。
说明： 如果会话缺失或过期，会出现身份验证警告。此时仍可浏览页面，但复制邀请码和查看历史可能不可用，请重新登录后再使用。
运营端（Ops 后台）
- 使用拥有该租户权限的账号登录 Admin Portal。
- 从 Dashboard 或 Mini Apps 进入 Referral。Ops 后台会嵌入到 Admin Portal 中加载。
- 顶栏左侧显示 Referral Ops 品牌名，右侧是 Invite history 链接。
- 默认落地页是 Referral rewards，奖励代币、数量、每日上限、以及开关都在该页配置。
说明： 运营人员访问需要由租户管理员在 Admin Portal 配置相应权限。Ops 后台还需要该租户已保存 VIO External API Key，否则代币奖励无法实际发放。详见 §3.2。
2. 会员体验
会员端是一个简短的两页应用：首页显示邀请码、奖励数量与当日进度；历史页列出全部成功邀请。
2.1 顶部导航
每一页都共用同一条顶部导航栏，滚动时也始终可见，方便会员随时知道自己在哪一页。
| 元素 | 用途 |
|---|---|
| Referral（品牌名） | 顶栏左侧的品牌标识。点击会返回 Home 首页。 |
| Home | 顶栏右侧的页签。会员在首页时高亮。点击返回首页，重新加载邀请码、奖励摘要与当日进度。 |
| History | 顶栏右侧的页签。会员在历史页时高亮。点击进入个人邀请记录（详见 §2.6）。 |
说明： 当前页签以胶囊样式高亮，未激活的页签为灰色。该顶栏属于本小程序自身——VIO Member App 自带的页头（含返回按钮与租户信息）位于其上方。
2.2 页面状态
页面根据租户配置呈现以下其中一种状态：
| 状态 | 触发条件 | 会员看到什么 |
|---|---|---|
| 加载中（Loading） | 页面刚打开时 | 显示占位骨架，等待加载个人数据。 |
| 已停用（Disabled） | 租户已关闭推荐奖励 | 红色横幅：Referral program is currently disabled. Invites may still register, but rewards will not be issued. 邀请码仍会展示并可复制，但不会发放任何代币奖励。 |
| 无租户（No tenant） | 当前账号没有 tenant | 黄色横幅：No tenant on your account. Open this app from your organization context. 页面只读。 |
| 正常（Active） | 已配置且已开启 | 完整呈现 hero、邀请码卡、每日进度与历史按钮。 |
| 加载失败（Error） | 接口加载失败 | 红色错误横幅，并显示 Retry 按钮。 |
2.3 Hero — 奖励摘要
顶部卡片告诉双方各能获得多少：
- 主标题： Invite a friend and get {邀请人金额} {代币}
- 副标题： When your friend registers with your code, they get {被邀请人金额} {代币}
代币标签由运营选择（显示 Token 的 symbol 或 name）。如果尚未配置数量，会用短横线 (—) 代替。
2.4 邀请码卡片
中间卡片是真正的邀请码：
- 邀请码： 6 位大写字符。字符集刻意避开易混淆字符（不含
0、O、1、I、L）。 - Copy 按钮： 点击 Copy 把邀请码复制到剪贴板，按钮文案会临时变为 Copied 持续 2 秒以作确认。
- 提示： Share this code with friends. Matching ignores letter case.
提示： 让朋友在 VIO 注册流程中输入或粘贴该邀请码即可。大小写不影响识别。
2.5 当日进度
邀请码卡下方显示当日成功邀请数：
- 标签： Daily successful invites
- 数值： 设置了每日上限时显示
当日 / 上限（例如 3 / 5）；当上限为 0 时显示当日，并附 (no daily cap) 字样。
该计数器只统计当日成功的邀请，按租户的报表时区计算。因当日上限而被跳过的邀请会出现在邀请记录页，但不计入此数。
2.6 邀请记录（会员端）
点击 Invite history 进入会员自己的邀请记录页：
| 字段 | 含义 |
|---|---|
| Friend | 朋友的显示名（取不到时回退为 user ID）。 |
| Your reward | 该笔邀请中邀请人获得的代币奖励。 |
| Time | 邀请记录的时间，按浏览器本地时区显示。 |
页面状态：
| 状态 | 显示内容 |
|---|---|
| 加载中 | 占位骨架。 |
| 空 | 一张卡片显示 No invites yet，副文案 When someone registers with your code and rewards are recorded, entries will appear here. |
| 列表 | 每笔邀请一张卡片，按时间倒序。 |
| 无租户 | 黄色横幅 No tenant on your account. |
按钮：
- ← Back — 返回 Referral 首页。
- Refresh — 重新拉取列表（朋友刚刚注册完时很有用）。
3. Ops 后台 - 推荐奖励
顶部导航
Ops 后台的每一页都共用同一条顶部导航栏，在切换页面时始终保持在原位。
| 元素 | 用途 |
|---|---|
| Referral Ops（品牌） | 顶栏左侧的纯文字标签，不是链接——点击不会跳转。 |
| Invite history | 顶栏右侧的链接。当前在 Invite history 页面时高亮。点击会把页面主体切换到邀请记录页（详见 第 4 节）。 |
说明： 顶栏中没有单独的 Referral rewards 链接——这一页是默认落地视图。从 Invite history 返回 Referral rewards 时，可点击 Referral Ops 品牌所在区域以重新加载后台，或使用浏览器的返回按钮。（品牌文字本身不可点击，但 Ops 后台的默认路由会打开 Referral rewards 页面。）
页面布局
Referral rewards 是 Ops 后台的默认落地页，由从上到下三张卡片组成，建议按顺序完成：
- Referral rewards enabled — 总开关。
- VIO External API key — 必须先保存，否则代币列表与发放都无法工作。
- Reward token and amounts — 选择代币、金额与每日上限。
说明： 如果当前 VIO 用户没有 tenant，页面顶部会出现黄色横幅 Your VIO user has no tenantId. Open this page from the VIO ops context with a tenant. 在恢复租户上下文之前，全部控件都会被禁用。
3.1 推荐奖励开关
总开关决定新会员通过他人邀请码注册时，是否真的派发代币奖励。
| 控件 | 用途 |
|---|---|
| Referral rewards enabled | 开关。旁边文字会显示 Enabled、Disabled，保存中会临时显示 Updating…。 |
On / Off 各自的作用
- Enabled — 每一笔成功邀请都会同时给邀请人和被邀请人发放代币奖励，受每日上限约束。开启前必须已经具备：(a) 已保存的 API Key，(b) 完整的奖励配置（代币 + 邀请人 / 被邀请人金额均大于 0 + 每日上限合法）。否则服务器会拒绝，并在页面顶部出现红色错误横幅。
- Disabled — 邀请仍能正常完成注册（不会阻塞注册流程），但不发放任何代币奖励。会员端会出现红色横幅向邀请人说明这一情况。
操作步骤：
Step 1：切换开关
- 点击开关进行切换。请求期间状态文字短暂显示 Updating…。
Step 2：确认结果
- 保存成功后，文字会稳定为 Enabled 或 Disabled。
- 若服务器拒绝（缺少 API Key 或缺少奖励字段），页面顶部出现红色错误横幅，开关会回滚到原位。
说明： 切到 Disabled 不会撤销已发放的奖励，只是后续的邀请不再发奖。
3.2 VIO External API Key
推荐小程序需要使用 VIO External API Key 来 (a) 加载该租户的代币列表，(b) 实际把代币奖励发到会员手中。每个租户只保存一个密钥。
| 控件 | 用途 |
|---|---|
| 状态块 | 已保存时显示 Key saved + 掩码（如 ****abcd）+ 上次更新时间；未保存时显示 No API key saved yet. |
| API key 输入框 | 密码型输入框。占位文案会根据是否已有密钥而变化。 |
| Save API key | 把粘贴的内容作为该租户的密钥保存。输入为空时按钮被禁用。 |
| Remove saved key | 清除已保存的密钥。未保存密钥或 Referral 开关仍开启时按钮被禁用。 |
操作步骤：
Step 1：获取密钥
- 在 VIO Admin Portal 的 API Keys 区域获取该租户的 API Key。每个租户都有自己独立的密钥。
Step 2：粘贴并保存
- 将密钥粘贴到输入框。未保存时占位文案为 Paste your VIO External API key；已保存时为 Paste only to replace the saved key。
- 点击 Save API key。请求期间按钮文案变为 Saving…。
- 保存成功后状态块更新为 Key saved + 掩码 + 时间戳；第三张卡片中的代币列表会自动重新加载。
Step 3：替换或移除（可选）
- 替换： 粘贴新密钥再次点击 Save API key，旧密钥会被覆盖。
- 移除： 先到 §3.1 把 Referral rewards 切到 Off，然后点击 Remove saved key 并在浏览器确认弹窗中确认 Remove the saved API key for this tenant? The token list and reward calls will stop until you save a new key. 之后状态块回到 No API key saved yet.，代币列表清空。
说明： 密钥保存在服务器端，不会写入浏览器。只有拥有 Admin Portal 权限的运营人员可以更新。请在此处轮换密钥，不要粘贴到其他后台或通过不安全的渠道分享。
3.3 奖励代币与数量
这张卡片决定发什么代币以及双方各发多少。
| 控件 | 用途 |
|---|---|
| Reward token | 下拉菜单，从 VIO 加载的代币列表。每项显示 Name (Symbol) — Available: {balance}。可用余额为 0 的代币会变灰并标注 Unavailable。 |
| Available balance | 下拉下方的副文案，显示已选代币的可发余额。 |
| Inviter amount | 数字输入框，邀请人单次邀请获得的数量。必须大于 0。 |
| Invitee amount | 数字输入框，被邀请人获得的数量。必须大于 0。 |
| Max rewarded invites per day | 整数输入框，每位邀请人的每日上限。0 表示无上限。 |
| Save reward settings | 把上述四个字段作为一组整体保存。未发生变化时按钮禁用。 |
操作步骤：
Step 1：选择代币
- 打开 Reward token 下拉。如果列表为空，先保存 API Key——列表会自动填充。
- 选一个代币。下方 Available balance 行会确认该代币的可发余额。变灰的代币无法选择。
Step 2：设置金额与每日上限
- 在 Inviter amount 和 Invitee amount 各填入一个正数。
- 设置 Max rewarded invites per day，例如 5 表示每位邀请人每天最多奖励 5 次邀请，0 表示不设上限。
Step 3：保存
- 点击 Save reward settings。请求期间按钮文案变为 Saving…。
- 保存成功后按钮会置灰（disabled），直到你再次修改字段。新值只对未来的邀请生效。
说明： 一旦邀请人达到当日上限，当天的后续成功邀请仍会被注册并出现在 Invite history，但奖励会被跳过并标记为 Daily reward limit reached。上限会在租户报表时区的午夜重置。
4. Ops 后台 - 邀请记录
Invite history 页签列出该租户的全部邀请事件，无论奖励是已发送、被跳过还是失败。
4.1 Records 卡片
| 控件 | 用途 |
|---|---|
| 总计 | 副文案 Total {N} (showing {M} on this page) — 反映最近一次拉取的结果。 |
| Refresh | 重新加载列表，请求期间显示 Refreshing…。 |
4.2 表格
每一行代表一次邀请事件，按时间倒序。
| 列 | 含义 |
|---|---|
| Inviter | 邀请人的显示名，取不到时回退为 user ID。 |
| Invitee | 被邀请人的显示名，取不到时回退为 user ID。 |
| Time | 邀请记录的时间，按浏览器本地时区显示。 |
| Inviter reward send | 邀请人代币奖励的发送状态——Sent、Failed ({reason})、Skipped (rate limit)、Skipped (not configured)，旧数据可能显示对应的兼容文案。 |
| Invitee reward send | 同上，针对被邀请人代币。 |
| Tokens (Inviter / Invitee) | 易读的汇总，例如 Inviter: [amount] [token name] / Invitee: [amount] [token name]。 |
| Status | 整笔事件的徽标，详见 §4.3。 |
无数据时表格显示：No records yet. Rows appear when the referral flow writes invite events.
4.3 状态徽标
最右一列在每行显示一个徽标：
| 徽标 | 含义 |
|---|---|
| Success（绿色） | 双方代币奖励都已发送。 |
| Daily reward limit reached（黄色） | 邀请已被记录，但邀请人当日上限已用完，未发送代币奖励。 |
| Send failed（红色） | 至少有一方代币发送失败。具体原因查看两个 reward send 列（例如 Failed (Out of stock)、Failed (Invalid key)）。 |
| 其他 | 兼容旧数据的兜底文字。 |
说明： 本页没有重发按钮。若需修复，请先解决根因（密钥、余额或配置），并请邀请人再次发起邀请；也可让租户管理员复核记录。
5. 业务规则与说明
邀请码生成规则
- 每位会员在首次打开本小程序时，会自动生成唯一的一个 6 位邀请码，之后所有邀请都复用该码。
- 字符集刻意避开易混淆字符——使用数字 2–9 与大写字母（不含 0、O、1、I、L），以减少口述或转写时的歧义。
- 邀请码匹配不区分大小写——
abcd23与ABCD23等同。
一码多用
- 同一个邀请码可被许多不同的朋友使用，每一次成功注册都会在邀请记录中生成一行。
- 一位朋友在注册时只能使用一个邀请码。
每日上限
- 上限按邀请人、按自然日计算（采用租户报表时区）。
- 达到上限后，当天的后续邀请仍能正常完成注册，但邀请人 / 被邀请人代币奖励会被跳过并标记为 Daily reward limit reached。
- 设为 0 表示无上限。上限数值上没有强制最大值，但数字过大可能会很快消耗代币余额，请密切关注 §3.3 中的 Available balance。
奖励发放时机
- 当朋友通过邀请码完成 VIO 注册的那一刻，邀请人与被邀请人的代币奖励同时发出。
- 若 Referral rewards 开关为 Off，注册依然允许并写入历史记录，但双方代币都不会发送。
租户差异
- 奖励代币、数量、每日上限以及 API Key 都是按租户分别配置，不同品牌可能完全不同。
访问控制
| 角色 | 会员端 | Ops 后台 |
|---|---|---|
| 普通会员 | 可查看与复制自己的邀请码，并查看自己的邀请记录。 | 无访问权限 |
| 租户管理员 | 与普通会员一样 | 全部权限（Referral rewards、Invite history） |
另请参阅：Mini Apps 总览、每日签到小程序、注册奖励小程序。