每日签到
每日签到小程序是一种奖励互动工具，允许会员每天签到一次并获得代币或礼券奖励。奖励按 7 天周期循环发放，其中第 7 天会提供“超级奖励”，鼓励持续参与。
访问方式
该小程序可从 VIO 会员端内部访问。用户必须先登录自己的 VIO 账号。管理员则通过专用的运营后台管理奖励和系统设置。
1. 如何进入
会员（PWA）
- 打开 VIO 会员端
- 进入小程序区域
- 点击 Daily Check-In 进入签到流程
- 应用会自动复用你的 VIO 会话完成鉴权，不需要额外登录
TIP
如果会话令牌缺失或已过期，会出现鉴权警告弹窗。你仍可以点击 “Continue Anyway” 继续进入，但签到功能可能会受到限制。
管理员（运营后台）
- 打开管理后台并登录。
- 在 Dashboard 或 Mini Apps 区域，打开 check in。
- 签到管理界面在管理后台内部打开。
说明： Ops 后台访问权限由租户管理员在管理后台中配置。Ops 后台还要求该租户已配置 VIO External API Key —— 否则奖励无法发放给会员。保存 key 的方式参见第 3 节与注册奖励 - VIO External API Key。
2. 会员体验 - 每日签到
2.1 页面状态
签到页面会根据租户配置显示三种状态：
状态 A：Coming Soon
当租户尚未配置签到功能时，会员会看到：
- 带火箭图标的标题 "Coming Soon"
- 提示文案："Daily check-in rewards are being prepared. Stay tuned!"
状态 B：Check-in Unavailable
当管理员已经配置过签到功能，但当前将其关闭时，会员会看到：
- 带禁止图标的标题 "Check-in Unavailable"
- 提示文案："Daily check-in is not currently available. Please check back later."
状态 C：Active Check-In（正常可用）
当签到功能已启用且配置完整时，会显示完整的签到界面。
2.2 欢迎语与页头
在签到页顶部，会员会看到：
- 欢迎文案："Welcome back, {username}"，其中
{username}来自会员在 VIO 资料中的显示名称
2.3 七日进度卡片
页面的主视觉是一张展示 7 天奖励周期的进度卡片：
- 布局：带有礼盒插图和背景装饰图的卡片
- 状态行：显示 "Check-In now"（如果今天尚未签到）或 "Check-In completed"（如果今天已完成签到）
- 进度格：分两行显示 Day 01 到 Day 07
- 第 1 行：Day 01、Day 02、Day 03、Day 04
- 第 2 行：Day 05、Day 06、Day 07
每日状态
每一天的格子会显示以下三种视觉状态之一：
| 状态 | 外观 | 含义 |
|---|---|---|
| Completed | 已领取样式的礼盒 | 这一天的奖励已经获得 |
| Current | 带动画灯光高亮的礼盒 | 今天可签到 |
| Future | 灰化/弱化样式的礼盒 | 尚未到达的后续天数 |
Day 07 - Super Reward
Day 07 使用特殊的加大版布局：
- 更大的礼盒插图（独立设计）
- 在日期数字下方显示 "Super reward"
- 在网格中横跨两列，起到更强视觉强调
TIP
完成 Day 07 后，周期会重置回 Day 01。签到 streak 会持续存在，并按 7 天循环无限滚动。
2.4 签到按钮
在进度格下方，会有一个显著的签到按钮来控制签到动作：
| 按钮状态 | 文案 | 行为 |
|---|---|---|
| Ready | "Check In" | 可点击，执行当天签到 |
| Loading | "Check In"（带加载指示） | 正在处理 |
| Completed | "Checked in"（禁用） | 今天已经完成签到 |
签到成功后，按钮下方会出现一条提示信息：
"Great job! Come back tomorrow for more rewards."
2.5 成功弹窗
点击 "Check In" 后，页面会弹出一个结果弹窗。共有两种变体：
变体 A：奖励发放成功
- 标题："Congratulations!"（以带放射光效的装饰图片呈现）
- 奖励展示：
- 对于 Token 奖励：显示两个叠放的代币圆形图，包含代币图标、代币名称（含 symbol）和获得数量
- 对于 Voucher 奖励：显示礼券卡片，包含礼券图片、名称和有效期（例如 "Valid until May 15, 2026"）
- 提示文案："Hooray! You earned {reward name}!"
- 按钮："Awesome!" - 关闭弹窗
变体 B：奖励未成功发放
如果签到记录已经写入，但奖励未能发出：
- 标题："Reward not sent"（纯文本，无庆祝动画）
- 提示文案：优先显示服务端返回的说明；否则显示默认文案："Your visit was recorded, but this reward could not be sent. Please try again tomorrow, or contact support if the problem continues."
- 按钮："Got it" - 关闭弹窗
WARNING
即使奖励发放失败，签到本身仍然会被记录。管理员可以在运营后台重新发送该奖励。
2.6 规则区块
如果管理员配置了签到规则内容，在进度卡下方会显示规则卡片：
- 标题："Rules"（带剪贴板图标）
- 内容：管理员配置的富文本（HTML）或纯文本，通常用于说明周期规则、断签后如何处理，以及奖励条件
3. 运营后台 - Dashboard
Dashboard 是运营后台的落地首页，用于总览签到活动数据。
如何进入：
- 打开运营后台 URL
- Dashboard 会作为默认页 (
/) 加载 - 右上角有一个 "Settings" 按钮，可跳转到设置页
3.1 页面头部
- 标题："Dashboard"
- 副标题："Daily Check-in performance overview - {today's date}"
- 操作按钮："Settings"（跳转到
/settings）
3.2 KPI 卡片
页面会展示一个核心指标卡片：
| 指标 | 说明 |
|---|---|
| Today's Check-ins | 当天的签到次数，副标题会显示总注册用户数（例如 "12 total users"） |
3.3 签到记录表格
一个带分页的表格，展示所有签到记录：
| 列 | 说明 |
|---|---|
| User | 会员显示名（或截断后的用户 ID） |
| Date | 本次签到的日历日期 |
| Day | 当前奖励周期中的第几天（例如 "Day 3"） |
| Reward | Badge 显示 "Token" 或 "Voucher"，下方显示奖励名称/数量 |
| Status | Badge： "Sent"（绿色）、"Pending"（黄色）或 "Failed"（红色），失败时附带错误细节 |
| Time | 完整签到时间戳 |
| Actions | （仅管理员）对于失败或待发送奖励显示 "Resend" 按钮 |
分页
- 显示 "Page X of Y"，并带有 "Previous" 和 "Next" 按钮
- 默认每页 10 条记录
- 表头有一个 "Refresh" 按钮，可重新加载当前数据
3.4 重发失败奖励
对管理员来说，当某条奖励状态为 "Failed" 或 "Pending" 时：
如何使用：
- 在表格中找到状态为 "Failed" 或 "Pending" 的记录
- 点击 Actions 列中的 "Resend" 按钮
- 按钮在处理中会变成 "Sending..."
- 成功时显示绿色提示："Reward sent successfully."
- 失败时显示红色提示并附带错误信息
INFO
"Resend" 按钮仅对拥有管理员角色的运营人员显示。普通操作员可能看不到这一列。
4. 运营后台 - Settings
Settings 页面允许管理员配置签到奖励及系统行为。
如何进入：
- 在 Dashboard 右上角点击 "Settings"
- 或直接访问
/settings - 顶部有返回箭头 "← Dashboard"，可回到 Dashboard
4.1 标签页导航
Settings 页面包含两个标签页：
| Tab | 标签 | 用途 |
|---|---|---|
| 1 | Reward Configuration | 配置 7 天中每天的奖励 |
| 2 | System Management | 控制签到开关并配置规则 |
4.2 Reward Configuration 标签页
这个标签页会展示一个 7 天奖励网格，每一天都必须配置一个 Token 或 Voucher 奖励。
说明文案
"Assign a token or voucher for each streak day. Use the buttons to open the picker - all seven days must be filled before you can save to the server."
配置每日奖励
如何使用：
- 对于每一天（Day 1-7），选择奖励类型：
- 点击 "Token" 打开 Token 选择弹窗
- 点击 "Voucher" 打开 Voucher 选择弹窗
- 在 Token 弹窗 中：从当前租户可用的代币里选择一个，并设置奖励数量
- 在 Voucher 弹窗 中：从当前租户可用的礼券/活动中选择一个
- 选择完成后，当天卡片会显示奖励图标、名称和详细信息预览
- 如需修改或移除奖励，可在当天卡片中使用 "Clear" 选项
保存奖励
- 所有 7 天都必须配置奖励后才能保存
- 点击 "Save Rewards"，将配置持久化到服务端
- 如果保存失败（例如网络异常），当前工作会自动以 本地草稿 的形式保存在浏览器中
本地草稿机制
当服务端保存失败时，页面顶部会出现提示：
"Local draft saved at {timestamp} (not on server)."
可用操作：
- "Restore draft" - 将之前保存的草稿重新载入编辑器
- "Discard draft" - 删除本地草稿
4.3 System Management 标签页
这个标签页用于控制签到功能的运行设置。
Enable Check-in 开关
| 设置 | 说明 |
|---|---|
| Enable Check-in | 总开关 - "Allow users to perform daily check-ins" |
如何使用：
- 切换开关以启用或禁用签到
- 系统会弹出确认框：
- 启用时："If you continue and save system settings, daily check-in is turned on for your tenant. Users will be able to open and use check-in again, subject to your reward configuration."
- 禁用时："If you continue and save system settings, daily check-in is turned off for your tenant immediately after that save. Users will no longer be able to access the check-in experience until you enable it again and save."
- 点击 "Enable" 或 "Disable" 确认，或点击 "Cancel" 取消
- 别忘了点击 "Save System Settings" 才会真正保存变更
WARNING
切换开关后不会立即生效，必须显式保存后才会作用到线上系统。只切换不保存不会对实际环境产生影响。
Calendar Boundary
开关下方会显示一条提示：
"Check-in days use midnight Asia/Shanghai as the calendar boundary."
这表示新的“签到日”以 Asia/Shanghai（UTC+8）的 00:00 为边界，不受用户本地时区影响。
Rules & Content Editor
这是一个富文本编辑器（TipTap），用于配置展示给会员的规则内容：
- 标签："Check-in Rules"
- 格式：支持粗体、斜体、列表等富文本格式
- 字符限制：最多 2,000 个字符（会显示计数器）
- 默认内容：如果没有设置自定义规则，会提供一份预写好的英文模板
如何使用：
- 使用富文本工具栏编辑规则内容
- 内容支持标题、加粗、斜体、无序列表、有序列表等格式
- 留意字符数，确保不超过 2,000 字限制
- 完成后点击 "Save System Settings"
TIP
这段规则内容会显示在会员签到页的 "Rules" 区块中，并按配置保留格式。
保存按钮
- "Save System Settings" - 当没有检测到改动或字符超限时会禁用
- 保存过程中显示 "Saving..."
- 通过 toast 提示保存成功或错误信息
4.4 VIO External API Key Gate
首次访问运营后台（或尚未配置 API Key）时，会先出现一个引导页，要求管理员设置 VIO External API Key。
如何使用：
- 从 VIO 管理后台获取当前租户的 API Key（位于 API Keys 区块）
- 在页面提供的输入框中填写该 API Key
- 提交后进入 Dashboard
WARNING
该 API Key 用于系统通过 VIO External API 向会员发送代币或礼券奖励。没有它时，签到仍会被记录，但奖励发放会失败。
5. 业务规则与说明
签到周期
- 奖励周期为 7 天，无限循环（Day 8 对应 Day 1，Day 14 对应 Day 7，以此类推）
- 每一天的奖励由管理员独立配置
- 当前所处周期天数由会员的 连续签到 streak 数 决定
时区
- 所有“天”的边界都基于 Asia/Shanghai（CST, UTC+8）
- 每一天从 00:00 开始，到 23:59:59 结束
- 会员在一个自然日（按 CST）内只能签到一次
奖励发放
- 签到成功后，系统会通过 VIO External API 自动发送奖励
- 如果发放失败，签到记录仍会保留，状态标记为 "Failed"
- 管理员可在 Dashboard 中使用 "Resend" 按钮重试发放
- 支持的奖励类型：Token（基于 ERC-20）与 Voucher（活动礼券）
访问控制
| 角色 | PWA（会员侧） | 运营后台 |
|---|---|---|
| 普通会员 | 可查看并执行签到 | 无权限 |
| 租户管理员 | 可查看并执行签到 | 完整权限（Dashboard、Settings、Resend） |