certificate-system/backend/docs/learner-certificate-domain.md

学员与证书业务模型

1. 核心关系

• 学员是长期主体，证书是某一次学习成果的签发记录。
• 一个学员可以拥有多张证书，证书可以来自不同项目、不同课程、不同模板和不同时间段。
• 证书签发后保存当次课程、阶段、日期和模板代码，不依赖项目默认值继续变化。
• 项目只负责归档和提供默认值，不能代替证书模板定义字段。

2. 学员身份规则

• 系统使用标准化后的手机号定位学员，姓名用于一致性校验和业务确认。
• 输入手机号会去除空格、短横线及中国大陆区号，最终保存为 11 位手机号。
• 手机号不存在时，手工签发和证书批量导入都会自动创建学员。
• 手机号已存在且姓名一致时，复用原学员。
• 手机号已存在但姓名不一致时，必须报冲突，不能自动改名或把证书挂到错误学员。
• 确需更名时，应在学员管理中人工修改，并保留姓名历史。

3. 模板字段规则

app/services/certificate_templates.py 是模板字段的唯一规则源。每个字段定义：

• key：后端和前端使用的稳定字段键。
• label：页面和 Excel 使用的中文名称。
• field_type：文本或日期。
• required：该模板签发证书时是否必填。
• example：Excel 填写示例。
• description：后台提示和 Excel 填写说明。

新增模板时，应先在这里声明字段。手工创建表单、Excel 表头、Excel 校验和后端签发校验都会读取同一份定义。

4. 导入流程

证书导入

1. 先选择证书模板。
2. 下载该模板专用 Excel，不能跨模板混用。
3. 上传后只做校验，不立即写入正式证书。
4. 管理员确认后调用统一签发服务。
5. 学员不存在时自动创建；重复证书跳过；身份冲突或字段错误进入失败记录。

证书导入的公共业务列是姓名、手机号和项目代码。其余列由所选证书模板决定。

学员导入

• 姓名和手机号必填，学员编号和备注选填。
• 只维护学员主数据，不创建证书。
• 已有学员姓名手机号一致时可补充学员编号和备注。
• 冲突行单独返回，不修改已有学员姓名。

5. 签发入口

手工创建和证书导入统一调用 app/services/certificate_issuance.py，由该服务负责：

• 校验项目和模板；
• 解析或创建学员；
• 校验模板字段和课程日期；
• 判断重复证书；
• 创建证书编号；
• 创建公开链接和二维码令牌。

路由层只处理权限、HTTP 参数、事务提交和操作日志，不应再次复制签发规则。