注册奖励小程序 - 用户指南
注册奖励小程序会在新会员完成注册的瞬间，自动给他们发放欢迎奖励（代币和/或优惠券）。会员不需要做任何操作；奖励是自动发放的。运营人员通过 Ops 后台选择奖励内容，并决定是否开启活动。
说明： 本小程序没有会员页面。新会员只会在注册成功后，看到奖励出现在自己的钱包中。运营人员通过 Admin Portal 进入 Ops 后台。
目录
1. 如何进入
会员端
- 什么都不用做。新会员完成 VIO 注册后，欢迎奖励会在后台自动派发。
- 会员端没有入口图标、没有扫码、也没有领取按钮。
运营端（Ops 后台）
- 使用拥有该租户权限的账号登录 Admin Portal。
- 从 Dashboard 或 Mini Apps 区域打开 Register。Ops 后台会嵌入到 Admin Portal 中加载。
- 页面标题为 Registration Reward，副标题 Configure rewards and review grant history，右上角是 VIO External API key 按钮。
- 标题下方有两个页签：
- Reward configuration（默认落地页）— 配置代币 / 优惠券，并控制活动的开关。
- Grant history — 查看每一笔尝试发放的注册记录，并对失败行进行重发。
说明： 运营人员访问需要由租户管理员在 Admin Portal 配置相应权限。Ops 后台还要求该租户已保存 VIO External API Key，否则无法发放奖励。详见 第 3 节。
2. 会员体验
注册奖励没有专门的会员页面。会员在 VIO 完成注册后，已配置的代币与优惠券会在后台自动发放，并在会员端常规的几个位置出现。
| 位置 | 会员需查看的内容 |
|---|---|
| Home - Balance | 代币余额按已配置数量增加。具体标签与图标取决于 VIO 中该代币的设置。 |
| Transaction History | 新增一条与代币奖励对应的交易记录，时间戳为平台实际发放的时间。 |
| Vouchers | 每个成功发放的优惠券奖励项都会生成一张新的优惠券卡片，名称、图片、有效期直接取自 VIO。 |
提示： 奖励由 VIO 平台排队发放，不一定立刻出现。如果会员刚注册完就没看到奖励，请稍等片刻并刷新对应页面。若几分钟后仍未到账，运营人员可到 Ops 后台的 Grant history 查看发放状态。
3. VIO External API Key 入口
首次进入 Ops 后台（或租户没保存密钥时）会弹出 VIO External API Key 拦截弹窗。该弹窗无法通过点击外部空白关闭——必须保存有效密钥后，Ops 后台的其他功能才会解锁。没有密钥的情况下，系统可以记录注册，但无法发放代币 / 优惠券。
操作步骤：
Step 1：获取 API Key
- 在 VIO Admin Portal 的 API Keys 区域获取该租户的 API Key。
- 密钥以
vio_live_…开头。每个租户都有自己独立的密钥。
Step 2：填入 API Key
- 将密钥粘贴到输入框。输入框的占位文案为 Paste your vio_live_… key。
- 如果你提交空值，弹窗会显示 Paste your VIO External API key to continue.
Step 3：提交保存
- 点击 Confirm 保存。请求期间按钮文案变为 Saving…。
- 保存成功后弹窗自动关闭，Reward configuration 页签随即可用。
- 保存失败时弹窗会保留在原位并显示后端返回的错误信息——请修正密钥后重试。
如需稍后更换密钥，点击页头右上角的 VIO External API key 按钮即可再次打开同一个弹窗，保存后会覆盖原有密钥。
说明： 密钥保存在服务器端，不会写入浏览器。只有拥有 Admin Portal 权限的运营人员可以更新。请在此处轮换密钥，不要粘贴到其他后台或通过不安全的渠道分享。
4. Ops 后台 - 奖励配置
Reward configuration 页签是默认落地页，整体采用两步式布局：
- Step 1 — Reward items：搭建新会员将收到的代币 / 优惠券列表。
- Step 2 — Registration rewards：把开关打开，让该列表真正生效。
4.1 Step 1 — Reward items
该列表展示新会员完成注册后将获得的全部奖励项。
| 控件 | 用途 |
|---|---|
| Add token | 从 VIO 选择一个代币，并设置每位新会员可获得的数量。 |
| Add voucher | 从 VIO 选择一个优惠券。 |
| Edit | 修改已有行的代币数量或代币 / 优惠券选择。 |
| Remove | 删除一行。 |
| Save reward list | 保存所有改动。在你点击保存之前，新注册不会受到任何影响。 |
说明： 列表为空时显示 No reward items yet。每一条已保存的奖励项都会以 Token 或 Voucher 徽标加奖励名称的方式呈现。
操作步骤：
Step 1：添加一个奖励
- 点击 Add token 或 Add voucher，会打开对应的选择弹窗：
- Select token — 顶部有搜索框，下方是可滚动的代币列表（图标、名称、symbol、总供应量 / 可用余额）。选中一个代币，输入 Amount（每位新会员可获得的数量），然后点 OK。可用余额为 0 的代币会变灰，无法选择。
- Select voucher — 顶部搜索框，下方是可滚动的优惠券列表（图片、名称、面额、库存如 Unlimited stock / N left / Sold out，以及人均上限）。选中一个优惠券后点 OK。已售罄的优惠券会变灰，无法选择。
- 两个弹窗都有 Cancel 按钮以及右上角的关闭（✕）按钮，可直接退出不保存。点击 OK 后，新奖励项会作为一行出现在列表中，但还未真正保存——它只是一个本地待保存的改动，直到你在 Step 3 点击 Save reward list。
Step 2：调整列表
- Edit 会以现有数值预填的方式重新打开同一个选择弹窗。修改数量或选择后点 OK，对应行就会更新。
- Remove 会弹出确认对话框 Remove this reward?，包含 Cancel 与 Remove 两个按钮。选择 Remove 删除该行；选择 Cancel 保留。
- 与 Step 1 一样，本步骤的改动都是本地的，必须再点击 Save reward list 才会生效。
Step 3：保存
- 点击 Save reward list。请求期间按钮文案变为 Saving…。
- 保存成功后会出现 Reward list saved Toast，新的列表会立即成为后续新注册使用的版本。
- 保存完成后按钮会置灰（disabled），直到你再次做出改动。
- 如果你刷新页面或离开页面而没保存，任何未保存的改动都会丢失。
4.2 Step 2 — Registration rewards
该卡片决定上一步保存的奖励列表是否真正发放给新会员。
| 控件 | 用途 |
|---|---|
| Grant rewards to new users | 总开关。当前状态会显示在开关旁边的 On 或 Off。 |
| Save registration rewards setting | 保存开关变更。在你点击保存之前，正式环境的状态不会改变。 |
On / Off 各自的作用
- On — 每一位通过 VIO 完成注册的新会员都会自动收到 “已保存奖励列表”中的全部奖励。开启之前必须已经具备：(a) 已保存的 API Key，(b) 至少一条已保存的奖励项；否则保存时会被服务器拒绝，并以错误 Toast 提示原因。
- Off — 后续的新注册不会发放奖励，Grant history 也不会生成记录。已经发到会员钱包里的奖励不会受到影响。
操作步骤：
Step 1：拨动开关
- 把 Grant rewards to new users 切到 On（或 Off）。开关旁边的状态文字会立即更新，但正式系统还没有真正改变。
Step 2：保存
- 点击 Save registration rewards setting。请求期间按钮文案变为 Saving…。
- 保存成功会出现 Toast 提示新状态：Registration rewards enabled 或 Registration rewards disabled。
- 保存完成后按钮会置灰（disabled），直到你再次拨动开关。
- 如果保存失败（例如没有 API Key 或没有奖励项），Toast 会说明原因，正式状态不会被改写。
说明： 把开关切到 Off 仅会停止未来注册的奖励发放。会员钱包里已经发放的奖励仍然保留——没有自动撤回的流程。
5. Ops 后台 - 发放历史
Grant history 页签列出每一次"已尝试发放奖励"的注册。每一笔注册占一组行；如果一次注册包含多种奖励，会在同一时间 / 用户下方以多行展开。
5.1 筛选
本页没有搜索框。请使用顶部筛选器缩小范围。任何筛选条件变化都会自动把分页重置到第 1 页。
| 筛选 | 选项 | 含义 |
|---|---|---|
| Per page | 10、20、50、100 | 单页显示多少笔注册。 |
| Sort | Newest first、Oldest first | 按尝试时间排序。 |
| Overall | All、All sent、Partial、All failed、Unknown | 按注册整体结果筛选（见 §5.2）。 |
| Type | All、Token、Voucher | 按奖励行的类型筛选，用于排查特定失败模式。 |
底部分页按钮（«、‹、›、»）用于翻页；当数据跨多页时，页脚会显示 N record(s) · Rows X–Y of Z。
5.2 表格
每一笔注册占一组行。Time、User、Overall 在每组的第一行显示一次；每条奖励行（Token / Voucher）会在下方多出一行。
| 列 | 说明 |
|---|---|
| Time | 奖励的尝试发放时间。格式遵循浏览器语言环境。 |
| User | 新会员的名称（由 VIO 返回）。 |
| Overall | 这笔注册整体的结果：All sent（全部成功）、Partial（部分成功）、All failed（全部失败）、Unknown（状态仍不明，通常因网络异常）。 |
| Reward type | 该行的徽标：Token 或 Voucher。 |
| Reward name | VIO 返回的代币 / 优惠券名称。 |
| Status | 每条奖励行的状态：Sent（绿色）或 Failed（红色）。Failed 行会显示简短失败原因，例如 Out of stock、Invalid key。 |
| Action | Resend 按钮——仅在失败行可见，且只有具备管理员角色的运营人员可以看到。 |
页面为空时会显示 No grant records yet.，并附说明：新用户完成注册并尝试发放奖励之后，记录就会出现在这里。
5.3 重发失败奖励
当某笔奖励显示 Failed 时，管理员可执行重发：
操作步骤：
Step 1：定位行
- 使用 Overall 筛选（Partial / All failed）找到对应的注册。再用 Type 筛选（Token / Voucher）进一步缩小。
- 同一笔注册可能包含多条奖励行，它们会堆叠在同一组 Time 与 User 下方。
Step 2：定位原因
- 读取失败行上的 Reason 文本，判断为何失败（例如：库存不足、密钥失效、代币余额不足）。
- 请先修复根因再点击 Resend；如果根因没解决，重发依然会失败。
Step 3：重发
- 点击该行的 Resend。请求期间按钮文案变为 Sending…。
- 成功后该行的 Status 变为 Sent，同时这笔注册的 Overall 徽标可能根据其余行的结果，从 Partial 或 All failed 变成 All sent。
- 失败时该行仍保持 Failed，Reason 会更新为最新的错误信息。
说明： Resend 只重发当前这一行奖励，不会重发整笔注册。其他失败行需要分别重发。
6. 业务规则与说明
触发条件
- 当 VIO 平台记录到一次成功注册时，本系统才会自动派发奖励。
- 本小程序不会主动轮询新会员，也不暴露 webhook，完全依赖 VIO 平台来调用它。
每人仅一次
- 每位新会员只会收到一次欢迎奖励。重复触发会被忽略，避免同一次注册被重复发奖。
关闭后的行为
- 把 Grant rewards to new users 切到 Off 仅影响未来注册。
- 没有自动撤回机制——已经发到会员钱包里的奖励不会被回收。
租户差异
- 奖励内容（代币、优惠券、数量）以及每张优惠券的人均上限，都是按租户分别配置的，不同品牌之间可能不同。
访问控制
| 角色 | 会员端 | Ops 后台 |
|---|---|---|
| 普通会员 | 自动获得奖励 | 无访问权限 |
| 租户管理员 | 与普通会员一样自动获得奖励 | 全部权限（Reward configuration、Grant history、Resend） |