63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# 学员与证书业务模型
|
||
|
||
## 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 参数、事务提交和操作日志，不应再次复制签发规则。
|