# 定时任务与批量解析接口隔离修改

## 修改概述

根据用户需求，将 **2026-05-10 之后的订单** 这个时间限制条件改为**仅应用于定时任务**，而 **batch-parse 接口不受此限制**。

这样实现了两个不同的数据查询范围：
- **定时任务** (`ProcessPendingTasksAsync`) - 仅处理 >= 2026-05-10 的订单
- **batch-parse 接口** - 处理**所有**订单，无时间限制

---

## 修改详情

### 1. 新增方法

为了实现隔离，在两个 Repository 中都添加了**新的专用方法**：

#### ILabelReplaceRepository 接口
```csharp
/// <summary>
/// 获取定时任务新订单（仅2026-05-10之后的订单）
/// </summary>
Task<List<string>> GetNewOrdersWithLabelsForBackgroundTaskAsync(int limit);
```

#### ILabelPdfCacheRepository 接口
```csharp
/// <summary>
/// 获取定时任务新订单（仅2026-05-10之后的订单）
/// </summary>
Task<List<string>> GetNewOrdersWithLabelsForBackgroundTaskAsync(int limit);
```

### 2. 原有方法恢复

以下方法已恢复为**无时间限制**的原始实现：

| 方法名 | 位置 | 修改 |
|--------|------|------|
| `GetNewOrdersWithLabelsAsync()` | LabelPdfCacheRepository | ✅ 移除时间过滤，恢复原始 |
| `GetAllOrdersWithLabelsAsync()` | LabelReplaceRepository | ✅ 移除时间过滤，恢复原始 |
| `GetOrdersWithLabelsByDateRangeAsync()` | LabelReplaceRepository | ✅ 移除时间过滤，恢复原始 |
| `GetOrdersWithLabelsByCustomerAsync()` | LabelReplaceRepository | ✅ 移除时间过滤，恢复原始 |

### 3. 定时任务调用修改

在 `LabelPdfCacheService.cs` 的 `ProcessPendingTasksAsync()` 方法中：

**修改前**:
```csharp
var newOrders = await _cacheRepository.GetNewOrdersWithLabelsAsync(newBatchSize);
```

**修改后**:
```csharp
// 仅处理创建时间>=2026-05-10的订单
var newOrders = await _cacheRepository.GetNewOrdersWithLabelsForBackgroundTaskAsync(newBatchSize);
```

---

## 工作流程对比

### batch-parse 接口行为

| 模式 | 支持范围 | 说明 |
|------|--------|------|
| `all` | **所有订单** | ✅ 不受时间限制 |
| `range` | **指定范围** | ✅ 按用户指定的日期范围处理 |
| `customer` | **指定客户订单** | ✅ 不受时间限制 |
| `single` | **单条订单** | ✅ 不受任何限制 |

### 定时任务行为

```
定时任务 (每5分钟)
    ├─ GetInvalidCachesAsync()
    │  └─ 处理所有状态=3的无效缓存（无时间限制）
    ├─ GetPendingTasksAsync()
    │  └─ 处理所有待处理缓存（无时间限制）
    └─ GetNewOrdersWithLabelsForBackgroundTaskAsync() ← 【新增：仅>=2026-05-10】
       └─ 只处理创建时间>=2026-05-10的新订单
```

---

## 使用场景

### 场景1：使用批量解析处理历史订单

```bash
# 处理所有订单（包括2026-05-10之前的）
curl -X POST http://localhost:5002/api/label/batch-parse \
  -H "Content-Type: application/json" \
  -d '{"mode":"all","limit":500}'
```

✅ **可以成功** - 返回所有有标签的订单

### 场景2：定时任务自动处理

定时任务每5分钟自动执行，会：
- ✅ 处理所有失效缓存
- ✅ 处理所有待处理缓存
- ✅ **仅处理**创建时间 >= 2026-05-10 的新订单

---

## 涉及文件修改

| 文件 | 修改内容 |
|------|---------|
| `src/DAL/Interfaces/ILabelReplaceRepository.cs` | 新增 `GetNewOrdersWithLabelsForBackgroundTaskAsync()` |
| `src/DAL/Repositories/LabelReplaceRepository.cs` | 实现新方法，恢复旧方法 |
| `src/DAL/Interfaces/ILabelPdfCacheRepository.cs` | 新增 `GetNewOrdersWithLabelsForBackgroundTaskAsync()` |
| `src/DAL/Repositories/LabelPdfCacheRepository.cs` | 实现新方法，恢复旧方法 |
| `src/BLL/Services/LabelPdfCacheService.cs` | 调用新方法 |

---

## 编译验证

✅ **编译成功** - 整个项目编译无错误

---

## 方法汇总

### 查询范围明细

| 方法 | 作用 | 时间限制 | 使用场景 |
|------|------|---------|---------|
| `GetAllOrdersWithLabelsAsync()` | 查询所有有标签订单 | ❌ 无 | batch-parse mode=all |
| `GetOrdersWithLabelsByDateRangeAsync()` | 按日期范围查询 | ❌ 无 | batch-parse mode=range |
| `GetOrdersWithLabelsByCustomerAsync()` | 按客户查询 | ❌ 无 | batch-parse mode=customer |
| `GetNewOrdersWithLabelsAsync()` | 查询新订单 | ❌ 无 | batch-parse 补充查询 |
| `GetNewOrdersWithLabelsForBackgroundTaskAsync()` | 查询定时任务新订单 | ✅ >= 2026-05-10 | 定时任务专用 |

---

## 回滚方案

如需恢复到之前的行为（定时任务和API都受时间限制），只需：

1. 将 `ProcessPendingTasksAsync()` 中的调用改回：
```csharp
var newOrders = await _cacheRepository.GetNewOrdersWithLabelsAsync(newBatchSize);
```

2. 为通用方法添加时间限制条件

3. 移除专用的 `GetNewOrdersWithLabelsForBackgroundTaskAsync()` 方法

---

## 常见问题

### Q: 使用batch-parse接口处理2026-05-10之前的订单，会成功吗？
A: **是的，会成功**。现在batch-parse接口不受时间限制，可以处理任何时间的订单。

### Q: 定时任务会处理2026-05-10之前的新订单吗？
A: **不会**。定时任务仅处理 >= 2026-05-10 的新订单。如需处理旧订单，请使用 `mode=single` 手动处理。

### Q: 如何手动处理单个旧订单？
A: 使用 `mode=single` 模式：
```bash
curl -X POST http://localhost:5002/api/label/batch-parse \
  -H "Content-Type: application/json" \
  -d '{"mode":"single","waybillNumber":"OLD_WAYBILL_NUMBER"}'
```

### Q: 时间限制条件会影响定时任务的其他步骤吗？
A: **不会**。时间限制仅应用于获取新订单的步骤，不影响处理失效缓存和待处理任务的步骤。

---

## 测试验证清单

- [ ] 编译成功且无错误
- [ ] 使用 `mode=all` 查询到2026-05-10之前的订单
- [ ] 使用 `mode=range` 查询到指定日期范围的所有订单
- [ ] 使用 `mode=customer` 查询到该客户的所有订单（含旧订单）
- [ ] 定时任务仅处理>=2026-05-10的新订单
- [ ] 定时任务正常处理失效缓存（无时间限制）
- [ ] 定时任务正常处理待处理缓存（无时间限制）
- [ ] 缓存统计接口统计正确

---

**修改完成于**: 2026-05-14  
**编译状态**: ✅ 成功  
**部署状态**: 等待确认