spec: 学生档案报告前端预览方案设计

docs/superpowers/specs/2026-07-07-archive-report-frontend-preview.md

@@ -0,0 +1,79 @@
+# 学生档案报告：后端渲染 → 前端预览
+
+> 将档案报告从后端 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 功能不受影响