# PDF格式身份证支持说明

## 更新内容

系统现已支持PDF格式的身份证正反面文件。当身份证文件为PDF时，系统会自动转换为图片后进行OCR识别。

## 主要变更

### 1. 新增文件
- `src/PDFToImageConverter.php` - PDF转图片转换器
- `test_pdf_id_card.php` - 测试脚本

### 2. 修改文件
- `src/PortraitExtractor.php` - 增加PDF格式支持

## 工作原理

```
身份证文件 → 检测格式 → 如果是PDF → 转换为JPG → Base64编码 → OCR识别
                      → 如果是图片 → 直接使用URL → OCR识别
```

### 关键点

1. **PDF文件处理**
   - 自动下载到本地（如果是URL）
   - 使用Ghostscript转换为JPG（300 DPI，质量90）
   - 转换为Base64编码
   - 使用`ImageBase64`参数调用腾讯云OCR

2. **普通图片处理**
   - 直接使用`ImageUrl`参数调用OCR
   - 无需额外转换

3. **重要提醒**
   - ⚠️ `ImageUrl`和`ImageBase64`不能同时使用
   - ⚠️ PDF文件必须使用`ImageBase64`
   - ⚠️ 普通图片使用`ImageUrl`

## 使用方法

### 无需修改现有代码

系统会自动检测文件格式并选择合适的处理方式：

```php
// 原有代码无需修改，自动支持PDF
$result = $portraitExtractor->extractPortrait(
    $url,  // 可以是PDF或图片URL
    'FRONT',
    ['crop_size' => 256, 'quality' => 90, 'save_cropped_card' => true]
);
```

### 在VAT文档生成中

`VATDocumentGenerator::processIdCard()`方法会自动处理PDF格式：

```php
// 身份证正面（支持PDF和图片）
$frontRetryResult = $this->retryOperation(
    '身份证正面OCR识别',
    function () use ($portraitExtractor, $url) {
        return $portraitExtractor->extractPortrait(
            $url,  // 自动检测PDF或图片
            'FRONT',
            ['crop_size' => 256, 'quality' => 90, 'save_cropped_card' => true]
        );
    },
    3,
    3
);

// 身份证反面（支持PDF和图片）
$backRetryResult = $this->retryOperation(
    '身份证反面OCR识别',
    function () use ($portraitExtractor, $url) {
        return $portraitExtractor->extractPortrait(
            $url,  // 自动检测PDF或图片
            'BACK',
            ['crop_size' => 256, 'quality' => 90, 'save_cropped_card' => true]
        );
    },
    3,
    3
);
```

## 系统要求

### 必需软件
- **Ghostscript** - PDF转换工具
  - Windows: 自动查找`gswin64c`或`gswin32c`
  - Linux/Mac: 自动查找`gs`

### 安装Ghostscript

**Windows:**
1. 下载：https://www.ghostscript.com/download/gsdnld.html
2. 安装后确保在系统PATH中

**Linux:**
```bash
sudo apt-get install ghostscript  # Ubuntu/Debian
sudo yum install ghostscript      # CentOS/RHEL
```

**Mac:**
```bash
brew install ghostscript
```

## 测试

运行测试脚本验证功能：
```bash
php test_pdf_id_card.php
```

## 临时文件管理

系统会自动管理临时文件：
- 下载的PDF文件
- 转换的图片文件
- 异常情况下也会清理

## 性能影响

- PDF转换通常需要1-3秒
- 已集成到异步任务中，不影响接口响应
- 包含重试机制，提高成功率

## 日志记录

查看处理日志：
```bash
# 异步任务日志
tail -f logs/async_task_*.log

# PDF生成日志
tail -f logs/pdf_generator_*.log
```

日志包含：
- PDF格式检测
- 文件下载
- PDF转换
- OCR请求类型（ImageUrl或ImageBase64）
- 临时文件清理

## 常见问题

### Q: 如何知道系统是否支持PDF？
A: 运行测试脚本或查看日志，会显示"检测到PDF文件，开始转换为图片"

### Q: PDF转换失败怎么办？
A: 检查Ghostscript是否正确安装，运行`gs --version`验证

### Q: 为什么PDF要用ImageBase64而不是ImageUrl？
A: 因为PDF需要先转换为图片，转换后的图片是临时文件，使用Base64更可靠

### Q: 会影响现有的图片格式身份证吗？
A: 不会，图片格式仍然使用原有的ImageUrl方式，性能不受影响

## 技术支持

如有问题，请查看：
1. 日志文件：`logs/`目录
2. 测试脚本：`test_pdf_id_card.php`

---

**更新日期**: 2026-01-21  
**版本**: v1.0.0