93 lines
3.2 KiB
Markdown
93 lines
3.2 KiB
Markdown
# 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缓存和主业务流程
|