jennisonzhang/LabelChange-server

Fork 0

Files

Im-Jenisson b2a9b7d3c2 上传源代码版本

2026-06-01 16:30:29 +08:00

8.1 KiB

Raw Permalink Blame History

📊 方案 v2.0 - 最终确认总结

创建时间: 2026-05-13
状态: ✅ 等待最终确认开始实施

🎯 用户需求回顾

您的核心需求

✅ 充分利用现有PDF转字节流能力
- 已分析并确认可完全复用现有HttpClientFactory下载逻辑
✅ 验证通过即缓存
- 设计分离的保存流程，不依赖条码识别结果
✅ 不管条码识别成功与否，都要缓存
- 条码识别完全异步，失败不影响已保存的PDF
💡 主从库同步问题 （新反馈）
- 原方案：保存后等待从库同步再返回用户 ❌
- v2.0方案：立即返回，同步进行保存和条码识别 ✅
🆕 保存原始URL （新增需求）
- 便于追踪和重新下载

📈 方案对比

时间线对比

阶段	原方案	改进v2.0	提升
下载PDF	10ms	10ms	-
验证	10ms	10ms	-
保存缓存	30ms	30ms	-
等待主从同步	100ms	0ms ✅	⬇️ 消除
条码识别	500ms	500ms	-
用户等待总时间	650ms	50ms	⬇️ 13倍快

功能对比

功能	原方案	改进v2.0	说明
PDF缓存	✅ 有	✅ 有	都支持
条码识别	❌ 必须成功	✅ 可选	v2.0更稳定
主从同步	⏳ 阻塞用户	🔄 后台	v2.0非阻塞
并行处理	❌ 否	✅ 是	v2.0效率更高
原始URL	❌ 不保存	✅ 保存	v2.0可追踪

🔧 改进方案v2.0核心流程

用户请求下载标签
    ↓
【检查缓存】
    ├─ 缓存命中 → 返回（100ms）✅
    └─ 无缓存 ↓
    
【下载PDF字节流】✅ 复用现有HttpClientFactory
    ↓
【验证PDF】✅ 复用现有PdfSharp逻辑
    ├─ 失败 → 记录并返回错误
    └─ 成功 ↓
    
【同步并行处理】✅ v2.0新设计
├─────────────────────────────────────────────┐
│ 线程A（同步）        │  线程B（后台）         │
├─────────────────────────────────────────────┤
│ 保存核心数据：        │  条码识别：            │
│ - PdfBytes          │  - 转换为位图          │
│ - Status=1          │  - 使用ZXing识别       │
│ - OriginalUrl       │  - 识别完成后更新DB    │
│ - 其他关联字段       │  - 失败仅记录日志      │
│                      │                        │
│ 完成时间：<50ms ✅  │  完成时间：~500ms     │
└─────────────────────────────────────────────┘
    ↓ (线程A完成时)
【立即返回PDF给用户】✅
    
【后台继续】
    └─ 线程B继续处理条码识别
       └─ 成功：更新主库(异步)
       └─ 失败：日志记录(无影响)

💾 数据库设计

表结构 - label_pdf_cache

CREATE TABLE label_pdf_cache (
    -- 主键和唯一标识
    Id BIGINT PRIMARY KEY IDENTITY,
    NeutralWaybillNumber NVARCHAR(100) UNIQUE NOT NULL,
    
    -- 核心PDF数据（同步保存）
    PdfBytes VARBINARY(MAX) NOT NULL,
    PageCount INT NOT NULL DEFAULT 1,
    FileSize INT NOT NULL,
    OriginalUrl NVARCHAR(500),  -- ✅ 新增
    
    -- 关联字段（同步保存）
    FinalMileTrackingNumber NVARCHAR(100),
    CustomerId NVARCHAR(100),
    
    -- 缓存状态
    Status TINYINT NOT NULL DEFAULT 1,  -- 0=pending, 1=success, 2=failed
    RetryCount INT DEFAULT 0,
    LastRetryTime DATETIME2,
    ErrorMessage NVARCHAR(500),
    
    -- 条码识别信息（异步更新）
    BarcodeNumber NVARCHAR(100),
    BarcodeType TINYINT DEFAULT 0,  -- 0=无, 1=1D, 2=2D
    BarcodeConfidence INT,
    BarcodeExtractTime DATETIME2,
    
    -- 时间戳
    CreatedTime DATETIME2 DEFAULT GETUTCDATE(),
    UpdatedTime DATETIME2 DEFAULT GETUTCDATE()
);

-- 索引
CREATE NONCLUSTERED INDEX IX_NeutralWaybillNumber 
    ON label_pdf_cache(NeutralWaybillNumber);
    
CREATE NONCLUSTERED INDEX IX_Status_UpdatedTime 
    ON label_pdf_cache(Status, UpdatedTime DESC);
    
CREATE NONCLUSTERED INDEX IX_CustomerId 
    ON label_pdf_cache(CustomerId);

🛠️ 实施详单

需要修改的文件

1. LabelPdfCacheService.cs (核心)

添加GhostScript.NET命名空间
实现ConvertPdfFirstPageToBitmap()使用GhostScript
新增CacheAndRecognizeAsync()方法（并行处理）
修改ProcessSingleCacheTask()调用新方法
估计修改：80-100行

2. LabelPdfCache.cs (数据模型)

添加OriginalUrl属性
总代码量：<2行

3. LabelPdfCacheRepository.cs (数据访问)

添加UpdateBarcodeInfoAsync()方法
估计修改：20-30行

4. LabelController.cs (API端点)

调用CacheAndRecognizeAsync()而非原有逻辑
估计修改：10-15行

5. 数据库迁移脚本 (SQL)

添加OriginalUrl列
确保Status和条码字段存在
创建必要索引
估计：15-20行SQL

总工作量

代码修改：120-160行
SQL脚本：15-20行
配置文件：0行（无需修改config）
测试：5个场景

📋 验收标准

检查项	成功标准	验证方式
PDF验证	正确拒绝多页/超大PDF	单元测试
缓存保存	验证后<50ms保存成功	性能测试
条码识别	异步执行，不阻塞返回	日志观察
主从同步	无需等待从库同步	并发测试
原始URL	正确保存URL字段	数据检查
PDF渲染	返回实际PDF内容位图	视觉检查
异常处理	无unhandled异常	压力测试

⚠️ 风险评估

低风险 🟢

✅ GhostScript.NET是成熟的库
✅ 修改集中在缓存逻辑，不涉及现有业务
✅ 向后兼容，不破坏现有功能
✅ 异步处理不影响主流程

中风险 🟡

⚠️ 主从库同步延迟仍然存在（现在由业务层处理）
- 缓解：条码识别异步，不影响用户
⚠️ 条码识别可能持续失败
- 缓解：不影响已缓存的PDF，业务继续

高风险 🔴

❌ 暂无高风险项

🚀 后续支持计划

第1阶段：实施

代码开发（预计2-3天）
内部测试（预计1-2天）
代码审查

第2阶段：验收

功能测试
性能测试
压力测试

第3阶段：部署

灰度发布
全量发布
监控告警

第4阶段：优化

收集使用反馈
优化条码识别准确率
优化性能指标

✅ 最终确认清单

请确认以下所有项目，回复"确认无误，请开始实施"时自动开始：

✅ PDF渲染方案：GhostScript.NET
✅ 缓存流程：同步保存 + 异步条码
✅ 返回时机：立即返回，不等条码识别
✅ 并行处理：保存缓存和条码识别同时进行
✅ 主从同步：用户无需等待（后台自动）
✅ 新增字段：OriginalUrl 保存原始URL
✅ 条码失败：不影响已缓存的PDF
✅ 优先级：缓存可用性 > 条码识别准确性

📞 最终确认

您需要做的只有一件事：

在评审完方案 v2.0 文档后，回复：

"确认无误，请开始实施"

然后我将立即开始：

✅ 集成 GhostScript.NET
✅ 修改核心服务类
✅ 更新数据库结构
✅ 测试验收
✅ 提交完整代码

📄 方案文档位置：

d:\EPproject\LabelReplaceServer\.trae\plan\

├── SUMMARY.md                        (总体总结)
├── improved_caching_strategy.md      (v1.0初始方案)
├── existing_capabilities_analysis.md (能力分析)
├── implementation_checklist.md       (实施清单)
└── improved_strategy_v2_0.md         (👈 最新方案v2.0)

🎯 等待您的最终确认！ ✨

8.1 KiB Raw Permalink Blame History Unescape Escape