# Python PDF 导出 - 使用指南

## ✅ 解决方案说明

已将PDF导出从浏览器端（jsPDF）改为**Python直接生成**，使用WeasyPrint库，完美解决中文乱码问题。

### 优势
- ✓ **无乱码**：使用思源宋体（SourceHanSerifSC），完美显示所有中文字符
- ✓ **样式保留**：100%保留HTML的所有CSS样式
- ✓ **自动优化**：自动处理分页、布局、图表转表格
- ✓ **高质量**：生成的PDF可直接用于打印和分发

## 📦 依赖安装

### 1. 安装系统依赖（已完成）
```bash
brew install pango cairo gdk-pixbuf
```

### 2. 安装Python库（已完成）
```bash
pip3 install weasyprint
```

## 🚀 使用方法

### 方法一：直接使用Python（推荐）

```bash
# 设置环境变量
export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH

# 运行导出
python3 ReportEngine/scripts/export_to_pdf.py final_reports/ir/report_ir_xxx.json

# 或从项目根目录运行
python3 -m ReportEngine.scripts.export_to_pdf final_reports/ir/report_ir_xxx.json
```

### 方法二：使用便捷脚本（如果有的话）

```bash
# 基本用法（自动生成同名PDF）
./pdf_export.sh final_reports/ir/report_ir_xxx.json

# 指定输出路径
./pdf_export.sh final_reports/ir/report_ir_xxx.json my_report.pdf
```

### 方法三：在代码中使用

```python
from ReportEngine.renderers import PDFRenderer
import json

# 读取报告数据
with open("report_ir.json", "r") as f:
    document_ir = json.load(f)

# 生成PDF
renderer = PDFRenderer()
renderer.render_to_pdf(document_ir, "output.pdf")
```

## 📊 测试样例

已生成两个测试PDF：

1. **综合样式测试** ([test_comprehensive.pdf](test_comprehensive.pdf))
   - 包含所有样式元素
   - 字体、标点、列表、表格、KPI卡片等

2. **真实报告** ([report_土木工程_python.pdf](report_土木工程_python.pdf))
   - 使用真实的土木工程报告数据
   - 完整展示实际使用效果

## ✨ 特性说明

### 1. 字体支持
- 优先使用：`SourceHanSerifSC-Medium.otf`（24MB完整版）
- 备选方案：`SourceHanSerifSC-Medium-Subset.ttf`（3.7MB子集版）
- 覆盖：所有常用汉字、标点符号、数字、英文

### 2. 样式保留
- 响应式布局 → PDF优化布局
- 交互按钮 → 自动隐藏
- Chart.js图表 → 自动显示fallback表格
- 所有CSS样式完整保留

### 3. 分页优化
- 标题不孤立（避免标题单独在页末）
- 表格和卡片避免跨页断裂
- 引用块和callout保持完整

## 🔧 故障排除

### 问题1：找不到libpango库

**症状**：
```
OSError: cannot load library 'libpango-1.0-0'
```

**解决**：
```bash
# 使用提供的pdf_export.sh脚本（已自动设置环境变量）
./pdf_export.sh <your_file.json>

# 或手动设置环境变量
export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
```

### 问题2：字体文件缺失

**症状**：
```
FileNotFoundError: 未找到字体文件
```

**解决**：
确保以下任一字体文件存在：
- `ReportEngine/renderers/assets/fonts/SourceHanSerifSC-Medium.otf`
- `ReportEngine/renderers/assets/fonts/SourceHanSerifSC-Medium-Subset.ttf`

### 问题3：PDF仍然有乱码

**解决**：
1. 检查字体文件是否完整（应该是24MB或3.7MB）
2. 使用pdftotext验证：`pdftotext output.pdf - | head`
3. 如有问题，重新生成字体子集或使用完整版

## 📝 开发说明

### 核心文件

- [PDFRenderer](../renderers/pdf_renderer.py) - PDF渲染器主类
- [HTMLRenderer](../renderers/html_renderer.py) - HTML渲染器（被PDF渲染器使用）
- [export_to_pdf.py](../scripts/export_to_pdf.py) - 命令行工具
- [pdf_export.sh](../../pdf_export.sh) - 便捷启动脚本（如果有的话）

### 工作流程

```
Document IR (JSON)
    ↓
HTMLRenderer.render()
    ↓
HTML with embedded font (base64)
    ↓
WeasyPrint
    ↓
PDF (with SourceHanSerif font)
```

## 🎯 下一步

如需集成到Web应用：

1. **Flask/FastAPI后端**
   ```python
   from flask import send_file
   from ReportEngine.renderers import PDFRenderer

   @app.route('/export_pdf')
   def export_pdf():
       renderer = PDFRenderer()
       pdf_bytes = renderer.render_to_bytes(document_ir)
       return send_file(io.BytesIO(pdf_bytes), mimetype='application/pdf')
   ```

2. **前端按钮**
   ```javascript
   document.getElementById('export-btn').addEventListener('click', () => {
       window.open('/export_pdf', '_blank');
   });
   ```

---

**生成时间**: 2025-11-18
**版本**: 1.0
**状态**: ✅ 已测试，无乱码