幸运抽奖小程序 - 用户指南

欢迎使用 Lucky Draw 小程序。本指南涵盖会员侧抽奖页（在 VIO 会员端中打开）与 Lucky Draw Ops 后台（在 VIO 管理后台中打开），帮助你创建活动、管理奖品并查看效果。

说明： 本小程序是嵌入在 VIO 会员端内部打开的。会员必须先登录 VIO 账号才能参与抽奖；运营人员则通过管理后台进入 Ops 后台。

---

目录

1. 如何进入
2. 会员端界面概览
3. 会员体验 - Lucky Draw
4. 会员体验 - My Rewards
5. Ops 后台 - Lucky Draw History
6. Ops 后台 - Create / Edit Lucky Draw
7. Ops 后台 - Event Dashboard
8. 运营工作流
9. 故障排查
10. 业务规则与说明

---

1. 如何进入

会员（会员端）

1. 打开 VIO 会员端，使用 Email 或 Phone 登录（参见 登录）。
2. 在 Home 中找到 Mini programme，点击 See all 进入小程序网格页（/mini-apps）。
3. 找到标签为 Lucky Draw 的格子（标签可能因租户而异）。
4. 点击该格子进入抽奖页。小程序会在会员端的外壳内加载。

提示： 如果被强制跳回登录页，请重新登录后从 Mini programme 再次打开 Lucky Draw。务必从会员端打开抽奖页，这样 VIO 会话才能正确传入小程序。

运营（Lucky Draw Ops 后台）

1. 打开管理后台并登录。
2. 在 Dashboard 或 Mini Apps 区域，打开 Lucky Draw。
3. Lucky Draw Ops 后台会在管理后台内部打开，默认落地页是 Lucky Draw History。

说明： Ops 后台访问权限由租户管理员在管理后台中配置。Ops 后台还要求该租户已配置 VIO External API Key —— 否则 Create / Edit 向导内的代金券/代币选择器无法加载，奖励也会发放失败。保存 key 的方式参见 注册奖励 - VIO External API Key。

---

2. 会员端界面概览

当 Lucky Draw 在会员端内打开时，页面通常包含以下元素：

UI 元素	用途
Back（会员端外壳左上，← 箭头）	返回上一屏（通常是小程序网格页）。
Title（会员端外壳顶部居中）	显示当前小程序名 Lucky Draw。
Refresh（会员端外壳右上，环形箭头图标）	重载嵌入的小程序并重新下发最新的 VIO 会话 token。当页面卡住或显示过期数据时使用。
My rewards 按钮（抽奖区右上角，礼盒图标）	打开 My rewards（/rewards）查看已赢得的代币和券。该按钮在紫色抽奖卡上，不在会员端外壳里。
Machine / spin area	扭蛋机样式的插画，里面装满胶囊球；SPIN 按钮位于机器正面、出口槽旁。
Event title（机器下方的小号大写标题）	在 Ops 后台中设置的当前事件标题。
Spin status line	当规则为 Per Day / Entire Event 时显示剩余次数（例如 Spins remaining for today: 2）。规则为 Unlimited 时不显示。
Countdown banner	显示 Ends in（进行中）或 Starts in（即将开始）的天/时/分/秒倒计时。
Terms & Conditions 区块	抽奖区下方自动生成的规则（活动时间、参与规则、库存说明）。

提示： Refresh 与 Back 的区别 —— Refresh 仅重载嵌入的小程序（你的抽奖状态可能回到初始加载态，token 会重新下发）；Back 直接离开 Lucky Draw 回到小程序网格页。

提示： 抽奖过程中请留在抽奖页。频繁切应用或浏览器标签可能打断动画与结果反馈。

---

3. 会员体验 - Lucky Draw

3.1 页面状态

抽奖页根据事件配置渲染三种主要状态之一：

状态 A：No Lucky Draw Event

• 日历样式图标，标题 No Lucky Draw Event
• 文案：There are no lucky draw events at this time.

当 Ops 后台未配置事件或 API 没有返回符合条件的事件时显示。

状态 B：Coming Soon（即将开始）

• 沙漏图标，标题 Coming Soon
• 文案：No lucky draw event now, / Next event will start at + 计划开始时间
• Starts in 倒计时（天 · 小时 · 分 · 秒）

倒计时归零时页面自动刷新。

状态 C：Active draw（进行中）

• 扭蛋机样式插画，SPIN 按钮在机器正面，紧邻出口槽。
• My rewards 礼盒按钮叠加在紫色抽奖卡的右上角。
• 事件标题以小号大写标题显示在机器正下方。
• 仅当规则为 Per Day 或 Entire Event 时才显示 Spin status line。
• Grab the Prizes Now! banner 显示 Ends in 倒计时（天/时/分/秒）。
• 倒计时卡片下方为 TERMS & CONDITIONS 区块。

3.2 如何抽奖

使用方法：

1. 从会员端的 Mini programme 打开 Lucky Draw。
2. 查看事件标题、Ends in 倒计时与下方的 Terms & Conditions。
3. 若有显示，查看 Spin status line 中今日或全活动的剩余次数。
4. 点击机器中央的 SPIN。
   • 机器动画播放约 2 秒。
   • 按钮进入忙碌状态 —— 请勿连续点击。
5. 等待结果弹窗。剩余次数会在结果出现后自动刷新。

SPIN 按钮状态

按钮状态	含义
Active（渐变）	活动进行中且仍有次数。
Disabled	活动未启动 / No spins left / 缺少会话之一。
Spinning（带动画）	系统正在处理本次抽奖。

3.3 抽奖后的结果

完成抽奖后，页面会弹出结果弹窗：

结果	弹窗内容
Win — token	标题图 Congratulations!、两个重叠的代币圆形、奖品名称、Hooray! You won {prize name}!、View Rewards 按钮。
Win — voucher	标题图 Congratulations!、带券图与名称的券卡片以及 Valid until / Event ends 日期、Hooray! You won {prize name}!、View Rewards 按钮。
No win	中性结果文案；如规则允许，稍后可再试。
Error	错误标题（例如 Prize delivery failed、Event ended、No spins left、Out of stock）+ 短提示。OK 按钮关闭弹窗。

说明： 看到 Prize delivery failed 时，本次抽奖不会被消耗，可重试。Event ended、Out of stock 等错误则不再接受抽奖。

3.4 Terms & conditions

TERMS & CONDITIONS 区块（标题全大写）显示在倒计时卡片下方。各条目以有序列表（1.、2.、3. …）呈现，由事件配置自动生成。

常见条目包括：

1. 活动时间 —— 例：Event period: May 5, 2026, 03:35 PM to Sep 30, 2026, 03:31 PM.
2. 参与规则 —— 三种之一：
   • You can spin as many times as you like during this event.（Unlimited）
   • Each user can spin up to N times per day.（Per Day）
   • Each user can spin up to N times for the entire event.（Entire Event）
3. 剩余次数（仅 Per Day / Entire Event 适用） —— You currently have N spin(s) left today. / ...left for this event.
4. 库存提示 —— Prizes are subject to availability while stocks last.

提示： 文案由事件设置自动生成。若需调整规则，请在 Ops 后台修改 Participation Limit。

说明： Terms 列表的底部可能被会员端底部导航遮住一部分 —— 在内层滚动可看到最后几条。

3.5 会员侧自查清单（客服宏）

1. 确认会员打开的是正确租户的会员端。
2. 确认当前时间在 active draw 的事件窗口之内。
3. 若提示 No spins left，请等到下一个可参与时段（次日或下一场活动）。
4. 若某奖品没看到，先打开 My rewards（礼盒按钮）再联系客服。

---

4. 会员体验 - My Rewards

My Rewards 列出会员在各场 Lucky Draw 中赢得的代币与券。可从抽奖页右上角的礼盒按钮进入，或直接打开 /rewards。

4.1 你会看到什么

• Back 箭头（左上）：返回 Lucky Draw 页。
• My Rewards 标题。
• 奖励列表 按最新优先排序，每行包含：
  • 奖励图标（券插画或代币圆形）
  • 奖励名称
  • 获得时间
  • 数量徽标（券为 +1，代币按 Tokens per User 配置显示 +N）
• 空状态（暂无奖励）：礼物图标、文案 You haven't won any rewards yet. 以及 Try Lucky Draw 按钮。

4.2 使用方法

1. 点击 Lucky Draw 页右上角的礼盒按钮。
2. 滚动列表浏览，最新奖励在最上方。
3. 点击 voucher 行直接进入会员端的券详情页（/voucher/:userVoucherId）。
   • 该页在小程序 iframe 之外打开，以便会员端能正确显示券详情。
   • 若某券卡片无法解析出会员端 URL，会出现短暂的内联提示 Voucher link is not available。代币行仅展示，不可点击。
4. 使用 Back 箭头返回抽奖页。

提示： 赢得的代币会发到你的 VIO 钱包，也可在会员端 Home -> Balance 与 Transaction History 查看。

---

5. Ops 后台 - Lucky Draw History

Ops 后台默认进入 Lucky Draw History 页面（/）。

5.1 页面结构

区块	内容
Title	Lucky Draw History — Manage and review all lottery events
+ Create Lucky Draw（右上）	打开 Create Lucky Draw 向导。当已存在未发布（Not Launched）事件时禁用 —— 同一时间只允许有一个未发布事件。
搜索框（占位 Search by event title…）	按事件标题过滤列表（按 Enter 搜索）。
Events table	每行一个事件，列见下表。
Empty state	没有事件时显示 No Lucky Draw Events 卡片，提示 Create your first lucky draw event。

事件表的列

列	说明
Event ID	事件的后端标识符。
Event	在向导第 1 步设置的事件标题。
Created	事件创建日期与时间。
Starts	计划开始日期与时间。
Ends	计划结束日期与时间。
Duration	紧凑时长（例 3d · 5h · 12m）。
Status	徽章：In Progress（绿）、Not Launched（蓝）、Ended（灰）。
Actions	Edit（事件 Ended 后隐藏）与 Dashboard（Ended 后变成 View）。

5.2 使用方法

使用方法：

1. 打开管理后台 -> Mini Apps -> Lucky Draw。
2. 用列表顶部的搜索框（占位 Search by event title…），按 Enter 过滤列表。
3. 点击 + Create Lucky Draw 开始创建新事件（参见第 6 节）。
4. 在事件行上：
   • 点击 Edit 修改尚未 Ended 的事件。
   • 点击 Dashboard 打开事件指标（参见第 7 节）；事件 Ended 后按钮显示为 View。
5. 通过 Status 徽章理解生命周期：
   • Not Launched —— 已排期但未开始。
   • In Progress —— 进行中。
   • Ended —— 已超过结束时间。

警告： 同一时间只能存在一个 Not Launched 事件。在你启动或删除现有未发布事件之前，+ Create Lucky Draw 会被禁用（附 tooltip）。

---

6. Ops 后台 - Create / Edit Lucky Draw

Create 与 Edit 共用一个 4 步向导。页面标题为 Create Lucky Draw、Edit Lucky Draw 或 View Lucky Draw（事件 Ended 后只读）。

步骤条：

1. Basic Settings
2. Prize Configuration
3. Rules
4. Confirm & Create（编辑模式下变为 Confirm & Update）

6.1 Step 1 — Basic Settings

使用方法：

1. Event Title（必填）：最多 30 字符，内联计数器显示 N/30。
2. Start Date & Time（必填）：未来日期/时间。若不是编辑已开始的事件，过去时间会被拒绝。
3. End Date & Time（必填）：严格晚于开始时间。如需要，表单会把结束时间自动顺延为开始时间 + 1 小时。
4. Show Lottery Entry After End（开关）：
   • On —— 会员在事件结束之后仍可进入抽奖入口（例如查看规则或历史）。
   • Off —— 结束后抽奖入口被隐藏。

内联校验提示

提示	触发条件
Start time cannot be in the past	Start 被设为过去时间（仅适用新建或尚未开始的事件）。
End time cannot be in the past	End 被设为过去时间。
The end time must be after the start time.	End 早于或等于 Start。
Event time overlaps with existing event: {title}	时间窗口与本租户其他事件重叠。

说明： 对于在打开表单时已经超过开始时间的事件，Start time 字段被锁定（不可编辑），以避免追溯修改影响已参与的会员。

6.2 Step 2 — Prize Configuration

奖品表列出转盘上的奖品。该区块顶部的 Total probability 指示器必须等于 100% 才能提交。

使用方法：

1. 点击 + Add Prize 打开 Add Prize 弹窗。
2. Prize Type（单选）：Token 或 Voucher。
3. Token：
   • 从租户代币列表中选择（下拉）。租户余额为 0 的代币被禁用。
   • 设置 Total Token Quantity (Stock) —— 被代币余额限制。
   • 设置 Tokens per User —— 每位获奖者获得的数量。
4. Voucher：
   • 点击 Select voucher 打开券选择器。使用其中的搜索框（占位 Search by voucher name…）查找券。
   • 不可选的券会显示原因：Already selected、Out of stock 或 Has per-user claim limit。
   • 设置 Stock。表单会按 voucher campaign 的剩余库存限制，并在超出可用量时给出告警。
5. Auto Restock（开关）：开启后配置：
   • Restock Quantity（必须 > 0）
   • Threshold
   • When to restock：Immediately when at/below threshold、At most once per hour、...per day、...per week
   • Max Total Restock（0 = 不限）
6. Probability (%) 在奖品添加后于奖品表内逐行设置。摘要行在总和等于 100% 时显示 Balanced。
7. 在 Actions 列使用 Edit / Delete / Restore 管理奖品行；从转盘上删除的奖品会带 Off wheel 徽章。

校验规则

规则	行为
转盘至少要有一个 active 奖品	否则 Next 按钮 tooltip 显示 At least one active prize must be on the wheel。
每个 active 奖品的概率必须 > 0%	否则 Every active prize must have a probability > 0%。
总概率 = 100%（±0.1%）	否则摘要显示 Over by N% 或 Remaining: N%。
Token 库存 ≤ 租户代币余额	自动限制，并以内联提示说明上限。
Voucher 库存 ≤ campaign 剩余数量	告警出现：Insufficient voucher quantity. Voucher campaign available quantity is N; please reduce the prize stock.

6.3 Step 3 — Rules

配置同一会员的抽奖频率上限。

选项	行为
Unlimited	不限参与次数。
Per Day	每人每天最多抽 N 次，在内联数字框中输入数值。
Entire Event	整个活动期间每人最多抽 N 次，在内联数字框中输入数值。

说明： Per Day 与 Entire Event 的数值必须 ≥ 1，否则向导显示 Participation limit must be >= 1。

6.4 Step 4 — Confirm & Create / Update

最后一步在保存前列出全部信息以供复核：

• Basic settings —— Event title、Start、End、Duration、Show after end。
• Prizes —— 奖品名、Type 徽章、Stock（编辑模式下含 Remaining）、Auto Restock 摘要、Probability。
• Rules —— 参与规则摘要。

操作：

• Previous —— 返回修改。
• Create Lucky Draw（创建）/ Update Lucky Draw（编辑） —— 保存事件。
  • 在编辑模式下点击此按钮会弹出 Save changes? 确认弹窗。

警告： 在进行中的事件上点击 Update Lucky Draw，改动会立即对会员生效。调整日期、奖品、规则时要小心，避免对已参与会员造成不公平。

若在有未保存修改时点击返回箭头，向导会弹出 Leave creation? / Leave without saving? 对话框，提供 Keep editing 和 Leave 选项。

---

7. Ops 后台 - Event Dashboard

在 Lucky Draw History 中点击事件行的 Dashboard（Ended 事件为 View）查看活动表现。

7.1 页面结构

区块	内容
Period filter（顶部）	按钮：Today、This Week、This Month、All Time —— 切换指标窗口。
Stats grid	两个 KPI 卡：Total Participants、Unique Users。
Prize Claim Status	每个奖品一行：Prize Name、Type 徽章、Status（Active / Off wheel）、Total stock、Remaining、Claimed。
Event details	标题、Status 徽章、Start time、End time、Duration、Prizes summary（在转盘 + 归档）、Show after end。
Back 箭头（左上）	返回 Lucky Draw History。
Error banner	API 失败时显示 Failed to load dashboard，可通过返回 History 重试。

说明： 仪表盘上的 Total stock 表示原始库存减去全部已领，再加上补货量；Remaining 表示当前可用的实时库存。

7.2 使用方法

使用方法：

1. 从 Lucky Draw History 点击事件行的 Dashboard（Ended 事件为 View）。
2. 在顶部选择 Period 重新载入对应窗口的指标。
3. 在 Stats grid 中查看 Total Participants 与 Unique Users 的对比 —— 反映总参与人次与去重账号。
4. 滚到 Prize Claim Status 检查每个奖品：
   • 确认 Remaining 在后续活动中是否充足。
   • Off wheel 行为归档奖品（不再参与抽奖，但仍在历史中计数）。
5. 在 Event details 中复核排期与 Show after end 设置后再公告或关闭活动。
6. 使用左上返回箭头回到事件列表。

---

8. 运营工作流

8.1 上线新抽奖

1. 在 Ops 后台创建事件（6.1–6.4）。
2. 在 Confirm & Create 中复核日期、奖品、参与规则。
3. 用测试账号打开会员端并点击 Lucky Draw 格子。
4. 用测试账号抽一次并确认：
   • 结果弹窗显示预期奖品类型。
   • 奖品出现在 My Rewards。
   • 会员端的代币余额 / 券列表反映了本次中奖。
5. 通过推送、新闻文章或营销页向会员通知活动。

8.2 编辑进行中的事件

警告： 编辑 In Progress 事件会影响已参与的会员。除非必要，请避免在活动中途修改日期或奖品结构。

1. 打开 Lucky Draw History 并点击行内的 Edit。
2. 进行最小、明确的改动（例如某奖品补货）。
3. 走到 Confirm & Update，在 Save changes? 弹窗中确认。
4. 立即在会员端复核改动效果。

8.3 活动收尾

1. 让事件自然到期，或在上游中止发放。
2. 在 Lucky Draw History 中行 Status 变为 Ended，Edit 被隐藏。
3. 打开 View（dashboard）抓取最终指标用于财务 / 合规。
4. 若希望会员在活动结束后仍可查看规则或历史，请在 Basic Settings 中开启 Show Lottery Entry After End。

---

9. 故障排查

会员侧

现象	排查方向
页面空白 / 一直转圈	点击会员端外壳右上的 Refresh（环形箭头图标）重载小程序。若仍空白，检查网络并从 Mini programmes 重新打开 Lucky Draw。
看到过期事件或旧倒计时	点击 Refresh 在 viewer 内重载小程序。
出现 No Lucky Draw Event	没有配置事件，或事件不在生效窗口内。
出现 Coming Soon	事件已排期但未开始。
SPIN 按钮 disabled	事件未启动、No spins left 或会话缺失 —— 点击 Refresh 或从会员端重新打开 Lucky Draw。
Prize delivery failed 弹窗	奖励后端异常 —— 本次抽奖未被消耗，可再试或联系客服。
没看到中奖	先打开 My Rewards（礼盒图标）。代币也会出现在 Home -> Balance 与 Transaction History。

运营侧

现象	排查方向
不能点 + Create Lucky Draw	已存在 Not Launched 事件，先启动或删除。
Step 2 的 Next 按钮 disabled	至少需要一个 active 奖品，且 Total probability 必须等于 100%。
券卡在 Has per-user claim limit	该券在 VIO 券设置里配置了每人领取上限；为活动新建一张券（或将其设为不限每人领取）。
Event time overlaps with existing event	在 Basic Settings 调整 Start / End 时间，或结束冲突事件。
入账已记但奖励未发	检查仪表盘 Prize Claim Status、租户代币余额，以及 VIO External API 的 key / 配置。

---

10. 业务规则与说明

主题	说明
会话	会员应从会员端打开 Lucky Draw，以便 VIO 会话正确传入小程序。
库存模型	奖品库存等于原始库存减去已领数量、再加上补货量。Auto-restock 在为该奖品配置的最大补货上限范围内持续补货。
概率	active 奖品的概率必须严格合计 100% (±0.1%)。概率在 on-wheel 奖品之间独立计算；归档（Off wheel）奖品永远不参与抽奖。
参与规则	Per Day 使用平台的自然日边界。Entire Event 按整个活动期间累计。
奖励发放	奖励通过 VIO External API 发出。若回报 VIO_SEND_FAILED，会员本次抽奖不计入，可重试。
编辑	进行中事件一旦在 Update Lucky Draw 确认，改动立即对会员生效。
合规	活动期与参与规则必须清晰告知会员。请把规则放入活动文案，同时依赖抽奖页自动生成的 Terms & Conditions。

---

另请参阅 小程序总览、收据上传小程序、营销页小程序、注册奖励小程序、会员端 - 首页。