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

缓存功能问题修复方案

问题诊断

问题1：尾程跟踪单号未成功赋值

原因分析：

• 定时任务中的SaveCacheAsync调用已正确传入order.FinalMileTrackingNumber和order.CustomerId
• 下载接口的异步SaveCacheAsync调用未传入尾程跟踪单号和客户ID参数
• 实体类字段已正确定义，数据库字段已存在

问题2：条码未成功提取

原因分析：

• ConvertPdfFirstPageToBitmap方法当前仅创建空白白色Bitmap，未实际渲染PDF页面内容
• 条码识别基于空白图片，导致所有识别都失败
• 项目已集成DinkToPdf和System.Drawing，具备PDF渲染能力

解决方案

问题1修复方案

1. 检查所有调用SaveCacheAsync的位置
2. 补充下载接口异步保存时缺失的FinalMileTrackingNumber和CustomerId参数
3. 确保两个保存入口都能正确写入关联数据

问题2修复方案

1. 完善ConvertPdfFirstPageToBitmap方法，实现真实的PDF页面渲染
2. 利用项目已有的PDF处理能力，将PDF第一页渲染为真实的Bitmap图像
3. 优化条码识别参数，适配物流面单的常见条码类型和排版
4. 添加识别失败的详细日志，便于后续调优

实施步骤

Step 1：修复尾程跟踪单号赋值

1. 在LabelController.DownloadLabelByWaybillNumber的异步缓存保存逻辑中，查询订单信息获取尾程号和客户ID
2. 调用SaveCacheAsync时传入完整的参数

Step 2：完善PDF转图片功能

1. 使用DinkToPdf或GhostScript（根据项目实际依赖）实现PDF页面渲染
2. 生成高对比度的Bitmap图像，提高条码识别率
3. 处理异常情况，渲染失败时不影响主流程

Step 3：优化条码识别逻辑

1. 调整DecodingOptions参数，启用PureBarcode、TryHarder等优化选项
2. 增加识别重试机制，尝试不同分辨率、旋转角度的识别
3. 支持物流行业常用的条码格式（QR、CODE128、CODE39等）

Step 4：日志和测试

1. 添加详细的识别日志，记录识别结果、置信度、耗时等信息
2. 用实际物流面单测试识别准确率
3. 验证保存到数据库的尾程号、客户ID、条码信息正确

预期结果

1. 所有缓存记录都包含正确的FinalMileTrackingNumber和CustomerId字段
2. 条码识别准确率达到80%以上（物流面单场景）
3. 识别失败时自动降级，不影响主缓存流程