3.8 KiB
3.8 KiB
PDF面单条码提取功能规划
一、需求分析
背景
物流面单PDF中通常包含一维码或二维码，存储了运单号、跟踪号等核心信息，在定时任务预解析PDF缓存时同步提取条码信息，可以避免后续业务流程重复解析PDF，提升处理效率。
目标
- 在定时任务解析PDF面单时，自动识别并提取其中的一维码和二维码内容
- 存储提取到的条码信息，供后续业务场景直接使用
- 不影响现有PDF缓存主流程，识别失败时自动降级
二、现有资源评估
- 已有依赖：项目已集成
ZXing.Net条码识别库、PdfSharpPDF处理库，无需新增第三方依赖 - 现有流程：定时任务已有完整的PDF下载、解析、页数校验流程，可直接嵌入条码识别步骤
- 存储基础：已有
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. 条码识别逻辑设计
识别流程：
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：数据结构扩展
- 扩展
LabelPdfCache实体类，新增条码相关字段 - 生成数据库ALTER TABLE更新脚本，添加新字段
步骤2：条码识别功能实现
- 实现条码识别工具方法，输入PDF字节流，输出识别到的条码信息
- 集成ZXing.Net库，配置物流常用条码格式
- 实现PDF页面转图片功能，用于条码识别
步骤3：定时任务集成
- 在
LabelPdfCacheService.ProcessSingleCacheTask方法中，PDF页数校验通过后加入条码识别步骤 - 将识别结果保存到缓存表对应字段
- 添加识别日志和异常处理
步骤4：测试验证
- 用实际物流面单测试条码识别准确率
- 测试识别失败场景的降级处理逻辑
- 验证定时任务整体性能不受影响
五、后续扩展
- 可根据业务需求，支持多条码识别和存储
- 可针对不同客户的面单格式优化识别参数
- 可将条码识别结果用于面单校验，提高数据准确性