# PRD 需求文档：导出 PDF/Excel 格式

> 模块：服务监测（service_monitor）
> 优先级：P2
> 创建日期：2026-07-23
> 状态：待开发

---

## 1. 背景与目标

### 1.1 背景

服务监测模块已支持导出巡检报告为 Markdown 和 JSON 格式。运维人员需要更多导出选项：
- PDF 格式：保留样式，适合打印归档、邮件附件
- Excel 格式：检测项明细表格，适合数据分析和二次处理

### 1.2 目标

实现 PDF 和 Excel 格式导出：
- 复用现有报告数据结构
- 集成到现有导出菜单
- 保持与 Markdown 导出一致的 API 设计

---

## 2. 功能需求

### 2.1 导出入口

**位置**：报告详情页（`report.html`）导出菜单

**现有选项**：
- 导出 Markdown
- 导出 JSON

**新增选项**：
- 导出 PDF
- 导出 Excel

### 2.2 PDF 导出

**内容结构**：
1. 报告头：目标名称、套件类型、时间范围
2. 汇总统计：总项数、正常/警告/严重数量
3. 异常项列表（置顶）：模块、检测项、当前值、阈值、状态
4. 各模块检测明细（可折叠）

**样式要求**：
- 保留颜色标记（正常=绿色、警告=黄色、严重=红色）
- 表格样式清晰，适合打印
- 中文支持（使用系统字体）
- 页眉：报告标题 + 目标名称
- 页脚：页码 + 生成时间

**技术选型**：
- 使用 `weasyprint` 库（纯 Python，无需外部依赖）
- 复用 `compare_service.py` 的 HTML 导出模板样式

### 2.3 Excel 导出

**内容结构**：
- Sheet 1：汇总（目标名称、套件、时间、统计）
- Sheet 2：检测明细（全量检测项表格）

**表格列**：
| 列名 | 说明 |
|------|------|
| 模块 | 检测模块名称 |
| 检测项 KEY | 唯一标识 |
| 检测项名称 | 显示名称 |
| 当前值 | 实际检测值 |
| 阈值 | 阈值标准 |
| 状态 | 正常/警告/严重 |
| 类别 | system/service |

**样式要求**：
- 表头加粗、冻结首行
- 状态列使用条件格式（正常=绿色背景、警告=黄色、严重=红色）
- 列宽自适应

**技术选型**：
- 使用 `openpyxl` 库（已在依赖中）

---

## 3. API 设计

### 3.1 扩展现有导出接口

```
GET /api/service-monitor/reports/{report_id}/export?format={md|json|pdf|excel}
```

**新增 format 参数值**：
- `pdf`：返回 PDF 文件
- `excel`：返回 Excel 文件

**响应头**：
- PDF：`Content-Type: application/pdf`
- Excel：`Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`

**文件名**：
- PDF：`report_{report_id}.pdf`
- Excel：`report_{report_id}.xlsx`

---

## 4. 技术方案

### 4.1 后端实现

**新增函数**：

```python
# report_service.py

def export_pdf(report_id: str) -> Optional[bytes]:
    """导出 PDF 格式报告。

    Returns:
        PDF 二进制数据，报告不存在返回 None
    """
    pass

def export_excel(report_id: str) -> Optional[bytes]:
    """导出 Excel 格式报告。

    Returns:
        Excel 二进制数据，报告不存在返回 None
    """
    pass
```

**修改文件**：
- `skill/code/web/service_monitor/services/report_service.py`：新增 `export_pdf()` 和 `export_excel()` 函数
- `skill/code/web/service_monitor/routes.py`：`api_export_report()` 增加 `pdf` 和 `excel` 格式支持

**新增依赖**：
- `weasyprint>=60.0`：PDF 生成（需添加到 requirements.txt）

### 4.2 前端修改

**修改文件**：
- `skill/code/web/templates/service_monitor/report.html`：导出菜单新增两个选项

---

## 5. 验收标准

### 5.1 功能验收

- [ ] 报告详情页导出菜单显示"导出 PDF"、"导出 Excel"
- [ ] PDF 导出成功，内容完整
- [ ] PDF 样式清晰，中文显示正常
- [ ] Excel 导出成功，包含两个 Sheet
- [ ] Excel 表格格式正确，状态列有颜色标记
- [ ] Token 免登访问时支持导出 PDF/Excel

### 5.2 边界情况

- [ ] 报告不存在时返回 404 错误
- [ ] 大报告（500+ 检测项）导出不超时
- [ ] 无异常项时 PDF 正常渲染

---

## 6. 时间规划

| 阶段 | 任务 | 预估时间 |
|------|------|---------|
| 阶段一 | PDF 导出实现 | 1.5h |
| 阶段二 | Excel 导出实现 | 1h |
| 阶段三 | 前端集成 + 测试 | 0.5h |
| **合计** | | **3h** |

---

## 7. 相关文档

- `HANDOFF_服务监测.md`：模块交接文档
- `PRD_需求文档_报告对比功能.md`：参考 HTML 导出样式