收据上传小程序 - 用户指南

Claim 小程序用于会员上传收据并领取奖励，运营人员通过 Claim Ops 后台审核提交并配置规则。

说明： 小程序嵌入在 VIO 会员端内部打开，会员必须先登录。运营人员从管理后台进入 Ops 后台，并需先为该租户配置 VIO External API Key（参见注册奖励 - VIO External API Key）。

---

目录

1. 如何进入
2. 会员端界面概览
3. 会员体验 - Upload Receipts
4. 会员体验 - Confirm、Summary 与 Result
5. 会员体验 - Claim History
6. Ops 后台 - Submissions
7. Ops 后台 - Users
8. Ops 后台 - Rules Configuration
9. 运营工作流
10. 故障排查
11. 业务规则与说明

---

1. 如何进入

会员 —— 登录 VIO 会员端，进入 Mini programme -> See all，点击 Claim 格子。小程序在会员端外壳内加载，默认进入 Upload Receipts。

运营 —— 登录管理后台，在 Mini Apps 中打开 Claim。Ops 后台带 Submissions / Users 两个 Tab，以及 Edit Rules Configuration 按钮。

提示： 如果页面被弹回登录或显示 Authentication Required，请从 Mini programme 重新打开 Claim —— 会员端通过 URL 中的 refresh token 传递 VIO 会话。

---

2. 会员端界面概览

会员端外壳为每个 Claim 页面提供 Back（←）、页面 Title 以及右上的 Refresh（环形箭头图标）。Refresh 会重载小程序并重发最新会话 token。

Upload Receipts 上还会看到：

• claim history 链接（右上） —— 打开 /history 的 Claim History。
• Take a photo —— 唤起相机。支持 JPG、PNG、HEIC（HEIC 自动转换）。
• Upload images —— 唤起文件选择器。同样的格式，张数上限为活动的 Max N receipts per submission。
• Submission Criteria 卡片 —— 由活动规则自动生成（每类张数上限、最低消费、整体上限）。

提示： Refresh 保留本地草稿但会重新拉取活动规则；Back 直接离开 Claim。

---

3. 会员体验 - Upload Receipts

3.1 页面状态

状态	出现时机	上传按钮
Campaign Not Active	Ops 规则未配置完成或保存校验失败（banner 列出缺失项）。	禁用
Campaign is not currently active	在活动期之外，且不在任何 Receipt Date Buffer 窗口内。	禁用
可上传	在正式活动期内。	可用
Within Receipt Date Buffer	在正式活动期之外、但仍在配置的 buffer 窗口内。会显示横幅，如 Campaign starts on {date}. You can submit receipts now. 或 Campaign has ended. Submit receipts by {endWithBuffer date}.	可用

3.2 如何上传

使用方法：

1. 在 Upload Receipts 点击 Take a photo 或 Upload images。
2. 等待处理提示（Uploading...、Converting HEIC image... 或 Compressing image...）。
3. 每张收据后台执行 OCR。当进行中列表显示 completed 后，Submission Criteria 卡片刷新，可核对类别、张数与合计。
4. 点击缩略图复核或删除某张收据。重复第 1 步追加，直至到达 Max N receipts per submission。
5. 全部就绪后，页面会跳到 Confirm receipt。

警告： 一次提交内的所有收据必须属于同一商户类别。混类时会出现 This receipt is from a {category} store. You can only add receipts from {locked} stores in this submission.

说明： 超过每类或总数上限时弹出 Upload Error（You can only upload up to N… 或 Only N more receipt(s) can be added.）。

3.3 Submission Criteria

卡片列出当前规则：每类张数上限、最低消费（RM）、整体 Max N receipts per submission（默认 3）。类别名称、上限与门槛因租户而异，请以页面上的卡片为准。

提示： 即使卡片里出现多个类别，一次提交内的收据也必须属于同一类别。

---

4. 会员体验 - Confirm、Summary 与 Result

4.1 Confirm receipt（/confirm）

每张收据以 Receipt N of M 显示，带商户、类别与金额。

• 点击缩略图打开 Receipt N 缩放弹窗（− / + / Close）。
• Add another receipt (N receipt(s) left) 继续追加；到达上限后显示 No receipts left to add。
• 行内删除图标打开 Delete Receipt（Cancel / Delete）。
• Continue 继续。

说明： 类别合计低于最低消费时，页面显示 Your total amount does not meet the minimum requirement of RM … for {category} stores. 与 You can add up to … more receipt(s).。

4.2 Summary（/summary）

提交前最后一步。每张收据需填写：

• Merchant（打开 Merchant 抽屉，搜索 placeholder 为 Search brand）
• Receipt date
• Receipt amount（前缀 RM）

只有当每张收据都有合格的 Merchant、Receipt date 与 Amount > 0 时，Submit 才会启用，提交期间显示 Submitting...。会话失效时页面提示 User not authenticated. Please log in again.

4.3 Submission Result（/result）

提交成功后页面显示 You have submitted the claim request. The approval takes within 3 days.、Receipt summary 卡片，以及返回 Upload Receipts 的 Done 按钮（本地草稿被清除）。

---

5. 会员体验 - Claim History

在 Upload Receipts 点击 claim history 打开 /history。列表按最新优先排序，每张卡片包含日期、Merchant、Amount、Reward（发奖后才显示）与状态徽章。

会员侧的状态徽章

徽章	含义
Pending	等待审核。
Processing	后端或奖励发放处理中。
Approved	已通过（覆盖后端 approved 与 processed）。
Rejected	运营已驳回。
Failed	提交未能成功处理。
Reward Failed	已通过审核但奖励发放失败。
Partial	部分奖励已发、部分失败（partial_failed）。

空状态：No submissions yet，附 Submit a Receipt 按钮。

---

6. Ops 后台 - Submissions

6.1 页面结构

Ops 后台默认进入 Submissions（/submissions）。页面提供 Status filter 下拉（All Status、Pending、Processing、Processed、Approved、Rejected、Failed、Partial Failed、Reward Failed）、搜索框（占位 Search by user ID or username），以及分页表格。

Submissions 表的列： Date & Time、Username、User ID、Receipts（N receipt(s)）、Status、Total Amount（RM）、Reward Obtained、Actions（人工队列显示 Verify claim，其他显示 View details）。

空状态：No Submissions Found / Try adjusting your filters or search criteria。

6.2 提交详情抽屉

点击 View details 或 Verify claim 打开 Submission Details。抽屉包含：

• Submission Info —— SUBMISSION ID、USER ID、USERNAME、DATE、STATUS、TOTAL AMOUNT；如有则包含 AMOUNT EDITED BY/AT、REVIEWED BY、REVIEWED AT、REJECT REASON。
• Receipts (N) —— 每张卡片显示可编辑的 Receipt amount、Receipt Date:、Store:、Store Name:，以及可展开的 OCR Text。在审批前用 Save Amounts 保存修改。点击缩略图打开灯箱（+ / −、Reset、Escape）。
• Rewards —— 状态药丸（Success、Partial、Failed、Pending approval）与奖励明细表（Reward type、Voucher name、NFT ID、Status、Error reason、Sent at）。
• System Error —— 当后端报错时显示原始 error 文本。
• 底部操作 —— Approve & send rewards、Reject；部分奖励失败时还会出现 Resend failed rewards。

每个动作都会先弹出确认弹窗（Approve Submission、需填理由的 Reject Submission、Resend Rewards）。

警告： Ops 前端没有批量 Export / CSV 功能 —— 报表导出仍需通过 API 或后端数据库。

6.3 使用方法

使用方法：

1. 打开 Submissions，按 Pending 过滤进入人工队列。
2. 点击 Verify claim（或 View details）打开抽屉。
3. 复核每张收据的 Store、Receipt Date 与 Receipt amount；必要时展开 OCR Text。
4. 调整明显有误的金额并 Save Amounts。
5. Approve & send rewards 或带书面理由的 Reject。
6. 当 Rewards 显示 Failed / Partial 时，先解决根因（代币余额、券剩余量、External API key），再 Resend failed rewards。

---

7. Ops 后台 - Users

Users Tab 提供会员维度的活动视图：

• Users Overview 计数：Total Users:、Total Submissions:、Total Rewards Sent:。
• 搜索框，占位为 Search by user ID, username or email。
• Users table 列：Username、User ID、Email、Submissions、Rewards、Last Active、Actions（View details）。
• User ID 在表里只显示前 5 个字符的预览（例如 abcde…）。点击旁边的复制图标（悬停文案 Copy full user ID）复制完整 ID —— 顶部会浮出 User ID copied to clipboard，图标变为 ✓。如果浏览器禁用了剪贴板，会弹出 Copy failed，文案：Could not copy to the clipboard. Your browser may block copying on this URL; try HTTPS or copy the ID manually from the network tab or logs.

View details 打开 User Details 抽屉，包含 User Info 卡片与 Submission History (...) 表（Date、Amount、Reward type、Voucher name、Tokens、Status）。

空状态：No Users Yet（系统尚未同步）或 No Users Found（搜索无匹配）。

---

8. Ops 后台 - Rules Configuration

Edit Rules Configuration 在 /rules 打开规则向导（面包屑 Receipt Ops > Rules Configuration）。每个步骤都有自己的 Save Changes 与 toast（例如 Receipt quantity rules saved successfully!）。Configuration completeness {pct}% 跟踪进度并列出仍需处理的步骤。

向导步骤：

1. Receipt Scope —— 定义 Eligible Merchants 并按 Merchant Categories 分组（例如 NSK、OTHER）。识别到的商户不在列表中的收据会被后端拒绝，文案为 Store "{storeName}" is not in the eligible tenants list。
2. Quantity —— 设置 Overall Limit（Maximum Total Receipts per Claim，默认 3，会员侧显示为 Max N receipts per submission）与 Category Limits（每个类别一个 {Category} Max Receipts 字段，且必须 ≤ 整体上限）。内联提示：⚠️ Note: Users can only submit receipts from ONE category per claim. Each category limit must be ≤ overall limit.
3. Thresholds —— 每类 Minimum spend required，币种 RM。
4. Review Mode —— Automatic 自动审批；Manual 把提交送入第 6 节中的 Verify claim 队列。
5. Rewards —— 选 Vouchers（连接 VIO Voucher Pool，搜索 Select voucher from VIO...）或 Tokens（系统将收据合计除以配置的消费门槛，向下取整，再乘以配置的获奖量发放）。依赖租户已配置 VIO External API Key；找不到 key 时 Ops 后台会弹出 VIO External API Key 闸门弹窗（占位 Paste your vio_live_… key，按钮 Confirm）。
6. User Limits —— Maximum Claims per User。校验提示：Maximum claims per user must be at least 1. 达到上限时，会员看到 You have reached the maximum number of submissions allowed for this campaign.
7. Time Rules —— Campaign Period（Start Date / End Date）与 Receipt Date Buffer（活动窗口前后多少天内收据日期仍视为有效）。Receipt Date Range 预览显示最终可接受的日期区间。

底部导航：第一步显示 Cancel，后续显示 Back，步与步之间用 Next，最后一步显示 Done。

警告： 活动进行中修改 Time Rules 会立刻影响会员可提交的收据，保存前请先通知会员。

---

9. 运营工作流

9.1 启动新一轮 Claim 活动

1. 为该租户配置 VIO External API Key。
2. 按顺序走完 Rules Configuration 向导（Receipt Scope -> Quantity -> Thresholds -> Review Mode -> Rewards -> User Limits -> Time Rules），每一步保存。
3. 确认 Configuration completeness 达到 100%。
4. 用测试账号在会员端走一遍 Upload Receipts -> Confirm receipt -> Summary -> Submission Result。
5. 在 Submissions 中确认新提交以预期的 Status 出现。

9.2 日常人工审核（Manual 模式）

1. 按 Pending 过滤 Submissions，点击 Verify claim。
2. 检查收据图、OCR 文本与已解析的 Receipt amount；必要时调整并 Save Amounts。
3. Approve & send rewards 或带书面理由的 Reject。
4. 确认 Rewards 显示 Success；否则在排查原因后使用 Resend failed rewards。

9.3 处理奖励发放失败

1. 按 Reward Failed 或 Partial Failed 过滤 Submissions。
2. 复核 Rewards 表与 System Error，判断根因（代币余额、券剩余量、External API key、网络）。
3. 解决后点击 Resend failed rewards。
4. 确认行状态变为 Approved，所有奖励显示 Sent。

9.4 活动收尾

活动窗口结束后会员开始看到 Campaign is not currently active。清理遗留的 Pending / Processing，在 Submissions 与 Users 中抓取最终指标，并决定是否保留 VIO External API Key 与现有规则供下轮复用。

---

10. 故障排查

会员侧

现象	排查方向
页面空白 / 一直转圈	点击 Refresh；如仍空白，检查网络并从 Mini programme 重新打开 Claim。
Authentication Required 弹窗	请从会员端重新打开 Claim —— 不要把 URL 粘贴到浏览器中。
Campaign Not Active banner	Ops 规则未配置完成，请联系运营。
Campaign is not currently active banner	活动期与 Receipt Date Buffer 窗口均已结束。
Upload Error 弹窗	减少所选文件数量，或将类别调整为已锁定类别。
Confirm receipt / Summary 合计低于门槛	在同一类别中追加一张收据。
会员端看不到中奖	先打开 Claim History 查看状态。代币也会出现在 Home -> Balance 与 Transaction History；券出现在 Vouchers。

运营侧

现象	排查方向
Submissions 卡在 Loading...	确认已配置 VIO External API Key（闸门弹窗 VIO External API Key）。
没有 Verify claim 动作	Review Mode 为 Automatic —— 如需人工审核，切到 Manual。
Save Amounts 失败	每个编辑后的金额必须 > 0。
已通过的行变成 Reward Failed	打开行查看每行 Error reason，修复后再 Resend failed rewards。
运营看不到新提交	检查 Time Rules —— 日期不在 Campaign Period + Receipt Date Buffer 范围内的收据会被后端拒绝。
规则步骤拒绝保存	按内联提示（如 Maximum claims per user must be at least 1.）与 Configuration completeness banner 补齐。

---

11. 业务规则与说明

• 会话 —— 会员必须从会员端打开 Claim，让 refresh token 在 URL 中传入。直接浏览器访问会显示 Authentication Required。
• 单类别提交 —— 同一次提交的收据必须同类；混类会被拒绝。
• 总收据上限 —— Maximum Total Receipts per Claim（默认 3），会员侧显示为 Max N receipts per submission。
• 币种 —— 会员端金额均以 RM 显示。多币种租户需要额外集成层（不在本指南范围内）。
• OCR 与压缩 —— 大于 1 MB 的 PNG/JPEG 会在客户端压缩；HEIC 会先转换再上传。
• 审批文案 —— Submission Result 页硬编码 The approval takes within 3 days.，请据此对齐对外 SLA。
• 状态对应关系 —— 会员侧 Approved 覆盖后端 approved 与 processed；Ops Submissions 在过滤器中分别区分。
• 奖励发放 —— 奖励通过 VIO External API 发出。失败行仍保留在 Rewards 表中，可用 Resend failed rewards 重发。
• 合规 —— 通过 Submission Criteria 卡片清晰展示当前规则；除非必要，不要在活动中途修改 Time Rules、Quantity 或 Thresholds。

---

另请参阅 小程序总览、幸运抽奖小程序、营销页小程序、注册奖励小程序、会员端 - 首页。