LabelChange-server/.trae/documents/pdf_barcode_extraction_plan.md

PDF面单条码提取功能规划

一、需求分析

背景

物流面单PDF中通常包含一维码或二维码，存储了运单号、跟踪号等核心信息，在定时任务预解析PDF缓存时同步提取条码信息，可以避免后续业务流程重复解析PDF，提升处理效率。

目标

1. 在定时任务解析PDF面单时，自动识别并提取其中的一维码和二维码内容
2. 存储提取到的条码信息，供后续业务场景直接使用
3. 不影响现有PDF缓存主流程，识别失败时自动降级

二、现有资源评估

1. 已有依赖：项目已集成ZXing.Net条码识别库、PdfSharpPDF处理库，无需新增第三方依赖
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. 条码识别逻辑设计

识别流程：

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. 可将条码识别结果用于面单校验，提高数据准确性