Add README of "Export as PDF"

2025-11-18 20:11:03 +08:00
parent 5e82185bee
commit 26ab0616e9
3 changed files with 625 additions and 0 deletions
--- a/ReportEngine/docs/PDF_EXPORT_GUIDE.md
+++ b/ReportEngine/docs/PDF_EXPORT_GUIDE.md
@@ -0,0 +1,309 @@
+# PDF导出优化系统使用指南
+
+## 概述
+
+全新的PDF导出系统现已集成到ReportEngine中，提供了智能布局优化功能，确保PDF文档美观且无溢出问题。
+
+## 核心特性
+
+### 1. 智能布局优化
+
+系统会自动分析文档内容并优化布局参数：
+
+- **KPI卡片优化**
+  - 自动调整每行列数（1-3列）
+  - 根据数值长度动态调整字号
+  - 防止数值溢出
+
+- **表格优化**
+  - 根据列数自动缩小字号
+  - 智能调整单元格内边距
+  - 支持长内容自动换行
+
+- **文本优化**
+  - 检测长文本自动增加行高
+  - 防止标题孤行
+  - 优化段落间距
+
+### 2. 配置持久化
+
+所有优化决策都会保存到日志文件中：
+- 位置：`logs/pdf_layouts/layout_YYYYMMDD_HHMMSS.json`
+- 内容：文档统计信息、优化策略、最终配置
+
+### 3. 前端集成
+
+用户只需点击"下载PDF"按钮，系统将：
+1. 自动分析报告内容
+2. 应用最佳布局优化
+3. 生成高质量PDF
+4. 自动下载到本地
+
+## 使用方法
+
+### 方式一：通过Web界面（推荐）
+
+1. 启动系统：`python app.py`
+2. 生成报告：在Report Engine中生成最终报告
+3. 点击"下载PDF"按钮
+4. 系统自动优化并下载PDF
+
+### 方式二：通过API
+
+#### 根据任务ID导出
+
+```bash
+curl -X GET \
+  "http://localhost:5000/api/report/export/pdf/YOUR_TASK_ID?optimize=true" \
+  -o report.pdf
+```
+
+#### 从IR JSON直接导出
+
+```bash
+curl -X POST \
+  "http://localhost:5000/api/report/export/pdf-from-ir" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "document_ir": {...},
+    "optimize": true
+  }' \
+  -o report.pdf
+```
+
+### 方式三：通过Python脚本
+
+```python
+from pathlib import Path
+import json
+from ReportEngine.renderers import PDFRenderer
+
+# 读取IR数据
+with open('report_ir.json', 'r', encoding='utf-8') as f:
+    document_ir = json.load(f)
+
+# 创建渲染器并导出PDF
+renderer = PDFRenderer()
+renderer.render_to_pdf(
+    document_ir,
+    'output.pdf',
+    optimize_layout=True  # 启用布局优化
+)
+```
+
+## 配置选项
+
+### 全局配置
+
+```python
+from ReportEngine.renderers import PDFLayoutOptimizer, PDFLayoutConfig
+
+# 自定义配置
+config = PDFLayoutConfig(
+    page=PageLayout(
+        font_size_base=14,
+        line_height=1.6
+    ),
+    kpi_card=KPICardLayout(
+        font_size_value=32,
+        min_height=120
+    ),
+    # ... 更多配置
+)
+
+# 使用自定义配置
+optimizer = PDFLayoutOptimizer(config)
+renderer = PDFRenderer(layout_optimizer=optimizer)
+```
+
+### 优化策略
+
+| 场景 | 触发条件 | 优化措施 |
+|------|---------|---------|
+| KPI数量多 | > 6个 | 调整为3列布局 |
+| KPI数量少 | ≤ 2个 | 调整为1列布局 |
+| KPI数值长 | > 10字符 | 字号从32px调整为28px |
+| KPI数值很长 | > 15字符 | 字号从32px调整为24px |
+| 表格列多 | > 6列 | 字号从13/12px调整为11/10px |
+| 文本很长 | > 200字符 | 行高从1.6增加到1.8 |
+
+## 测试
+
+运行测试脚本验证所有功能：
+
+```bash
+# 设置环境变量
+export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
+
+# 运行测试
+python test_pdf_optimized.py
+```
+
+测试将生成：
+- `test_pdf_optimized.pdf` - 启用优化的PDF
+- `test_pdf_default.pdf` - 默认设置的PDF（对比）
+- `test_layout_config.json` - 布局配置
+- `logs/pdf_layouts/` - 优化日志
+
+## 优化日志格式
+
+```json
+{
+  "timestamp": "2024-11-18T19:41:10.983000",
+  "document_stats": {
+    "kpi_count": 10,
+    "table_count": 2,
+    "chart_count": 2,
+    "max_kpi_value_length": 14,
+    "max_table_columns": 8
+  },
+  "optimizations": [
+    "KPI数值过长(14字符)，字号从32调整为28",
+    "KPI卡片较多(10个)，每行列数从2调整为3",
+    "表格列数较多(8列)，缩小字号和内边距"
+  ],
+  "final_config": {
+    "page": {...},
+    "kpi_card": {...},
+    "table": {...}
+  }
+}
+```
+
+## 故障排除
+
+### 问题1：WeasyPrint库加载失败
+
+**症状**：
+```
+OSError: cannot load library 'libpango-1.0-0'
+```
+
+**解决方案**：
+```bash
+# macOS
+export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
+
+# 或在脚本中设置
+import os
+os.environ['DYLD_LIBRARY_PATH'] = '/opt/homebrew/lib'
+```
+
+### 问题2：字体文件缺失
+
+**症状**：
+```
+FileNotFoundError: 未找到字体文件
+```
+
+**解决方案**：
+确保以下字体文件存在：
+- `ReportEngine/renderers/assets/fonts/SourceHanSerifSC-Medium.otf`
+
+### 问题3：PDF布局仍有问题
+
+**解决方案**：
+1. 检查优化日志：`logs/pdf_layouts/`
+2. 查看应用了哪些优化策略
+3. 如需自定义，修改配置参数
+4. 禁用优化对比：`optimize_layout=False`
+
+## 性能优化建议
+
+1. **首次导出**：需要加载字体文件，可能需要几秒钟
+2. **字体子集化**：对于大型报告，考虑使用字体子集以减小文件大小
+3. **图表处理**：图表会自动转换为表格，提高PDF渲染速度
+4. **批量导出**：复用同一个PDFRenderer实例可以提高效率
+
+## 架构说明
+
+```
+┌─────────────────────────────────────────┐
+│           Web UI / API                  │
+│  (用户点击"下载PDF"按钮)                  │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│      Flask API Endpoint                 │
+│  /api/report/export/pdf/:task_id        │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│      PDFLayoutOptimizer                 │
+│  • 分析文档结构                          │
+│  • 智能调整布局参数                      │
+│  • 保存优化日志                          │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│      HTMLRenderer                       │
+│  • 将IR转换为HTML                        │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│      PDFRenderer                        │
+│  • 注入优化的CSS                         │
+│  • 嵌入字体                             │
+│  • 使用WeasyPrint生成PDF                │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│      优化的PDF文件                       │
+│  • 无溢出                               │
+│  • 布局美观                             │
+│  • 自动分页                             │
+└─────────────────────────────────────────┘
+```
+
+## 更新日志
+
+### v1.0.0 (2024-11-18)
+
+**新增功能**：
+- ✅ PDF布局智能优化器
+- ✅ 自动调整字号、行间距、网格列数
+- ✅ 配置持久化系统
+- ✅ Flask API集成
+- ✅ 前端一键导出
+
+**优化措施**：
+- ✅ KPI卡片防溢出
+- ✅ 表格自适应布局
+- ✅ 长文本行高优化
+- ✅ 标题防孤行
+- ✅ 图表转表格渲染
+
+**测试覆盖**：
+- ✅ 多种KPI场景测试
+- ✅ 复杂表格测试
+- ✅ 图表渲染测试
+- ✅ 长文本测试
+
+## 未来计划
+
+- [ ] 支持更多纸张尺寸（A3、Letter等）
+- [ ] 添加PDF水印功能
+- [ ] 支持页眉页脚自定义
+- [ ] 提供更多布局模板
+- [ ] 优化大型文档渲染性能
+
+## 技术栈
+
+- **PDF生成**：WeasyPrint
+- **布局优化**：自研PDFLayoutOptimizer
+- **字体**：思源宋体（SourceHanSerifSC）
+- **后端框架**：Flask
+- **前端**：原生JavaScript
+
+## 贡献者
+
+欢迎提交Issue和PR来改进PDF导出系统！
+
+## 许可证
+
+本项目遵循项目主仓库的许可证。
--- a/ReportEngine/docs/PDF_EXPORT_QUICKSTART.md
+++ b/ReportEngine/docs/PDF_EXPORT_QUICKSTART.md
@@ -0,0 +1,134 @@
+# PDF导出功能快速启动
+
+## 立即开始
+
+### 1. 启动系统
+
+```bash
+# 设置环境变量（macOS必需）
+export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
+
+# 启动Flask应用
+python app.py
+```
+
+### 2. 生成报告
+
+1. 在浏览器中打开 `http://localhost:5000`
+2. 启动 Insight、Media、Query Engine
+3. 输入搜索主题，点击搜索
+4. 切换到 Report Engine 标签
+5. 点击"生成最终报告"
+
+### 3. 导出PDF
+
+报告生成完成后：
+1. 点击"**下载PDF**"按钮
+2. 系统自动：
+   - 分析报告内容
+   - 优化布局参数
+   - 生成高质量PDF
+   - 自动下载文件
+
+## 快速测试
+
+想立即看到效果？运行测试脚本：
+
+```bash
+# 设置环境变量
+export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
+
+# 运行测试（生成示例PDF）
+python test_pdf_optimized.py
+
+# 查看结果
+open test_pdf_optimized.pdf
+```
+
+测试会生成：
+- ✅ 包含10个KPI卡片的报告
+- ✅ 复杂的8列表格
+- ✅ 多个图表和色块
+- ✅ 自动优化的布局
+
+## 优化效果对比
+
+系统会自动：
+
+| 问题 | 优化前 | 优化后 |
+|------|--------|--------|
+| KPI数值溢出 | ⚠️ 字号固定32px，长数值溢出 | ✅ 自动缩小到28px或24px |
+| KPI布局拥挤 | ⚠️ 固定2列，10个卡片显得拥挤 | ✅ 自动调整为3列 |
+| 表格字体过大 | ⚠️ 8列表格字体过大 | ✅ 字号从13/12px缩小到11/10px |
+| 长文本难读 | ⚠️ 行高固定1.6 | ✅ 自动增加到1.8 |
+
+## 查看优化日志
+
+想了解系统做了哪些优化？
+
+```bash
+# 查看最新的优化日志
+cat logs/pdf_layouts/layout_*.json
+
+# 或打开保存的配置文件
+cat test_layout_config.json
+```
+
+日志示例：
+```json
+{
+  "optimizations": [
+    "KPI数值过长(14字符)，字号从32调整为28",
+    "KPI卡片较多(10个)，每行列数从2调整为3",
+    "表格列数较多(8列)，缩小字号和内边距"
+  ]
+}
+```
+
+## 常见问题
+
+### Q: 为什么PDF生成需要几秒钟？
+A: 首次生成需要加载字体文件和分析文档，后续会更快。
+
+### Q: 可以禁用自动优化吗？
+A: 可以，在API中设置 `optimize=false`：
+```bash
+curl "http://localhost:5000/api/report/export/pdf/TASK_ID?optimize=false"
+```
+
+### Q: 如何自定义布局参数？
+A: 参考 [PDF_EXPORT_GUIDE.md](PDF_EXPORT_GUIDE.md) 中的"配置选项"章节。
+
+## 技术亮点
+
+✨ **智能布局分析**
+- 自动检测KPI数量、表格复杂度、文本长度
+- 根据内容特征动态调整参数
+
+✨ **无损质量**
+- 使用WeasyPrint专业PDF引擎
+- 完整保留CSS样式
+- 完美支持中文字体
+
+✨ **开箱即用**
+- 前端一键导出
+- 无需额外配置
+- 自动应用最佳实践
+
+## 下一步
+
+- 📖 阅读完整文档：[PDF_EXPORT_GUIDE.md](PDF_EXPORT_GUIDE.md)
+- 🧪 运行测试：`python test_pdf_optimized.py`
+- 🎨 自定义布局：修改配置参数
+- 🚀 集成到生产：通过API批量导出
+
+## 问题反馈
+
+遇到问题？
+1. 查看 [PDF_EXPORT_GUIDE.md](PDF_EXPORT_GUIDE.md) 的"故障排除"章节
+2. 检查 `logs/pdf_layouts/` 目录的优化日志
+3. 提交Issue到项目仓库
+
+---
+
+享受全新的PDF导出体验！ 🎉
--- a/ReportEngine/docs/PDF_EXPORT_README.md
+++ b/ReportEngine/docs/PDF_EXPORT_README.md
@@ -0,0 +1,182 @@
+# 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
+**状态**: ✅ 已测试，无乱码