批量凭证

批量凭证让你通过上传 CSV 文件，一次性为数百或数千名接收者发放徽章。流程分为四步，内置进度跟踪、暂停/恢复以及错误处理。

概览

批量凭证流程分为四步：

1. 配置 — 选择徽章和选项
2. 上传 — 准备并上传你的 CSV 文件
3. 处理 — 在凭证创建过程中监控进度
4. 结果 — 查看结果并下载报告

第 1 步：配置

1. 从侧边栏打开 批量凭证 页面（它是独立的路由，与凭证页面分开）。
2. 使用徽章选择器选择你要颁发的徽章。
3. 可选配置：
   • 颁发日期 — 用于所有凭证的日期（默认为今天）
   • 过期时间 — 所有凭证的可选过期日期
   • 发送邮件 — 是否在每位接收者的凭证创建后自动向其发送邮件
4. 点击 下一步。

第 2 步：上传 CSV

CSV 格式

CSV 文件必须包含 name 列和 email 列，并带有标题行。标题名称不区分大小写，recipient_name / recipient_email 可作为 name / email 的别名使用。

name,email
Jane Smith,jane@example.com
John Doe,john@example.com
Maria Garcia,maria@example.com

下载模板

点击 下载模板 获取带有正确标题的空白 CSV 文件。填入你的接收者信息后上传即可。

上传

1. 点击 上传 CSV，或将文件拖放到页面中。
2. 文件会在开始处理之前进行验证。

验证规则

文件一经解析，每一行就会立即被验证：

• 姓名 至少需要 5 个字符
• 邮箱 必须是有效的电子邮件地址
• 空行会被跳过

预览表会列出每一行，并以绿色对勾或红色原因标注。无效行不会阻碍你继续 — 它们只会被 跳过，计数器会显示将处理多少个有效接收者（例如“18 个有效接收者，2 个无效（将被跳过）”）。只要至少有一行有效就可以继续，无需先修正并重新上传。

3. 点击 下一步 开始处理。

第 3 步：处理

处理开始后，你会看到进度条和实时计数器：

• 进度条 — 已处理行数的百分比
• 已创建 — 已创建的凭证数量
• 失败 — 失败的行数
• 剩余 — 仍在队列中的行数

批次运行时，进度条下方会实时填充 已创建、失败 和 待处理 表格。

暂停与恢复

• 点击 暂停 可临时停止处理。暂停期间不会创建新的凭证。
• 点击 恢复 可从中断处继续。

取消

• 点击 取消 可完全停止处理。已创建的凭证会保留。

错误处理

当某一行因其自身原因失败时（例如后端拒绝的无效值）：

• 错误会记录到该行
• 处理会自动继续下一行
• 失败的行会汇总到结果步骤，其错误文本显示在屏幕上的失败表格中

受到速率限制的行会在短暂退避后自动重试。额度或配额错误则不同 — 批次不会继续向下处理，而是 暂停，以免耗尽文件中的其余部分。屏幕上会出现红色的“额度不足”提示；请充值或升级套餐，然后点击 恢复 从中断处继续。

页面刷新恢复

如果你在处理期间不小心关闭了浏览器或刷新了页面，返回时批量凭证会话会被恢复。进度将从中断处继续。

第 4 步：结果

处理完成（或被取消）后，结果界面会显示四张汇总卡片：

• 总计 — 批次中的接收者数量
• 已创建 — 已创建的凭证数量
• 失败 — 失败的行数
• 已跳过 — 未处理的接收者（例如取消后剩余的行）

卡片下方，已创建 表格列出每个新凭证并附带查看链接，失败 表格则列出失败项及其错误文本。

下载报告

• 下载结果 CSV — 批次中的每一行，包含列 row, name, email, status, award_url（已创建的行会填入凭证 URL）。
• 下载失败项 CSV — 仅包含失败的行，列为 name, email, error。

重试失败项

如果有些行失败，点击 重试失败项。这会仅对失败的接收者重新处理一遍 — 无需重新上传 CSV。在修复临时问题（例如批次暂停后充值额度）之后，这个功能非常方便。