上传源代码版本

.trae/documents/pdf_barcode_extraction_plan.md

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