上传源代码版本
This commit is contained in:
Im-Jenisson
285
.trae/plan/v2_0_FINAL_CONFIRMATION.md
Normal file
285
.trae/plan/v2_0_FINAL_CONFIRMATION.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# 📊 方案 v2.0 - 最终确认总结
|
||||
|
||||
**创建时间**: 2026-05-13
|
||||
**状态**: ✅ 等待最终确认开始实施
|
||||
|
||||
---
|
||||
|
||||
## 🎯 用户需求回顾
|
||||
|
||||
### 您的核心需求
|
||||
1. ✅ **充分利用现有PDF转字节流能力**
|
||||
- 已分析并确认可完全复用现有HttpClientFactory下载逻辑
|
||||
|
||||
2. ✅ **验证通过即缓存**
|
||||
- 设计分离的保存流程，不依赖条码识别结果
|
||||
|
||||
3. ✅ **不管条码识别成功与否，都要缓存**
|
||||
- 条码识别完全异步，失败不影响已保存的PDF
|
||||
|
||||
4. 💡 **主从库同步问题** （新反馈）
|
||||
- 原方案：保存后等待从库同步再返回用户 ❌
|
||||
- v2.0方案：立即返回，同步进行保存和条码识别 ✅
|
||||
|
||||
5. 🆕 **保存原始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
|
||||
|
||||
```sql
|
||||
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阶段：优化
|
||||
- [ ] 收集使用反馈
|
||||
- [ ] 优化条码识别准确率
|
||||
- [ ] 优化性能指标
|
||||
|
||||
---
|
||||
|
||||
## ✅ 最终确认清单
|
||||
|
||||
**请确认以下所有项目，回复"确认无误，请开始实施"时自动开始**：
|
||||
|
||||
- [x] ✅ PDF渲染方案：**GhostScript.NET**
|
||||
- [x] ✅ 缓存流程：**同步保存 + 异步条码**
|
||||
- [x] ✅ 返回时机：**立即返回，不等条码识别**
|
||||
- [x] ✅ 并行处理：**保存缓存和条码识别同时进行**
|
||||
- [x] ✅ 主从同步：**用户无需等待（后台自动）**
|
||||
- [x] ✅ 新增字段：**OriginalUrl 保存原始URL**
|
||||
- [x] ✅ 条码失败：**不影响已缓存的PDF**
|
||||
- [x] ✅ 优先级：**缓存可用性 > 条码识别准确性**
|
||||
|
||||
---
|
||||
|
||||
## 📞 最终确认
|
||||
|
||||
**您需要做的只有一件事**：
|
||||
|
||||
在评审完方案 v2.0 文档后，回复：
|
||||
|
||||
> **"确认无误，请开始实施"**
|
||||
|
||||
然后我将立即开始：
|
||||
1. ✅ 集成 GhostScript.NET
|
||||
2. ✅ 修改核心服务类
|
||||
3. ✅ 更新数据库结构
|
||||
4. ✅ 测试验收
|
||||
5. ✅ 提交完整代码
|
||||
|
||||
---
|
||||
|
||||
**📄 方案文档位置**：
|
||||
|
||||
```
|
||||
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)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**🎯 等待您的最终确认！** ✨
|
||||
Reference in New Issue
Block a user