新增PDF批量预生成

docs/decision-log.md

@@ -100,3 +100,10 @@
 - Decision: production PDF rendering now uses the approved certificate image as the base layer, then renders learner/course/date/certificate number dynamically with Pillow.
 - Current limitation: the data model only has `issue_date`; until separate training start/end dates are added, the rendered course date range uses `issue_date` for both start and end.
 - Current limitation: mentor, issuer names, and QR area remain from the approved base image for visual consistency.
+
+### C012 PDF 批量预生成
+
+- 决定：后台提供批量预生成 PDF 能力，可按导入批次生成，也可在证书管理中筛选和勾选后生成。
+- 策略：预生成继续使用系统设置里的 `PDF 生成并发限制`，不单独开无限制后台任务。
+- 原因：大批量学员毕业前先生成缓存，可以降低公开查询高峰的等待时间和 CPU 压力。
+- 当前限制：任务进度保存在后端进程内，服务重启后只保留已生成的 PDF 缓存，不恢复历史进度。

docs/deployment-checklist.md

@@ -39,6 +39,7 @@ docker compose exec backend python -m app.cli init-db --admin-username admin --a
 - 系统设置里的 `PDF 生成并发限制` 已确认，2 核 4G 建议保持默认 `2`。
 - Excel 导入模板已下载并试填。
 - 占位证书模板已确认可临时使用。
+- 大批量毕业前的操作约定已确认：确认导入后先在“Excel 导入”或“证书管理”里批量预生成 PDF。
 
 ## 验收动作
 
@@ -46,6 +47,8 @@ docker compose exec backend python -m app.cli init-db --admin-username admin --a
 - 可新增学员。
 - 可新增证书并生成编号。
 - 可上传 Excel 并确认导入。
+- 已导入批次可以启动“预生成PDF”，进度弹窗能显示总数、已完成、失败数和并发数。
+- 证书管理页可按导入批次和 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。

docs/正式部署操作手册.md

@@ -516,6 +516,7 @@ https://你的域名/admin/login
 - 证书编号自动生成。
 - 能预览证书。
 - 能下载 PDF。
+- 能按导入批次或 PDF 状态筛选证书，并勾选多张证书批量预生成 PDF。
 - PDF 底图、姓名、日期、课程、导师、二维码清晰。
 - 作废证书后不能下载正常 PDF。
 - 重置链接后旧链接失效。
@@ -538,6 +539,7 @@ https://你的域名/admin/login
 - 错误数据能生成错误报告。
 - 校验通过后能确认导入。
 - 确认导入后能生成学员和证书。
+- 已导入批次能点击“预生成PDF”，进度弹窗显示总数、已完成和失败数。
 - 能下载导入原文件。
 
 ### 9.6 公开查询

docs/阿里云正式部署详细操作手册.md

@@ -513,6 +513,7 @@ https://你的域名/admin/login
 - 证书名称使用项目名称。
 - 能预览证书。
 - 能下载 PDF。
+- 能按导入批次或 PDF 状态筛选证书，并勾选多张证书批量预生成 PDF。
 - 证书日期、课程标题、导师、二维码显示正常。
 - 能作废证书。
 - 作废证书不能下载正常 PDF。
@@ -536,6 +537,7 @@ https://你的域名/admin/login
 - 能确认导入。
 - 确认导入后状态变成已导入。
 - 不能重复确认导入。
+- 已导入批次能点击“预生成PDF”，进度弹窗显示总数、已完成和失败数。
 
 ### 13.6 公开查询