# 面单PDF字节流缓存方案规划

## 一、需求与现有逻辑评估

### 现有逻辑分析

1. **下载接口**：`LabelController.DownloadLabelByWaybillNumber` 实时根据中性面单号获取标签数据，若为URL则实时下载，校验PDF页数后返回字节流，存在网络开销和超时风险。
2. **下单接口**：`TagController.LabelReplace` 生成标签替换记录，存储到订单表（`LabelReplaceEntity`对应表），`Label`字段存储URL或base64编码内容。

### 核心需求目标

* 减少URL实时下载的网络开销

* 提前校验面单问题（页数超限、无数据等）

* 实现下载重试机制，避免超时

* 不影响原有换单流程，无缓存时降级使用原URL访问

## 二、数据库表设计

### 表名：`LabelPdfCache`

| 字段名                  | 类型                        | 说明                             |
| -------------------- | ------------------------- | ------------------------------ |
| Id                   | bigint                    | 主键，自增                          |
| NeutralWaybillNumber | varchar(50)               | 中性面单号，唯一索引                     |
| PdfBytes             | longblob / varbinary(max) | PDF二进制字节流                      |
| PageCount            | int                       | PDF实际页数                        |
| FileSize             | int                       | 文件大小（字节）                       |
| Status               | tinyint                   | 缓存状态：0=待处理，1=处理成功，2=处理失败，3=已失效 |
| RetryCount           | int                       | 已重试次数，默认0                      |
| LastRetryTime        | datetime                  | 最后重试时间                         |
| ErrorMessage         | varchar(500)              | 处理失败错误信息                       |
| CreatedTime          | datetime                  | 创建时间                           |
| UpdatedTime          | datetime                  | 更新时间                           |

### 索引设计

* 唯一索引：`IX_NeutralWaybillNumber`（中性面单号，用于快速查询）

* 普通索引：`IX_Status_RetryCount`（状态+重试次数，用于定时任务扫描）

## 三、定时任务实现方案

### 任务执行逻辑

1. **扫描条件**：每次扫描订单表中满足以下条件的记录：

   * `Label`字段不为空

   * 未在`LabelPdfCache`表中存在，或`LabelPdfCache`中状态为失败且重试次数<3
2. **处理流程**：

   ```mermaid
   graph LR
   A[扫描待处理订单] --> B{是否有缓存记录}
   B -->|无| C[新建缓存记录状态=待处理]
   B -->|有失败记录| D[更新重试次数+1，状态=待处理]
   C --> E[下载/解析Label内容]
   D --> E
   E --> F{解析成功?}
   F -->|是| G[校验PDF页数≤1，大小正常]
   F -->|否| H[更新状态=失败，记录错误信息]
   G -->|校验通过| I[保存字节流，状态=成功]
   G -->|校验失败| J[更新状态=失败，记录校验错误]
   ```

### 任务配置

* 执行频率：建议每5分钟执行一次，可配置

* 单次处理数量：每次最多处理100条，避免占用过多资源

* 重试间隔：失败后至少间隔10分钟再重试

## 四、接口逻辑改造

### 1. 下载接口优化（LabelController）

原有逻辑保持不变，新增缓存查询逻辑：

```csharp
// 新增：先查询缓存
var cache = await _labelPdfCacheService.GetValidCacheAsync(waybillNumber);
if (cache != null && cache.Status == 1)
{
    _logger.LogInformation("Hit PDF cache for waybill: {number}", waybillNumber);
    scanResult = ScanResult.ReturnedLabel;
    scanDescription = "命中缓存返回标签";
    return File(cache.PdfBytes, "application/pdf", $"label_{waybillNumber}.pdf");
}
// 未命中缓存，走原有逻辑
// ... 原有下载/解析逻辑 ...
// 新增：解析成功后异步写入缓存
_ = Task.Run(async () => 
{
    try
    {
        await _labelPdfCacheService.SaveCacheAsync(waybillNumber, labelBytes, pageCount, labelBytes.Length);
    }
    catch (Exception ex)
    {
        _logger.LogWarning(ex, "Save cache failed for waybill: {number}", waybillNumber);
    }
});
```

### 2. 换单接口兼容（TagController）

无需改造原有逻辑，当调用`_labelReplaceService.ProcessLabelReplaceAsync`时，若需要返回字节流：

* 先查询缓存，存在则直接使用

* 不存在则走原有URL访问逻辑

## 五、重试机制设计

### 重试规则

1. 默认最大重试次数：3次
2. 重试触发条件：

   * 网络请求超时

   * HTTP请求错误（5xx、429等可重试错误）

   * 临时IO异常
3. 不重试条件：

   * PDF页数超过1页（校验不通过，无需重试）

   * 标签数据格式错误（base64解析失败）

   * 4xx错误（404、403等客户端错误）

### 退避策略

* 第1次失败：间隔10分钟重试

* 第2次失败：间隔30分钟重试

* 第3次失败：标记为最终失败，不再重试

## 六、异常处理与降级策略
1. **缓存服务异常**：缓存服务不可用时，直接降级走原有实时下载逻辑，不影响主流程
2. **定时任务异常**：定时任务执行失败不影响正常接口调用，仅预缓存功能暂时失效
3. **缓存失效策略**：
   - **触发时机**：当订单的`Label`字段更新时（如换单服务更新标签URL、重新生成标签等场景），同步调用`_labelPdfCacheService.InvalidateCacheAsync(waybillNumber)`将对应缓存标记为失效状态（Status=3）
   - **失效后处理**：
     1. 被标记为失效的缓存不会在下载接口中被返回
     2. 定时任务扫描时会优先处理状态为已失效的记录，重置重试次数为0，重新下载解析新的Label内容
     3. 失效缓存的字节流会保留24小时后自动清理，方便问题排查
   - **兜底校验**：下载接口查询缓存时，会额外校验订单表的`Label`更新时间与缓存更新时间，若缓存更新时间早于Label更新时间，自动忽略缓存走实时下载逻辑，同时异步触发缓存更新，避免标记失效遗漏导致返回旧数据
4. 确保系统稳定: 定时任务的启动和执行不能影响整个程序.

## 七、实施步骤

1. 新增`LabelPdfCache`实体类和数据库迁移脚本
2. 实现`LabelPdfCacheService`缓存操作服务
3. 实现定时任务服务（基于Hangfire或现有定时任务框架）
4. 改造`DownloadLabelByWaybillNumber`接口增加缓存逻辑
5. 适配换单服务的缓存查询逻辑
6. 测试验证功能正确性和性能提升效果