# PDF面单条码提取功能规划
## 一、需求分析
### 背景
物流面单PDF中通常包含一维码或二维码，存储了运单号、跟踪号等核心信息，在定时任务预解析PDF缓存时同步提取条码信息，可以避免后续业务流程重复解析PDF，提升处理效率。
### 目标
1. 在定时任务解析PDF面单时，自动识别并提取其中的一维码和二维码内容
2. 存储提取到的条码信息，供后续业务场景直接使用
3. 不影响现有PDF缓存主流程，识别失败时自动降级
## 二、现有资源评估
1. **已有依赖**：项目已集成`ZXing.Net`条码识别库、`PdfSharp`PDF处理库，无需新增第三方依赖
2. **现有流程**：定时任务已有完整的PDF下载、解析、页数校验流程，可直接嵌入条码识别步骤
3. **存储基础**：已有`label_pdf_cache`表，可扩展字段存储条码信息
## 三、方案设计
### 1. 数据库扩展
#### 1.1 新增基础关联字段（参考LabelReplaceEntity命名规范）
| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| FinalMileTrackingNumber | varchar(100) | 尾程跟踪单号（与订单表字段一致） |
| CustomerId | int | 客户ID（与订单表字段一致，关联customers表） |
#### 1.2 新增条码识别字段
| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| BarcodeNumber | varchar(100) | 提取到的条码单号 |
| BarcodeType | tinyint | 条码类型：0=未识别到，1=一维码，2=二维码 |
| BarcodeConfidence | int | 识别置信度（0-100，数值越高识别结果越可靠） |
| BarcodeExtractTime | datetime | 条码提取完成时间 |
### 字段注释规范
- 所有实体类字段都添加XML注释，明确字段含义
- 数据库表字段添加COMMENT注释，便于维护和理解
- 命名完全参考订单表`LabelReplaceEntity`的命名风格，保持项目一致性
### 2. 条码识别逻辑设计
#### 识别流程：
```mermaid
graph LR
A[获取PDF字节流] --> B[渲染PDF第一页为图片]
B --> C[优先识别二维码]
C --> D{识别成功?}
D -->|是| E[存储二维码内容]
D -->|否| F[识别一维码]
F --> G{识别成功?}
G -->|是| H[存储一维码内容]
G -->|否| I[标记为未识别]
E & H & I --> J[继续后续缓存流程]
```
#### 识别策略：
- 优先识别二维码，其次识别一维码，符合物流面单常用设计
- 仅识别PDF第一页（面单通常只有一页）
- 支持常见条码格式：CODE128、CODE39、QR Code、PDF417等物流行业常用格式
- 识别失败不影响主缓存流程，仅记录日志
### 3. 性能保障
- 条码识别作为异步流程的一部分，不影响接口响应速度
- 单次识别时间控制在500ms以内，避免影响定时任务处理效率
- 识别异常时添加熔断机制，避免重复识别无效PDF
## 四、实施步骤
### 步骤1：数据结构扩展
1. 扩展`LabelPdfCache`实体类，新增条码相关字段
2. 生成数据库ALTER TABLE更新脚本，添加新字段
### 步骤2：条码识别功能实现
1. 实现条码识别工具方法，输入PDF字节流，输出识别到的条码信息
2. 集成ZXing.Net库，配置物流常用条码格式
3. 实现PDF页面转图片功能，用于条码识别
### 步骤3：定时任务集成
1. 在`LabelPdfCacheService.ProcessSingleCacheTask`方法中，PDF页数校验通过后加入条码识别步骤
2. 将识别结果保存到缓存表对应字段
3. 添加识别日志和异常处理
### 步骤4：测试验证
1. 用实际物流面单测试条码识别准确率
2. 测试识别失败场景的降级处理逻辑
3. 验证定时任务整体性能不受影响
## 五、后续扩展
1. 可根据业务需求，支持多条码识别和存储
2. 可针对不同客户的面单格式优化识别参数
3. 可将条码识别结果用于面单校验，提高数据准确性