forked from wangziqi/gongxue-base
80 lines
3.1 KiB
Markdown
80 lines
3.1 KiB
Markdown
# 学生档案报告：后端渲染 → 前端预览
|
||
|
||
> 将档案报告从后端 Puppeteer 生成 PDF 改为后端生成 HTML、前端新窗口预览、浏览器打印出 PDF。
|
||
|
||
## 目标
|
||
|
||
- 去掉 Puppeteer 依赖（减小编译/运行时镜像体积）
|
||
- 报告预览即时可用，不再等待 PDF 生成
|
||
- PDF 导出由用户通过浏览器 Ctrl+P → 另存为 PDF 完成
|
||
- 改动最小化：复用现有 `buildHtml()` 等 HTML 构造方法
|
||
|
||
## 架构
|
||
|
||
```
|
||
前端: fetch /archive/:studentId/report-html
|
||
→ window.open → document.write(html)
|
||
→ 用户浏览/打印
|
||
|
||
后端: ArchiveReportService.generateReportHtml(studentId)
|
||
→ 查数据库组装 ReportData
|
||
→ 调用现有 buildHtml(data)
|
||
→ 返回 HTML 字符串
|
||
```
|
||
|
||
## 后端改动
|
||
|
||
### `apps/server/src/archive/archive-report.service.ts`
|
||
|
||
| 操作 | 详情 |
|
||
|------|------|
|
||
| 新增 | `generateReportHtml(studentId: number): Promise<string>` — 复用现有数据查询和 `buildHtml()`，返回纯 HTML 字符串 |
|
||
| 删除 | `generateReport(studentId: number, res: Response): Promise<void>` — Puppeteer PDF 流式输出 |
|
||
| 删除 | `import puppeteer from 'puppeteer'` |
|
||
| 删除 | `import { Response } from 'express'` |
|
||
|
||
其余 `buildHtml`、`buildCover`、`buildBasicInfo`、`buildExamOverview`、`buildAttendance`、`buildExamDetail`、`buildLearningAndResult`、`renderScoreTable`、`renderScoreTrendChart`、`renderAttendanceBar`、`renderAttendanceMatrix`、`css`、`pageFrame`、`pageHeader`、`pageFooter`、`esc` 等私有方法全部保留不变。
|
||
|
||
### `apps/server/src/archive/archive.controller.ts`
|
||
|
||
| 操作 | 详情 |
|
||
|------|------|
|
||
| 新增 | `GET /archive/:studentId/report-html` — 调用 `reportService.generateReportHtml(+studentId)`，返回 `{ html: string }`，记录操作日志 |
|
||
| 删除 | `GET /archive/:studentId/report` — 原 Puppeteer PDF 下载端点 |
|
||
|
||
### 依赖清理
|
||
|
||
| 文件 | 操作 |
|
||
|------|------|
|
||
| `apps/server/package.json` | 移除 `puppeteer` |
|
||
| `apps/server/Dockerfile` | 移除 Chromium 相关依赖安装步骤 |
|
||
|
||
## 前端改动
|
||
|
||
### `apps/admin/src/pages/StudentProfile/index.tsx`
|
||
|
||
| 操作 | 详情 |
|
||
|------|------|
|
||
| 修改 | "生成档案报表"按钮文本 → "预览报告" |
|
||
| 修改 | `handleDownloadReport` → `handlePreviewReport`：`fetch(/api/archive/:id/report-html)` → 解析 JSON → `window.open` → `document.write(html)` |
|
||
|
||
|
||
## 影响范围
|
||
|
||
| 层级 | 文件 | 改动量 |
|
||
|------|------|--------|
|
||
| 后端 service | `archive-report.service.ts` | +15 行, -30 行 |
|
||
| 后端 controller | `archive.controller.ts` | +12 行, -10 行 |
|
||
| 后端依赖 | `package.json`, `Dockerfile` | 小改动 |
|
||
| 前端 | `StudentProfile/index.tsx` | ~10 行 |
|
||
|
||
无数据库变更，无 API 兼容性破坏（`/report` 端点被替换为 `/report-html`）。
|
||
|
||
## 验收标准
|
||
|
||
- [ ] 点击「预览报告」按钮，新窗口打开完整报告（封面→学情记录共 6 页）
|
||
- [ ] 报告样式与现有 PDF 版视觉一致
|
||
- [ ] 新窗口内 Ctrl+P 可正常打印，打印预览显示分页正确
|
||
- [ ] Puppeteer 已从依赖中移除，Docker 构建不再安装 Chromium
|
||
- [ ] 现有学生档案 CRUD 功能不受影响
|