Initial certificate system

docs/usage-deployment-manual.md

@@ -0,0 +1,146 @@
+# 部署与使用手册
+
+本文档用于一期本地验收和正式部署交接。
+
+## 本地验收版
+
+适合在没有 Docker、npm 环境时先完整跑通业务流程。
+
+```bat
+cd /d C:\Users\nelso\Documents\projects\certificate-system
+start-local.bat
+```
+
+访问地址：
+
+```text
+后台：http://127.0.0.1:8000/admin/login
+公开查询：http://127.0.0.1:8000/query
+```
+
+默认账号：
+
+```text
+admin / Admin123!
+```
+
+本地数据保存在：
+
+```text
+local_app/data/local.db
+```
+
+清空本地验收数据：
+
+```bat
+reset-local-data.bat
+```
+
+## 后台使用流程
+
+1. 登录 `/admin/login`。
+2. 进入“项目管理”，维护 `DBY`、`QSX` 等项目代码。项目支持搜索、修改、启用和停用。
+3. 进入“学员管理”，手动新增、查询、修改或删除学员。
+4. 进入“证书管理”，手动新增证书，支持单张预览、PDF 下载、作废、重置直达链接和导出。
+5. 进入“Excel 导入”，下载模板、上传 Excel、查看校验结果，确认后正式导入。模板只需要填写姓名、手机号、项目代码、发证日期；证书名称、课程名称、阶段名称、发证单位从项目配置自动带出。
+   “确认导入”表示把已校验通过的临时数据正式写入学员和证书表。导入记录支持下载原文件、下载错误报告和删除；删除导入记录只删除上传文件、错误报告和批次记录，不删除已经生成的学员和证书。
+6. 进入“操作日志”，查看关键后台操作。日志动作已转成中文显示。
+
+## 公开查询流程
+
+1. 用户进入 `/query`。
+2. 输入证书编号 + 姓名 + 图形验证码，或手机号 + 姓名 + 图形验证码。
+3. 查询成功后展示证书状态和证书信息；手机号查询可能返回多张证书。
+4. 有效证书可下载 PDF。
+5. 作废证书只展示作废状态，不提供正常 PDF 下载。
+
+## PDF 下载说明
+
+PDF 由服务端按需生成，并使用 30 天缓存。这样可以保证模板、二维码、作废状态和审计逻辑统一。
+
+后台 PDF 下载不能用简单的 `window.location` 直接跳转，因为后台接口需要登录态。如果直接打开下载地址，浏览器不会自动带上前端保存的 Authorization token，容易出现下载失败。当前后台已改为通过带 token 的请求下载 blob 文件，再在浏览器里保存。
+
+## 正式部署准备
+
+- Linux 服务器，建议 2 核 4G 起步。
+- 域名和 HTTPS 证书。
+- Docker 和 Docker Compose。
+- MySQL 8，可以使用 Compose 内置 MySQL 或云数据库。
+
+默认数据目录：
+
+```text
+/data/certificate-system
+```
+
+建议子目录：
+
+```text
+uploads
+error-reports
+exports
+pdf-cache
+```
+
+`pdf-cache` 是 30 天缓存，不需要作为长期档案备份。
+
+## 环境变量
+
+复制 `.env.example` 为 `.env`，至少修改：
+
+```text
+APP_ENV=production
+DATABASE_URL=mysql+pymysql://certificate:password@mysql:3306/certificate_system
+SECRET_KEY=change-me
+PUBLIC_BASE_URL=https://your-domain.com
+CERTIFICATE_NO_SECRET=change-me
+PDF_CACHE_DAYS=30
+DATA_ROOT=/data/certificate-system
+```
+
+## Docker 部署
+
+```bash
+docker compose up -d --build
+```
+
+首次初始化：
+
+```bash
+docker compose exec backend python -m app.cli init-db --admin-username admin --admin-password "请替换为强密码"
+```
+
+单独执行数据库迁移：
+
+```bash
+docker compose exec backend alembic upgrade head
+```
+
+后端测试：
+
+```bash
+docker compose exec backend pytest
+```
+
+## 当前已实现
+
+- 后台登录。
+- 后台概览统计。
+- 项目新增、搜索、修改、启用、停用。
+- 学员手动新增、查询、修改、删除。
+- 证书新增、查询、后台预览、后台下载、作废、重置直达链接。
+- Excel 模板下载、上传校验、错误报告下载、确认导入。导入模板字段为姓名、手机号、项目代码、发证日期。
+- 导入批次原文件下载和导入批次删除。
+- 导入后自动生成证书编号、直达链接 token、二维码 token。
+- 证书导出，包含证书编号和对外直达链接。
+- 公开查询：证书编号 + 姓名 + 图形验证码，或手机号 + 姓名 + 图形验证码。
+- 证书直达页和二维码核验页。
+- PDF 服务端按需生成，缓存 30 天。
+- 关键操作日志写入和中文展示。
+
+## 后续上线前确认
+
+- 生产域名、HTTPS 和 Nginx 限流参数。
+- PDF 正式模板、Logo、公章和证书文案。
+- 生产管理员账号和强密码。
+- 服务器部署后的联调和验收数据导入演练。