report_viewer/PDF生成环境说明.md

# PDF 生成环境说明文档

## 📋 概述

本项目使用 Python 脚本将 JSON 数据转换为 PDF 报告。主要依赖 WeasyPrint 库进行 HTML 到 PDF 的转换。

## 🔧 环境要求

### Python 版本
- **Python 3.8+** （推荐 Python 3.9 或更高版本）
- 支持 Windows、Linux、macOS

### 系统依赖

#### Windows
- 需要安装 **GTK+ 运行时库**（WeasyPrint 的必需依赖）
- 推荐使用 Conda 环境（自动处理依赖）

#### Linux
- 需要安装系统级字体库和 GTK+ 相关库
- Ubuntu/Debian: `sudo apt-get install python3-dev python3-pip python3-cffi libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info`
- CentOS/RHEL: `sudo yum install python3-devel python3-pip cairo pango gdk-pixbuf2 libffi`

#### macOS
- 需要安装 GTK+ 和相关库
- 推荐使用 Homebrew: `brew install cairo pango gdk-pixbuf libffi`

## 📦 Python 依赖包

项目依赖以下 Python 包（见 `requirements.txt`）：

| 包名 | 版本要求 | 说明 |
|------|---------|------|
| jinja2 | >=3.1.2 | HTML 模板引擎，用于渲染报告模板 |
| weasyprint | >=60.0 | PDF 生成库，将 HTML 转换为 PDF |

## 🚀 安装步骤

### 方法一：使用 Conda（推荐，Windows 用户首选）

Conda 会自动处理所有系统依赖，包括 GTK+ 运行时库。

```bash
# 1. 创建 Conda 环境（可选）
conda create -n pdf-generator python=3.9
conda activate pdf-generator

# 2. 安装 WeasyPrint（自动安装所有依赖）
conda install -c conda-forge weasyprint

# 3. 安装其他依赖
pip install jinja2
```

### 方法二：使用 pip + 手动安装系统依赖

#### Windows

1. **安装 GTK+ 运行时库**
   - 下载地址：https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
   - 下载并安装最新的 `gtk3-runtime-*.exe`（64位版本）
   - 安装到默认路径：`C:\Program Files\GTK3-Runtime Win64`
   - 确保安装程序自动添加到 PATH，或手动添加：`C:\Program Files\GTK3-Runtime Win64\bin`

2. **安装 Python 依赖**
   ```bash
   pip install -r requirements.txt
   ```

3. **重启终端**（重要！让 PATH 生效）

#### Linux

```bash
# 1. 安装系统依赖（Ubuntu/Debian 示例）
sudo apt-get update
sudo apt-get install python3-dev python3-pip python3-cffi \
    libcairo2 libpango-1.0-0 libpangocairo-1.0-0 \
    libgdk-pixbuf2.0-0 libffi-dev shared-mime-info

# 2. 安装 Python 依赖
pip install -r requirements.txt
```

#### macOS

```bash
# 1. 安装系统依赖（使用 Homebrew）
brew install cairo pango gdk-pixbuf libffi

# 2. 安装 Python 依赖
pip install -r requirements.txt
```

### 方法三：使用虚拟环境（推荐用于生产环境）

```bash
# 1. 创建虚拟环境
python -m venv venv

# 2. 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt
```

## ✅ 验证安装

运行以下命令验证环境是否正确配置：

```bash
python -c "from weasyprint import HTML; print('WeasyPrint 安装成功！')"
```

如果出现错误，请参考下面的"常见问题"部分。

## 📝 使用方法

### 基本用法

```bash
python generate_pdf.py <数据文件> [输出文件]
```

### 示例

```bash
# 使用示例数据生成 PDF
python generate_pdf.py public/example.json output.pdf

# 指定输出文件名（默认为 report.pdf）
python generate_pdf.py public/example.json my_report.pdf
```

### 数据文件格式

- 支持 JSON 格式文件
- 文件应包含 `DWBG8B4D` 或 `CDWBG8B4D` 的谛听报告数据
- 可选包含 `FLXG7E8F` 或 `FLXG0V4B` 的司法涉诉数据

## 🐛 常见问题

### 问题 1: `OSError: cannot load library 'libgobject-2.0-0'`

**原因**：Windows 系统缺少 GTK+ 运行时库。

**解决方案**：
1. **推荐**：使用 Conda 安装 WeasyPrint
   ```bash
   conda install -c conda-forge weasyprint
   ```

2. **或**：手动安装 GTK+ 运行时库
   - 下载：https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
   - 安装后重启终端

### 问题 2: `ImportError: No module named 'weasyprint'`

**原因**：WeasyPrint 未安装或不在当前 Python 环境中。

**解决方案**：
```bash
pip install weasyprint
# 或使用 Conda
conda install -c conda-forge weasyprint
```

### 问题 3: `ImportError: No module named 'jinja2'`

**原因**：Jinja2 模板引擎未安装。

**解决方案**：
```bash
pip install jinja2
```

### 问题 4: 生成的 PDF 中文显示为方块

**原因**：系统缺少中文字体。

**解决方案**：
- **Windows**：系统自带中文字体，通常无需额外配置
- **Linux**：安装中文字体
  ```bash
  sudo apt-get install fonts-wqy-microhei fonts-wqy-zenhei
  ```
- **macOS**：系统自带中文字体

### 问题 5: Conda 安装 WeasyPrint 时卡住或报错

**原因**：Conda 依赖解析时间过长或网络问题。

**解决方案**：
1. 更新 Conda：
   ```bash
   conda update conda
   ```

2. 使用国内镜像源（如果在中国）：
   ```bash
   conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
   conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
   conda config --add channels conda-forge
   ```

3. 或使用 pip + GTK+ 运行时库的方式

### 问题 6: 权限错误（Linux/macOS）

**原因**：没有权限安装系统依赖。

**解决方案**：
```bash
# 使用 sudo 安装系统依赖
sudo apt-get install ...  # Ubuntu/Debian
sudo yum install ...      # CentOS/RHEL
```

## 🔍 环境检查清单

在开始使用前，请确认：

- [ ] Python 版本 >= 3.8
- [ ] WeasyPrint 已正确安装
- [ ] Jinja2 已正确安装
- [ ] （Windows）GTK+ 运行时库已安装并添加到 PATH
- [ ] （Linux/macOS）系统依赖已安装
- [ ] 可以成功导入 WeasyPrint：`python -c "from weasyprint import HTML"`

## 📚 相关资源

- **WeasyPrint 官方文档**：https://weasyprint.org/
- **Jinja2 官方文档**：https://jinja.palletsprojects.com/
- **GTK+ Windows 运行时**：https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
- **Conda 文档**：https://docs.conda.io/

## 💡 最佳实践

1. **使用虚拟环境**：避免污染系统 Python 环境
2. **Windows 用户优先使用 Conda**：自动处理所有依赖，最简单
3. **定期更新依赖**：`pip install --upgrade weasyprint jinja2`
4. **测试环境**：在生成大量 PDF 前，先用示例数据测试

## 🔄 更新依赖

```bash
# 更新所有依赖
pip install --upgrade -r requirements.txt

# 或单独更新
pip install --upgrade weasyprint jinja2
```

## 📞 技术支持

如果遇到问题：

1. 检查 Python 版本：`python --version`
2. 检查已安装的包：`pip list | grep -E "weasyprint|jinja2"`
3. 查看错误信息：运行 `python generate_pdf.py` 查看详细错误
4. 验证环境：运行 `python -c "from weasyprint import HTML; print('OK')"`

---

**最后更新**：2025-01-20