# 学生档案报告：后端渲染 → 前端预览

> 将档案报告从后端 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 功能不受影响