# 开发决策记录

本文档记录开发过程中由 Codex 先行拍板的实现决定。后续如果业务方有不同意见，可以按条目调整。

## 已确认决策

### D001 PDF 生成策略

- 决定：PDF 由服务端生成，不在用户浏览器生成。
- 策略：按需生成 + 30 天缓存。
- 原因：证书属于正式凭证，服务端生成更利于统一版式、审计、作废状态控制和后续模板替换。

### D002 证书编号格式

- 决定：`EPX{YYYY}-{项目代码}-{7位短码}-{2位校验码}`。
- 示例：`EPX2026-DBY-K7M9Q2R-83`。
- 说明：内部数据库继续使用 `BIGINT` 主键，对外编号使用短码和校验码，降低枚举和手输错误风险。

### D003 公开查询方式

- 决定：一期公开查询支持两种方式：证书编号 + 姓名 + 图形验证码，或手机号 + 姓名 + 图形验证码。
- 说明：手机号 + 姓名可能匹配多张证书，查询结果按列表展示。
- 风控：继续保留图形验证码和基础频率限制，降低批量撞库风险。

### D004 作废证书 PDF

- 决定：一期作废证书不允许下载正常 PDF。
- 展示：查询页、直达页、二维码核验页统一显示作废状态。

### D005 证书模板

- 决定：一期先使用占位模板。
- 要求：模板文件与业务逻辑分离，后续替换 Logo、公章、排版、正式文案时不改核心业务代码。

### D006 更正和补发

- 决定：一期不实现复杂更正/补发流程。
- 一期保留证书编辑、作废、重置链接等主链路操作。

## Codex 先行决定

### C001 项目代码维护方式

- 决定：后台提供项目/课程代码配置，导入 Excel 使用项目代码匹配，不允许随意生成编号中的项目代码。
- 原因：避免同一项目出现多个拼写，确保证书编号稳定。

### C002 一期部署方式

- 决定：单机 Docker Compose 部署。
- 组件：Nginx、前端静态资源、FastAPI 后端、MySQL。
- 原因：符合低并发和快速上线目标，减少运维复杂度。

### C003 文件目录

- 决定：使用 `/data/certificate-system/uploads`、`error-reports`、`exports`、`pdf-cache`。
- 原因：便于备份策略区分；PDF 缓存不进入长期备份。

### C004 初始化管理员

- 决定：通过初始化命令创建第一个系统管理员。
- 原因：避免在公开页面暴露注册入口。

### C005 访问 token 一期存储

- 决定：一期在 `certificate_access_tokens` 中同时保存 token 哈希和 token 原值。
- 原因：后台导出必须能生成证书对外直达链接；纯哈希无法反推出链接。
- 风险：数据库泄露时 token 原值可被直接使用。
- 后续优化：将 token 原值改为应用层加密存储，或仅在生成时写入导出文件并提供链接重置机制。

### C006 验证码和限流

- 决定：一期使用后端进程内存保存图形验证码和简单 IP 频率计数。
- 原因：一期单机部署，不引入 Redis，满足快速上线和低并发目标。
- 后续优化：访问量上来后迁移到 Redis，并把限流前移到 Nginx 或网关层。

### C007 后台 UI 风格

- 决定：后台采用浅色、清爽、偏办公工具的视觉风格。
- 原因：这个系统是日常管理工具，用户需要快速查找和处理数据，不适合厚重的深色或营销化页面。

### C008 后台 PDF 下载方式

- 决定：后台证书 PDF 下载使用带 Authorization token 的 blob 请求。
- 原因：受保护的后台接口不能依赖普通链接跳转，否则浏览器不会带前端保存的登录 token，容易导致下载失败。

### C009 Excel 导入字段

- 决定：导入模板只保留姓名、手机号、项目代码、发证日期。
- 原因：证书名称、课程名称、阶段名称、发证单位属于项目配置，不应该在每一行 Excel 里重复填写。
- 备注：导入备注字段一期移除；批量导入后的备注缺少明确展示和业务使用场景。

### C010 导入批次文件管理

- 决定：后台保留导入批次列表，并支持下载原始 Excel、下载错误报告、删除批次记录。
- 删除范围：只删除上传文件、错误报告和批次记录，不删除已经确认导入后生成的学员和证书。
- 原因：导入文件会占用服务器存储，但导入后的业务数据应作为正式数据继续保留。
### C011 Certificate Rendering Template

- Decision: keep `certificate-template-lab` as a standalone visual tuning page.
- 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.