新增PDF批量预生成

docs/usage-deployment-manual.md

@@ -41,9 +41,10 @@ reset-local-data.bat
 1. 登录 `/admin/login`。
 2. 进入“项目管理”，维护 `DBY`、`QSX` 等项目代码。项目支持搜索、修改、启用和停用。
 3. 进入“学员管理”，手动新增、查询、修改或删除学员。
-4. 进入“证书管理”，手动新增证书，支持单张预览、PDF 下载、作废、重置直达链接和导出。
+4. 进入“证书管理”，手动新增证书，支持单张预览、PDF 下载、作废、重置直达链接、按条件筛选、勾选后批量预生成 PDF 和导出。
 5. 进入“Excel 导入”，下载模板、上传 Excel、查看校验结果，确认后正式导入。模板只需要填写姓名、手机号、项目代码、发证日期；证书名称、课程名称、阶段名称、发证单位从项目配置自动带出。
    “确认导入”表示把已校验通过的临时数据正式写入学员和证书表。导入记录支持下载原文件、下载错误报告和删除；删除导入记录只删除上传文件、错误报告和批次记录，不删除已经生成的学员和证书。
+   确认导入后，可以在该批次行点击“预生成PDF”，系统会提前为这一批有效证书生成 PDF，并在弹窗里显示总数、已完成、新生成、已缓存、跳过和失败数量。
 6. 进入“系统设置”，确认 `PDF 生成并发限制`。2 核 4G 服务器建议保持默认值 `2`。
 7. 进入“操作日志”，查看关键后台操作。日志动作已转成中文显示。
 
@@ -65,6 +66,13 @@ PDF 由服务端按需生成，并使用 30 天缓存。这样可以保证模板
 
 首次生成 PDF 会占用 CPU。后台“系统设置”里的 `PDF 生成并发限制` 默认是 `2`，用于防止多人同时首次下载 PDF 时把 2 核 4G 服务器打满。前端下载和预览时会显示“当前查询人数较多，请稍后。。。”，避免用户误以为页面卡死。
 
+如果一次性导入大量毕业学员，建议管理员先做批量预生成：
+
+1. 进入“Excel 导入”，找到已确认导入的批次，点击“预生成PDF”。
+2. 或进入“证书管理”，按导入批次、PDF 状态、项目或关键词筛选，勾选需要提前生成的人，再点击“预生成所选PDF”。
+3. 批量预生成会继续遵守 `PDF 生成并发限制`，不会绕过系统并发保护。
+4. 预生成任务只在当前后端进程内记录进度；如果服务重启，已生成的 PDF 缓存仍然保留，但任务进度弹窗不会恢复。
+
 ## 正式部署准备
 
 - Linux 服务器，建议 2 核 4G 起步。
@@ -134,6 +142,7 @@ docker compose exec backend pytest
 - 项目新增、搜索、修改、启用、停用。
 - 学员手动新增、查询、修改、删除。
 - 证书新增、查询、后台预览、后台下载、作废、重置直达链接。
+- 证书按导入批次筛选、按 PDF 状态筛选、批量预生成 PDF。
 - Excel 模板下载、上传校验、错误报告下载、确认导入。导入模板字段为姓名、手机号、项目代码、发证日期。
 - 导入批次原文件下载和导入批次删除。
 - 导入后自动生成证书编号、直达链接 token、二维码 token。