重构学员证书签发与批量导入流程

backend/docs/learner-certificate-domain.md

@@ -0,0 +1,62 @@
+# 学员与证书业务模型
+
+## 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 参数、事务提交和操作日志，不应再次复制签发规则。