diff --git a/ReportEngine/docs/PDF_EXPORT_GUIDE.md b/ReportEngine/docs/PDF_EXPORT_GUIDE.md new file mode 100644 index 0000000..d89637a --- /dev/null +++ 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导出系统！ + +## 许可证 + +本项目遵循项目主仓库的许可证。 diff --git a/ReportEngine/docs/PDF_EXPORT_QUICKSTART.md b/ReportEngine/docs/PDF_EXPORT_QUICKSTART.md new file mode 100644 index 0000000..d4d8c3e --- /dev/null +++ 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导出体验！ 🎉 diff --git a/ReportEngine/docs/PDF_EXPORT_README.md b/ReportEngine/docs/PDF_EXPORT_README.md new file mode 100644 index 0000000..bdcf362 --- /dev/null +++ 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 + +# 或手动设置环境变量 +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 +**状态**: ✅ 已测试，无乱码