集印章小程序 - 用户指南
集印章（Stamp）小程序是一个"集印章、抽奖品"的会员忠诚度计划。会员通过到合作商户消费来获得印章，集满 5 个印章后点击 Redeem 按钮，按运营人员配置的中奖概率随机抽中一个奖品（代币或礼券）。
说明： 本小程序面向三类用户，对应三个入口：
- 会员：在 VIO 会员端首页打开 Stamp Collect 入口。
- 商户员工：在专用的商户设备上扫描会员二维码，进入 Merchant 页面，输入运营 PIN 后确认收据。
- 运营 / 品牌管理员：通过 Admin Portal 打开 Stamp Ops Portal，管理奖品、查看记录并编辑会员端说明文案。
目录
1. 如何进入
会员（PWA）
- 打开 VIO 会员端并登录。
- 在首页的 Mini Apps 区域点击 Stamp Collect 入口。小程序会复用现有 VIO 会话，无需另行登录。
- 顶部栏左侧显示返回箭头（<），中间显示标题 Stamp Collect。
说明： 如果当前没有有效的 VIO 会话，会员端将无法生成会员二维码，Collect 流程也无法开始。请先登录会员端再进入入口。
商户员工（Merchant 页面）
商户员工不需要登录任何账户。他们在专用的商户设备上操作，流程是：
- 设备打开会员二维码中携带的 URL（
/#merchant/pin），顶部显示 Enter PIN。 - 员工输入 Operator PIN（共 6 位：前 2 位字母 + 后 4 位数字，例如
AB-1234）。 - PIN 校验通过后，设备跳转到 Action Center 页面，由员工输入收据金额并选择门店位置，然后确认。
管理员（Ops 后台）
- 打开 Admin Portal 并以租户账号登录。
- 从 Dashboard 或 Mini Apps 入口打开 Stamp。Stamp Ops Portal 会在 Admin Portal 的框架内加载。
- 默认进入 Collect Stamp 页面：标题 Collect Stamp、右上角 Edit PWA Configuration 按钮、Program Summary 卡片，以及 Stamp Collections / Reward Records 两个页签。
说明： 运营访问权限需由租户管理员在 Admin Portal 中分配。
2. 会员端 - Stamp Collect
会员端是单页面：5 个印章位、一个 Redeem 按钮，以及一个 "How to collect stamps?" 链接。
2.1 页面布局
| 元素 | 用途 |
|---|---|
| <（返回箭头） | 顶部左上角的返回按钮，返回到打开小程序时的页面（即传入的 redirect URL）。 |
| Stamp Collect（标题） | 顶部栏的页面标题。 |
| Visit Merchants to Claim Free Vouchers or Tokens! | 顶部下方的主标语。 |
| Turn your visits into rewards by collecting stamps! | 主标语下方的副标语。 |
| 印章网格 | 5 个圆形印章位，按 2 - 1 - 2 排列（第 1 行印章 1 和 2，第 2 行印章 4 和 3，第 3 行中间是印章 5）。第 5 个是 Reward stamp，样式跟前 4 个 Store stamp 不同。 |
| Redeem（按钮） | 5 个印章未集齐前保持灰色不可点。 |
| You've collected N/5 stamps. | Redeem 按钮下方的实时计数。 |
| How to collect stamps? | 页面底部的链接，点击打开说明弹窗（弹窗内容由运营在 Ops 后台编辑，见 §4.1）。 |
2.2 收集印章
印章不能光靠点击获得 —— 必须由商户扫码确认收据，会员的角色是出示二维码。
操作步骤：
Step 1：点击下一个印章位
- 第一个未收集的印章位可点击；已收集的印章位、以及暂时还轮不到的印章位都处于不可点状态。
- 点击可点的印章位会弹出 Membership QR Code 弹窗，显示会员的二维码以及用户名。如果二维码还在生成中，则同一位置显示 Generating QR Code... 占位文字。
Step 2：把二维码出示给商户员工
- 商户员工在自己的设备上扫描该二维码，二维码内含会员的 user ID、用户名以及钱包地址。
- 当商户在自己一侧确认收据后，会员页面会实时更新：
- 对应印章位播放"印章已盖上"的动画。
- 弹出 Stamp Collected! 弹窗，内容为 You have successfully collected a stamp! You can collect only one stamp per store per day. Visit other stores to collect more stamps.，附带 Done 按钮。
- 当前印章到下一个印章的连接线 / 弧线被填满。
Step 3：重复完成印章 1 到 4
- 同一天里每个印章必须来自不同的门店 —— 同一天再次在同一门店领取会被系统拦截。此时会员端会弹 Stamp Collected Here 弹窗，文案为 You've already collected a stamp today. Come back tomorrow for your next stamp!
Step 4：领取 Reward stamp（第 5 格）
- 第 5 格的样式不同（Reward stamp）。同样点击它、走"扫码 + 确认"流程。
- 成功后 Stamp Collected! 弹窗的文案更强：You have successfully collected all stamps! Redeem your reward now!，附带 Done 按钮。
提示： 印章网格上不会显示门店名。"同一门店每天最多 1 个印章"的规则由商户设备在后台统一校验，会员不需要自己记录。
2.3 抽奖
当 5 个印章全部点亮后，Redeem 按钮被激活。
操作步骤：
Step 1：点击 Redeem
- 系统自动抽取一个奖品，按运营在 Ops 后台为每个奖品设定的 Winning Probability (%) 进行加权随机（见 §5.1）。
Step 2：查看结果
- 弹出庆祝弹窗，主标题 Congratulations!，副标题 Hooray! You get {prize name}!
- 视觉根据奖品类型不同：
- Voucher —— 显示一张卡片，包含礼券图、名称与有效期。
- Token —— 显示两个圆形代币图标，下方有 +{amount} 徽标。
- 点击 Done 按钮关闭弹窗。
Step 3：关闭弹窗之后
- 5 个印章被全部清空，页面重新加载。
- 当前页面回到 0 / 5 印章，进入新一轮收集。已经发放的奖品仍保留在会员的钱包里。
说明： 一次只展示一个奖品。如果运营还没配置任何奖品就点了 Redeem，会出错误 Toast：No rewards available at this moment. 此时不会消耗印章，会员稍后可以再试。
2.4 How to Collect Stamps? 弹窗
点击落地页底部的 How to collect stamps? 即可打开说明弹窗。
| 部分 | 内容 |
|---|---|
| 标题 | How to Collect Stamps? —— 固定文字。 |
| 正文 | 展示给会员的编号步骤说明。由运营在 Ops 后台的 Collect Stamp > Edit PWA Configuration 中设置（见 §4.1）。默认文案为 1) Visit a nearby merchant. 2) Make any purchase at the store. 3) Click on the stamp icon. 4) Show the QR code to the staff to collect your stamp. 5) When all stamps are collected, click on 'Redeem' to claim a reward! |
| 条款 | 两条固定项目 —— By participating the draw you are agreeing to these draw terms and conditions. 及 We reserve the right to amend these terms and conditions at any time without prior notice. 不能从 Ops 后台修改。 |
| 关闭按钮 | 右上角的 X。 |
3. 商户端 - 发放印章
商户端运行在专用设备上。当商户员工扫到会员二维码时，设备会自动打开。
3.1 Enter PIN 页面
扫码后第一页就是 Enter PIN。
| 元素 | 用途 |
|---|---|
| 顶部标题 | Enter PIN（紫色渐变背景）。 |
| 副标题 | Enter Operator PIN，下方辅助文字 Enter your PIN to proceed with Stamp Distribution. |
| PIN 输入框 | 6 个独立小框，格式 AA - 1234：第 1、2 位只能输入字母；第 3、4、5、6 位只能输入数字。第 2、3 位之间显示 - 分隔符。 |
| 状态行 | 设备正在获取会话 token 时，显示一个小转圈和 Initializing session... 文字。 |
| 错误行 | 若 PIN 框输入了非法字符（例如字母框输入数字），下方会显示红字提示 —— First two characters must be letters 或 Last four characters must be numbers。PIN 校验失败时显示 Invalid operator PIN。 |
操作步骤：
Step 1：确认已经扫码成功
- 该页面只在扫码成功后打开，所以会员的 user ID、用户名和钱包地址已经在内部携带好。如果这几项缺失，页面会显示 Invalid QR code. Missing user information. —— 让会员重新打开二维码弹窗，再扫一次。
Step 2：输入 PIN
- 按发给员工的 6 位 PIN 完整输入。字母自动转大写；光标输入后自动跳到下一格。
- Backspace 键会清空当前框；若当前框已经为空，则向前回退一格并清空那一格。
Step 3：等待校验
- 当第 6 个字符输入完毕，PIN 立即开始校验，期间可能短暂显示 Initializing session...。
- 校验通过：设备自动跳转到 Action Center。
- 校验失败：原有的 6 个框保留为可编辑状态，下方显示红色错误提示。
说明： PIN 按商户门店 / 运营进行配置，由品牌管理员定期轮换。请像密码一样对待，不要泄露给运营组之外的人。
3.2 Action Center
PIN 通过后，设备进入 Action Center。
| 字段 | 含义 / 用途 |
|---|---|
| Recipient | 会员的头像（👤）、用户名以及钱包地址 —— 由二维码自动带入，方便员工确认是当前面前的这个顾客。 |
| Operation Type | 固定显示 Stamp Collect。该页面只能发放印章，不能执行其他操作。 |
| Receipt amount | 胶囊形输入框。左侧是币种选择器（默认 HKD$，点击可选其它币种）；右侧是金额输入（数字 + 最多 1 个小数点 + 最多 2 位小数）。下方有辅助文字 Please input receipt amount。校验失败时显示红字。 |
| Store Location | 胶囊形选择器。点击后打开门店位置选择器，范围限定在该运营所属公司之内。必填。 |
| Confirm（按钮） | 两个字段都通过校验前为不可点状态。提交期间显示为 Processing...。 |
操作步骤：
Step 1：核对顾客
- 核实用户名与面前的顾客一致。当多个租户里出现同名用户时，可参考钱包地址作辅助校验。
Step 2：输入金额、选门店
- 如需更换币种，点 HKD$ 切换。
- 输入收据金额。如果输入了非数字，辅助文字会变红并提示 Please enter numbers only。
- 点 Select store location 并选择正确的门店。
Step 3：确认
- 点击 Confirm。提交期间按钮变成 Processing...。
- 一共有三种可能的结果：
- Stamp Collection Approved —— 收据被接受；顾客的印章数 +1。设备跳转到 Stamp Collection Approved 确认页（见 §3.3）。同时顾客一侧的 PWA 也实时更新。
- Already collected today —— 该顾客今天已经在这家门店领过印章。设备显示 Stamp Collection Rejected 状态（见 §3.4）；顾客一侧弹 Stamp Collected Here 弹窗。
- Error —— 其它任何失败原因（会话过期、PIN 失效、缺字段等），设备跳转到 Unexpected Error 页面（见 §3.5）。常见原因会显示更友好的文案，例如 Session expired. Please scan QR code again. 或 Stamp collection is already complete. You have collected all 5 stamps!
说明： 新会话必须重新扫一次码。如果员工看到 Session expired，请让顾客在自己设备上重新打开二维码，然后从 §3.1 开始重新走一遍。
3.3 Stamp Collection Approved
收据被接受后，设备显示确认页面，包含印章编号、时间和收据明细。
| 元素 | 含义 |
|---|---|
| 标题 | Stamp Collection Approved（如果第 5 个印章顺带中奖了，则改为 Congratulations! Prize Won!）。 |
| 副标题 | User has successfully collected stamp #N.（或对应的中奖版本）。 |
| Collection Date and Time | 商户设备的当前日期与时间，例如 dd/mm/yyyy HH:MM:SS。 |
| Stamp Number | #1 到 #5。 |
| Receipt Amount | 上一页输入的币种 + 金额。 |
| Store Location | 选定的门店。 |
| Recipient | 用户名与钱包地址。 |
| Prize Won / Redemption Code（仅第 5 个印章） | 若该次顺带中奖，会显示奖品名称和一串等宽字体的兑奖码。 |
页面上没有按钮 —— 关闭页面或回到起点即可发放下一个印章。
3.4 Stamp Collection Rejected（已经领过）
如果顾客今天已经在同一门店领过印章，Action Center 不会跳到 Approved 页，而是跳到这里。
| 元素 | 含义 |
|---|---|
| 顶部标题 | Action Center（紫色）。 |
| 提示横幅 | 紫色横幅 + ! 图标，文案 This user has already collected a stamp here today. Users only can collect one stamp per day from the same store. |
| Last collected on | 一行 Last collected on dd Mon yyyy, hh:mm AM/PM 格式的时间，若可以拿到上次领取时间。 |
| Recipient | 与 Approved 页相同的 Recipient 区块（头像、用户名、钱包地址）。 |
提示： 商户设备不会自动重试。请告知顾客明天再来，或当天去同品牌下的其他门店。
3.5 Unexpected Error
其他任何失败（网络问题、字段缺失、会话失效、校验错误），都会跳到 Unexpected Error 页面。
| 元素 | 含义 |
|---|---|
| 标题 | Unexpected Error |
| 正文 | 真实的错误文案，例如 Session expired. Please scan QR code again. 若后端返回为空，则兜底显示 There was an unexpected error. Try again after a few seconds. |
错误页没有"重试"按钮 —— 关闭页面、让顾客重新扫码再来一次即可。
4. Ops 后台 - Collect Stamp 页面
Collect Stamp 页面是 Ops 后台的默认落地页，分三块：
- 页面顶部 —— 标题 + Edit PWA Configuration 按钮。
- Program Summary —— 三个一眼可见的统计数字，加一个跳转到 Prize Information 的链接。
- 页签记录区 —— Stamp Collections 与 Reward Records 两个页签，每个页签都有自己的筛选、搜索和分页表格。
4.1 页面顶部
| 元素 | 用途 |
|---|---|
| Collect Stamp（标题） | 页面标题。 |
| Edit PWA Configuration | 打开 PWA Configuration 弹窗，用于编辑会员端 How to Collect Stamps? 弹窗里的说明文字（见 §2.4）。 |
PWA Configuration 弹窗
| 元素 | 用途 |
|---|---|
| 标题 | PWA Configuration。 |
| How to Collect Stamp (User Instructions) | 富文本编辑器，支持基本格式（粗体、斜体、列表、链接）。会预填当前已保存内容；若从未保存过，则使用 5 步的默认文案。 |
| 字符计数 | 编辑器下方显示字符数，最多 2000 字符。 |
| Confirm | 把新的 HTML 保存为会员端说明。编辑器为空时按钮不可点。保存成功后弹绿色 Toast PWA configuration has been updated.，弹窗关闭。 |
| 右上角 X | 不保存直接关闭。未保存的修改丢弃；下次打开会重新拉取最新已保存内容。 |
说明： 会员弹窗底部固定的条款两条不在这里编辑 —— 此处只编辑上方的编号说明。
4.2 Program Summary
页面顶部下方有一张卡片，包含三个一眼可见的统计数字，以及一个跳到 Prize Information 的链接。
| 元素 | 用途 |
|---|---|
| Program Summary | 卡片标题。 |
| View Prize Information | 卡片右上角带下划线的链接，跳转到 Prize Information 页面（见 §5）。 |
| Total Participants | 该租户下，至少领过一个印章的去重用户数。! 图标的 tooltip 文案为 Total number of users who have participated in the stamp collection program。 |
| Total Stamps Collected | 所有参与者累计发出的印章总数。 |
| No. of Redemptions | 已发出奖品的总次数（奖品已经实际进入会员钱包）。 |
加载期间每个数字会显示为 ...。
4.3 Stamp Collections 页签
默认页签，每行一个印章发放记录。
| 元素 | 用途 |
|---|---|
| Stamp Collections（页签） | 当前激活页签。数字反映该租户下累计发出的印章总数。 |
| Search input（占位符 Search by Username） | 按会员用户名筛选表格。 |
| Store Location（筛选器） | 多选 checkbox 筛选，选项来自实际发出过印章的门店。不勾选 = 不筛选。 |
表格列
| 列 | 含义 |
|---|---|
| Collection Date Time | 印章发放时间。 |
| Username | 会员用户名。 |
| Spending Amount | 商户在 Action Center 输入的收据金额，带币种。 |
| Store Location | 印章发放的门店。 |
无数据时显示空状态图和"无记录"提示。分页：每页 6 行。
4.4 Reward Records 页签
每行一次奖品发放尝试。
| 元素 | 用途 |
|---|---|
| Reward Records（页签） | 当前激活页签。 |
| Search input（占位符 Search by Username/ Prize Name） | 在用户名和奖品名上做模糊搜索。 |
| Prize Type（筛选器） | checkbox 筛选，选项为 Voucher 和 Token。 |
| Distribution Status（筛选器） | checkbox 筛选，选项为 Success 和 Fail。 |
表格列
| 列 | 含义 |
|---|---|
| Redemption Date Time | 抽奖时间。 |
| Username | 点击 Redeem 的会员。 |
| Prize Name | 抽奖时的奖品名（例如 5 PTS Token、Free Coffee Voucher）。 |
| Prize Type | 标签：Voucher 或 Token。 |
| Distribution Status | Success（绿色）或 Fail（红色）。Fail 表示奖品被抽中但平台无法发放 —— 展开该行查看失败原因，然后做相应处理。 |
分页：每页 6 行。
说明： 发放失败不会消耗会员的印章，印章保持满格，会员在你修复原因（例如补库存、补代币余额）后可以再次点 Redeem。
5. Ops 后台 - Prize Information
Prize Information 页面路径为 /prize-information，可从 Program Summary 的 View Prize Information 链接进入，也可在面包屑（Collect Stamp > Prize Information）中点回来。
页面下设两个页签：
- Prize Configuration —— 维护可被抽中的奖品列表。
- Prize Claim Statistic —— 查看每个奖品实际被领取的情况。
5.1 Prize Configuration 页签
该页签维护当前生效的奖品池，只有保存在这里的奖品才会参与会员端的随机抽取。
| 元素 | 用途 |
|---|---|
| 橙色提示横幅 | Please set the winning probability for each prize. The total must be 100% or less. |
| Add Prize（按钮） | 打开 Add New Prize 弹窗（见下）。 |
| Search input（占位符 Search in Prize Configuration...） | 按奖品名 / 奖品类型筛选表格。 |
表格列
| 列 | 含义 |
|---|---|
| Prize Name | 显示从所选 token / voucher 拉取的展示名。 |
| Prize Type | 标签：Voucher 或 Token。 |
| Quantity | 剩余数量。代币奖品额外显示一行 Per user: N，表示每次领取的金额。 |
| Winning Probability (%) | 行内可编辑的数字输入，0–100。系统强制所有奖品的概率总和 ≤ 100。如果你的编辑导致总和超过 100，会出校验 Toast，且该行会显示行内错误。 |
| Actions | 行级 Edit 与 Delete 操作。 |
Save Configuration
新增 / 编辑 / 删除 / 修改概率的操作都先在本地暂存，必须点右下角 Save Configuration 才会真正提交。
- 有未保存改动时，按钮旁会出现一个橙色小提示 You have unsaved changes。
- 没有未保存改动时，Save Configuration 按钮处于不可点状态。
- 保存中按钮文字变成 Saving…。
- 保存成功时弹绿色 Toast Prize configuration has been successfully saved to the database.，表格自动重新加载。
- 保存失败时弹红色 Toast Failed to save configuration. Please try again.，本地修改仍保留，可以重试。
Add New Prize 弹窗
从 Prize Configuration 页签右上角的 Add Prize 按钮打开。第一个字段 Prize Type 决定下面显示哪些字段。
| 字段 | 用途 |
|---|---|
| Prize Type | 必填。选择 Voucher 或 Token。下面的字段会随该选择变化。 |
| Voucher（仅 Voucher） | 当 Prize Type = Voucher 时显示。点击 Select 打开 Select Voucher 选择器 —— 可按 Brand、Category、Voucher Type、Country 筛选 VIO 礼券库，或者在 Search by voucher name 输入框搜索，选中一行后点 Confirm。本次配置中已被其他奖品使用过的礼券会被置灰。 |
| Voucher Quantity（仅 Voucher） | 必填。本奖品投入到奖品池的礼券张数。下方辅助文字 Max quantity: N 显示 VIO 中的剩余库存。 |
| Token Type（仅 Token） | 当 Prize Type = Token 时显示，是一个带搜索框的下拉。已被其他奖品使用过的代币会被置灰。 |
| Total Token Quantity（仅 Token） | 必填。本奖品对应的代币总池。下方辅助文字 Max quantity: N 显示所选代币的钱包余额。 |
| Token Per User（仅 Token） | 每位中奖会员领取的代币数。必须在 1 到 Total Token Quantity 之间。 |
| 底部主按钮 | 新建时为 Add Prize，从 Edit 重新打开时为 Confirm。所有必填项校验通过前按钮不可点。 |
说明： Winning Probability (%) 不在这个弹窗里设置 —— 它直接在 Prize Configuration 表格的行内编辑（见 §5.1）。同样，删除奖品也只是本地暂存，必须点击表格右下角的 Save Configuration 才会真正生效。
5.2 Prize Claim Statistic 页签
该页签告诉你每个奖品被领取的实际情况。
| 元素 | 用途 |
|---|---|
| Prize Claim Status | 区块标题。 |
| 时间筛选 | 分段控件：Today、This Week、This Month、All Time。切换会重新拉取表格用的领取数据。 |
| Search input（占位符 Search in Prize Claim Statistic...） | 按奖品名筛选表格。 |
表格列
| 列 | 含义 |
|---|---|
| Prize Name | 奖品。包括已经从配置中删除但仍有历史领取记录的奖品 —— 这类奖品会出现在列表末尾，带 (Deleted) 标签且呈灰色，提示已不再可被抽中。 |
| Prize Type | Voucher 或 Token。 |
| Claims | 一个单一数字 —— 所选时间范围内成功领取的总次数。对代币而言，统计的是发出的代币总量（不是用户数）。 |
说明： 仅统计成功的发放。失败的发放不会计入领取数。
6. 业务规则与说明
集印章周期
- 每个周期 5 个印章 —— 4 个店铺印章 + 1 个奖励印章。
- 同一会员同一门店一天最多领 1 个印章。该规则由商户设备强制执行；同一天再次到同一门店，会员只会看到 Stamp Collected Here 弹窗。
- 5 个印章集满后，Redeem 按钮被激活。一次成功抽奖后，印章计数自动重置为 0 / 5。
抽奖
- 奖品在点击 Redeem 的瞬间抽取，使用 Winning Probability (%) 作为权重。
- 如果还没配置任何奖品，会员端会弹 Toast No rewards available at this moment.，并且不消耗会员的印章。
- 发放失败（例如代币余额已空）同样不消耗印章 —— 会员可以再次尝试。
- 一次成功抽奖后页面会刷新，进入下一个周期。
印章与时区
- "同一门店一天 1 个印章"按商户设备的本地日来计算。不同时区的门店相互独立。
Operator PIN
- 6 位 PIN 的格式为
AA-1234（前 2 位字母，后 4 位数字）。PIN 在底层运营系统中按公司维度配置，不在 Ops 后台维护。 - 字母与数字不能在同一半中混合 —— 商户设备在输入时会即时拦截非法字符。
商户设备能看到的会员数据
- 商户设备只能看到会员的用户名、user ID 与钱包地址 —— 这些信息都通过会员二维码携带。看不到会员的其他 VIO 数据。
- 每个新会话都必须重新扫码；后端的会话有较短的过期窗口。
租户隔离
- 奖品、门店、How to Collect Stamps? 文案以及所有记录都按租户隔离。不同品牌可以有完全不同的配置。
权限对照表
| 角色 | 会员端 | 商户设备 | Ops 后台 |
|---|---|---|---|
| 普通会员 | 收集印章、抽奖 | 无权限 | 无权限 |
| 商户员工 | 用自己的个人账户时，与普通会员一致 | 通过 PIN 校验后可发放印章 | 无权限 |
| 租户管理员 | 与普通会员一致 | 用自己的 PIN 后等同于商户员工 | 全权限（Collect Stamp、Prize Information、Edit PWA Configuration） |