批量颁发

批量颁发让你通过上传 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 valid recipients, 2 invalid (will be skipped)")。只要至少有一行有效,你就可以继续;无需先修正并重新上传。

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

第 3 步:处理

处理一旦开始,你会看到进度条和实时计数:

• 进度条 — 已处理行数的百分比
• Created — 已创建的颁发数量
• Failed — 失败的行数
• Remaining — 仍在排队的行数

进度条下方会实时填充 Created、Failed 和 Pending 表格,随批处理运行而更新。

暂停与恢复

• 点击 暂停 临时停止处理。暂停期间不会创建新的颁发。
• 点击 恢复 从上次中断处继续。

取消

• 点击 取消 完全停止处理。已创建的颁发保持不变。

错误处理

当某一行因行本身的原因失败(例如后端拒绝的无效值):

• 该错误会记录到对应行
• 处理自动继续到下一行
• 失败的行将被收集用于结果步骤,其错误文本会显示在屏幕上的失败表格中

被限流的行会自动以短暂退避重试。积分或配额错误则不同 — 批处理不会跳过继续,而是 暂停,以免你耗尽文件的其余部分。此时会出现红色 "Insufficient credits" 提示;充值或升级后,点击 恢复 从停止处继续。

页面刷新恢复

如果你不慎关闭浏览器或在处理过程中刷新页面,回到页面时批量颁发会话会被恢复。进度从中断处继续。

第 4 步:结果

处理完成(或取消)后,结果屏显示四张汇总卡片:

• Total — 批次中的接收者数量
• Created — 创建的颁发数量
• Failed — 失败的行数
• Skipped — 未处理的接收者(例如取消后剩余的行)

卡片下方,Created 表格列出每条新颁发并附有查看链接,Failed 表格列出失败项及其错误文本。

下载报告

• Download Results CSV — 批次中的每一行,列为 row, name, email, status, award_url(已创建的行会填入 award URL)。
• Download Failures CSV — 仅失败的行,列为 name, email, error。

重试失败

如果有行失败,点击 Retry Failures。这会仅针对失败的接收者重新处理一遍 — 无需重新上传 CSV。在修复了暂时性问题(例如暂停批处理后充值积分)之后,这尤其方便。