certificate-system/backend/docs/certificate-template-management.md

证书模板管理说明

当前模板

系统内置两套模板：

• classic：经典结业证书，动态填写姓名、课程名称、阶段名称、课程起止日期和发证日期。
• practice-camp：实修大本营结业证书，只动态填写姓名、课程开始日期、课程结束日期和发证日期。

模板定义集中在 app/services/certificate_templates.py，底图位于 app/assets/，文字坐标和绘制逻辑位于 app/services/pdf.py。

后台流程

1. 在“证书模板”查看可用模板和动态字段。
2. 在“项目管理”为项目配置默认模板。
3. 单张创建证书时，系统自动采用项目默认模板，管理员可以在提交前切换。
4. Excel 导入时先选择本批次模板，再上传文件；确认导入后整批证书固化为所选模板。
5. 证书创建后保存 template_code，以后修改项目默认模板不会改变历史证书。

增加新模板

1. 将清晰底图放入 app/assets/，不要在代码中引用工作区外部文件。
2. 在 certificate_templates.py 注册模板代码、名称、底图文件和动态字段。
3. 在 pdf.py 增加独立渲染函数，并由 render_certificate_image 按模板代码分发。
4. 使用真实姓名和日期生成 PDF，再通过 pdftoppm 渲染为 PNG 检查位置、清晰度和文字遮挡。
5. 在 tests/test_certificate_templates.py 增加模板资源和渲染测试。

模板代码一旦用于正式证书，不应重命名或复用；需要大幅改版时应注册新的模板代码，以保证历史证书可以稳定重现。