From 488122ae9dde4f81e9863f7240e9d5ea72fe989e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=A9=AC=E4=B8=80=E4=B8=81?= <1769123563@qq.com> Date: Thu, 20 Nov 2025 00:48:22 +0800 Subject: [PATCH] Delete Useless Docs --- ReportEngine/docs/PDF_EXPORT_GUIDE.md | 309 --------------------- ReportEngine/docs/PDF_EXPORT_QUICKSTART.md | 134 --------- ReportEngine/docs/PDF_EXPORT_README.md | 182 ------------ 3 files changed, 625 deletions(-) delete mode 100644 ReportEngine/docs/PDF_EXPORT_GUIDE.md delete mode 100644 ReportEngine/docs/PDF_EXPORT_QUICKSTART.md delete mode 100644 ReportEngine/docs/PDF_EXPORT_README.md diff --git a/ReportEngine/docs/PDF_EXPORT_GUIDE.md b/ReportEngine/docs/PDF_EXPORT_GUIDE.md deleted file mode 100644 index d89637a..0000000 --- a/ReportEngine/docs/PDF_EXPORT_GUIDE.md +++ /dev/null @@ -1,309 +0,0 @@ -# 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 deleted file mode 100644 index d4d8c3e..0000000 --- a/ReportEngine/docs/PDF_EXPORT_QUICKSTART.md +++ /dev/null @@ -1,134 +0,0 @@ -# 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 deleted file mode 100644 index bdcf362..0000000 --- a/ReportEngine/docs/PDF_EXPORT_README.md +++ /dev/null @@ -1,182 +0,0 @@ -# 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 -**状态**: ✅ 已测试，无乱码