上传源代码版本

.trae/documents/barcode_extraction_implementation_plan.md

@@ -0,0 +1,92 @@
+# PDF条码识别功能实现规划
+## 一、现状分析
+### 当前代码状态
+- 已存在`ExtractBarcodeFromPdfAsync`方法框架，位于`LabelPdfCacheService.cs:L344-354`
+- 方法签名完整，返回类型为`(string barcodeNumber, byte barcodeType, int confidence)`
+- 当前只返回空值`(string.Empty, 0, 0)`，不影响主流程
+
+### 现有资源
+- 项目已集成`ZXing.Net`条码识别库
+- 项目已集成`PdfSharp`和`System.Drawing`用于PDF和图片处理
+- 项目已有HTTP客户端工厂和日志记录体系
+
+## 二、技术方案设计
+### 实现策略
+1. **PDF页面转图片**：使用System.Drawing.Common将PDF第一页渲染为Bitmap
+2. **条码识别顺序**：优先二维码（QR Code）→ 一维码（CODE128、CODE39等）
+3. **置信度评估**：基于识别结果的可靠性评分（0-100）
+4. **异常处理**：识别失败不影响主流程，仅记录日志
+
+### 实现细节
+#### 步骤1：导入必要的命名空间
+- `ZXing`：条码识别核心库
+- `ZXing.Common`：解码选项配置
+- `System.Drawing`：图片处理
+
+#### 步骤2：实现RecognizeBarcodeAsync辅助方法
+- 创建BarcodeReader实例
+- 配置识别参数（自动旋转、反转尝试、多格式支持）
+- 返回识别结果和置信度
+
+#### 步骤3：实现主方法ExtractBarcodeFromPdfAsync
+流程：
+1. 读取PDF第一页并转换为Bitmap图像
+2. 调用RecognizeBarcodeAsync识别QR Code
+3. 若失败，识别CODE128一维码
+4. 若仍失败，尝试其他常见格式（CODE39、EAN-13、UPC-A）
+5. 若全部失败，返回(string.Empty, 0, 0)
+
+#### 步骤4：错误处理和日志
+- 捕获PDF处理异常（损坏、格式错误）
+- 捕获条码识别异常
+- 记录识别成功/失败的详细日志
+- 不抛出异常，防止影响主流程
+
+## 三、实施步骤
+### Step 1：添加必要的using声明
+- 在文件头部添加ZXing相关命名空间
+- 确保System.Drawing可用
+
+### Step 2：实现RecognizeBarcodeAsync方法
+- 创建条码读取器
+- 配置识别选项
+- 执行识别并返回结果
+
+### Step 3：实现ExtractBarcodeFromPdfAsync方法
+- PDF页面读取和转换为图片
+- 调用识别方法
+- 按优先级尝试多种格式
+- 返回最终结果
+
+### Step 4：编译验证
+- dotnet build确保无编译错误
+- 检查对现有类型和API的引用正确性
+
+### Step 5：集成验证
+- 确认定时任务能正常调用此方法
+- 确认返回值能正确存储到数据库
+
+## 四、关键实现细节
+### 条码识别优先级
+1. **QR Code**（二维码）：物流面单最常见
+2. **CODE128**：物流行业标准一维码
+3. **CODE39、CODE93、EAN-13、UPC-A**：备选格式
+
+### 置信度评分规则
+- 成功识别：基于ZXing返回的ResultPoint数量和位置准确度评分
+- 失败识别：返回0
+
+### 异常处理清单
+- PDF格式错误或损坏
+- 页数为0或负数
+- PDF转图片失败
+- 图片为空或无效
+- 条码识别内部错误
+
+## 五、预期结果
+完成此实现后：
+- 定时任务在缓存PDF时自动识别条码
+- 识别到的条码单号存储到`LabelPdfCache.BarcodeNumber`
+- 条码类型存储到`BarcodeType`字段（1=一维码，2=二维码）
+- 识别置信度存储到`BarcodeConfidence`字段
+- 识别失败不影响PDF缓存和主业务流程