上传源代码版本
This commit is contained in:
Im-Jenisson
329
.trae/docs/BackgroundTasks/02-定时任务执行范围修改说明.md
Normal file
329
.trae/docs/BackgroundTasks/02-定时任务执行范围修改说明.md
Normal file
@@ -0,0 +1,329 @@
|
||||
# 定时任务执行范围修改说明
|
||||
|
||||
## 修改内容
|
||||
|
||||
### 修改目标
|
||||
将定时任务 `ProcessPendingTasksAsync()` 的执行范围限制为仅处理创建时间在 **2026-05-10** 之后的订单。
|
||||
|
||||
### 修改日期
|
||||
- **修改时间**: 2026-05-14
|
||||
- **截断日期**: 2026-05-10 00:00:00
|
||||
|
||||
---
|
||||
|
||||
## 涉及文件修改
|
||||
|
||||
### 1. LabelReplaceRepository.cs
|
||||
**文件路径**: `src/DAL/Repositories/LabelReplaceRepository.cs`
|
||||
|
||||
#### 修改的方法：
|
||||
|
||||
**1.1 GetNewOrdersWithLabelsAsync()**
|
||||
```csharp
|
||||
public async Task<List<string>> GetNewOrdersWithLabelsAsync(int limit)
|
||||
{
|
||||
var db = _provider.GetClient();
|
||||
// 定义截断日期：2026-05-10之后
|
||||
var cutoffDate = new DateTime(2026, 5, 10, 0, 0, 0);
|
||||
|
||||
return await db.Queryable<LabelReplaceEntity>()
|
||||
.Where(o => !string.IsNullOrEmpty(o.Label))
|
||||
.Where(o => o.CreatedAt >= cutoffDate) // 新增
|
||||
.Where(o => !SqlFunc.Subqueryable<LabelPdfCache>()
|
||||
.Where(c => c.NeutralWaybillNumber == o.NeutralWaybillNumber)
|
||||
.Any())
|
||||
.Select(o => o.NeutralWaybillNumber)
|
||||
.Take(limit)
|
||||
.ToListAsync();
|
||||
}
|
||||
```
|
||||
|
||||
**说明**:
|
||||
- 添加了 `cutoffDate` 变量定义截断日期
|
||||
- 添加了 `.Where(o => o.CreatedAt >= cutoffDate)` 条件过滤
|
||||
- 该方法是定时任务获取新订单的主要入口
|
||||
|
||||
**1.2 GetAllOrdersWithLabelsAsync()**
|
||||
```csharp
|
||||
public async Task<List<LabelReplaceEntity>> GetAllOrdersWithLabelsAsync(int limit = 1000)
|
||||
{
|
||||
var db = _provider.GetClient();
|
||||
var cutoffDate = new DateTime(2026, 5, 10, 0, 0, 0);
|
||||
|
||||
return await db.Queryable<LabelReplaceEntity>()
|
||||
.Where(lr => !string.IsNullOrEmpty(lr.Label))
|
||||
.Where(lr => lr.CreatedAt >= cutoffDate) // 新增
|
||||
.Take(limit)
|
||||
.ToListAsync();
|
||||
}
|
||||
```
|
||||
|
||||
**说明**:
|
||||
- 添加了创建时间过滤条件
|
||||
- 影响批量解析接口中 `mode=all` 的查询结果
|
||||
|
||||
**1.3 GetOrdersWithLabelsByDateRangeAsync()**
|
||||
```csharp
|
||||
public async Task<List<LabelReplaceEntity>> GetOrdersWithLabelsByDateRangeAsync(DateTime startDate, DateTime endDate, int limit = 1000)
|
||||
{
|
||||
var db = _provider.GetClient();
|
||||
var cutoffDate = new DateTime(2026, 5, 10, 0, 0, 0);
|
||||
|
||||
// 确保指定的日期范围不低于截断日期
|
||||
var finalStartDate = startDate < cutoffDate ? cutoffDate : startDate;
|
||||
|
||||
return await db.Queryable<LabelReplaceEntity>()
|
||||
.Where(lr => !string.IsNullOrEmpty(lr.Label)
|
||||
&& lr.CreatedAt >= finalStartDate // 修改
|
||||
&& lr.CreatedAt <= endDate)
|
||||
.Take(limit)
|
||||
.ToListAsync();
|
||||
}
|
||||
```
|
||||
|
||||
**说明**:
|
||||
- 添加了日期范围检查，确保开始日期不低于截断日期
|
||||
- 影响批量解析接口中 `mode=range` 的查询结果
|
||||
|
||||
**1.4 GetOrdersWithLabelsByCustomerAsync()**
|
||||
```csharp
|
||||
public async Task<List<LabelReplaceEntity>> GetOrdersWithLabelsByCustomerAsync(int customerId, int limit = 1000)
|
||||
{
|
||||
var db = _provider.GetClient();
|
||||
var cutoffDate = new DateTime(2026, 5, 10, 0, 0, 0);
|
||||
|
||||
return await db.Queryable<LabelReplaceEntity>()
|
||||
.Where(lr => !string.IsNullOrEmpty(lr.Label)
|
||||
&& lr.CustomerId == customerId
|
||||
&& lr.CreatedAt >= cutoffDate) // 新增
|
||||
.Take(limit)
|
||||
.ToListAsync();
|
||||
}
|
||||
```
|
||||
|
||||
**说明**:
|
||||
- 添加了创建时间过滤条件
|
||||
- 影响批量解析接口中 `mode=customer` 的查询结果
|
||||
|
||||
---
|
||||
|
||||
## 工作流程影响
|
||||
|
||||
### 定时任务处理流程
|
||||
|
||||
定时任务执行时流程如下：
|
||||
|
||||
```
|
||||
ProcessPendingTasksAsync()
|
||||
├─ GetInvalidCachesAsync()
|
||||
│ └─ 获取状态=3的无效缓存（结合订单表过滤）
|
||||
│
|
||||
├─ GetPendingTasksAsync()
|
||||
│ └─ 获取状态=0和状态=2的待处理缓存
|
||||
│
|
||||
└─ GetNewOrdersWithLabelsAsync() ← 新增时间过滤
|
||||
└─ 获取订单表中有标签但缓存表无记录的订单
|
||||
└─ 过滤条件: CreatedAt >= 2026-05-10
|
||||
```
|
||||
|
||||
### 受影响的查询
|
||||
|
||||
| 方法 | 影响 | 说明 |
|
||||
|------|------|------|
|
||||
| `GetNewOrdersWithLabelsAsync()` | ✅ 直接影响 | 定时任务的新订单获取方法 |
|
||||
| `GetAllOrdersWithLabelsAsync()` | ✅ 直接影响 | 批量解析 `mode=all` |
|
||||
| `GetOrdersWithLabelsByDateRangeAsync()` | ✅ 直接影响 | 批量解析 `mode=range` |
|
||||
| `GetOrdersWithLabelsByCustomerAsync()` | ✅ 直接影响 | 批量解析 `mode=customer` |
|
||||
|
||||
---
|
||||
|
||||
## API 行为变化
|
||||
|
||||
### 批量解析接口 (`/batch-parse`)
|
||||
|
||||
**修改前**: 可以处理2026-05-10之前的订单
|
||||
|
||||
**修改后**: 只能处理2026-05-10及以后的订单
|
||||
|
||||
| 模式 | 说明 | 变化 |
|
||||
|------|------|------|
|
||||
| `all` | 处理所有有标签的订单 | ✅ 只处理>=2026-05-10的订单 |
|
||||
| `range` | 按时间范围处理 | ✅ 开始日期自动调整至2026-05-10 |
|
||||
| `customer` | 按客户处理 | ✅ 只处理>=2026-05-10的订单 |
|
||||
| `single` | 单条订单处理 | ❌ 无变化（通过单号直接处理） |
|
||||
|
||||
### 示例
|
||||
|
||||
**请求 - 按时间范围处理**
|
||||
```json
|
||||
{
|
||||
"mode": "range",
|
||||
"startDate": "2026-05-01", // 实际从2026-05-10开始
|
||||
"endDate": "2026-05-15"
|
||||
}
|
||||
```
|
||||
|
||||
**说明**: startDate 会被自动调整为 2026-05-10，因为这是截断日期
|
||||
|
||||
---
|
||||
|
||||
## 定时任务行为
|
||||
|
||||
### 定时任务的新特性
|
||||
|
||||
1. **自动时间过滤** - 所有查询都将受到创建时间的限制
|
||||
2. **历史数据隔离** - 2026-05-10之前的订单不会被自动处理
|
||||
3. **手动处理支持** - 通过 `mode=single` 可以手动处理任何订单
|
||||
|
||||
### 执行间隔
|
||||
- **间隔**: 5分钟
|
||||
- **处理范围**: 仅2026-05-10及以后的订单
|
||||
- **批处理大小**: 100条（可配置）
|
||||
|
||||
---
|
||||
|
||||
## 配置参数
|
||||
|
||||
### 截断日期定义位置
|
||||
|
||||
所有截断日期都定义在数据访问层（Repository）中：
|
||||
|
||||
```csharp
|
||||
var cutoffDate = new DateTime(2026, 5, 10, 0, 0, 0);
|
||||
```
|
||||
|
||||
### 修改截断日期的方法
|
||||
|
||||
如需修改截断日期，只需更改上述时间值，例如改为2026-06-01：
|
||||
|
||||
```csharp
|
||||
var cutoffDate = new DateTime(2026, 6, 1, 0, 0, 0);
|
||||
```
|
||||
|
||||
然后重新编译和部署项目。
|
||||
|
||||
---
|
||||
|
||||
## 数据库影响
|
||||
|
||||
### 查询变化
|
||||
|
||||
**修改前SQL**:
|
||||
```sql
|
||||
SELECT o.NeutralWaybillNumber
|
||||
FROM label_replace o
|
||||
WHERE o.Label IS NOT NULL
|
||||
AND NOT EXISTS (
|
||||
SELECT 1 FROM label_pdf_cache c
|
||||
WHERE c.NeutralWaybillNumber = o.NeutralWaybillNumber
|
||||
)
|
||||
LIMIT 100;
|
||||
```
|
||||
|
||||
**修改后SQL**:
|
||||
```sql
|
||||
SELECT o.NeutralWaybillNumber
|
||||
FROM label_replace o
|
||||
WHERE o.Label IS NOT NULL
|
||||
AND o.CreatedAt >= '2026-05-10' -- 新增条件
|
||||
AND NOT EXISTS (
|
||||
SELECT 1 FROM label_pdf_cache c
|
||||
WHERE c.NeutralWaybillNumber = o.NeutralWaybillNumber
|
||||
)
|
||||
LIMIT 100;
|
||||
```
|
||||
|
||||
### 性能考虑
|
||||
|
||||
- 添加的 `CreatedAt >= cutoffDate` 条件可以利用现有的时间索引
|
||||
- 预期查询性能无负面影响
|
||||
- 可能会减少返回结果数量（因为过滤了旧数据）
|
||||
|
||||
---
|
||||
|
||||
## 兼容性
|
||||
|
||||
### 向后兼容性
|
||||
- ✅ 单条处理模式 (`mode=single`) 不受影响
|
||||
- ❌ 通过API手动处理时会受到时间限制
|
||||
|
||||
### 版本信息
|
||||
- **修改版本**: v2.1
|
||||
- **兼容版本**: v2.0（如需处理旧数据，需升级到v2.1后手动处理）
|
||||
|
||||
---
|
||||
|
||||
## 测试验证
|
||||
|
||||
### 编译验证
|
||||
✅ 整个项目已成功编译，无新的编译错误
|
||||
|
||||
### 功能验证清单
|
||||
|
||||
- [ ] 定时任务成功运行（每5分钟一次）
|
||||
- [ ] 只处理2026-05-10之后的订单
|
||||
- [ ] 2026-05-10之前的订单不被处理
|
||||
- [ ] 批量解析接口在 `mode=all` 时只返回新数据
|
||||
- [ ] 批量解析接口在 `mode=range` 时正确调整日期范围
|
||||
- [ ] 批量解析接口在 `mode=customer` 时只返回新客户订单
|
||||
- [ ] 缓存统计接口统计正确
|
||||
|
||||
### 手动测试命令
|
||||
|
||||
```bash
|
||||
# 测试批量解析 - all模式
|
||||
curl -X POST http://localhost:5002/api/label/batch-parse \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"mode":"all","limit":10}'
|
||||
|
||||
# 测试批量解析 - range模式（时间范围自动调整）
|
||||
curl -X POST http://localhost:5002/api/label/batch-parse \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"mode":"range","startDate":"2026-05-01","endDate":"2026-05-15","limit":10}'
|
||||
|
||||
# 测试定时任务状态
|
||||
curl -X GET http://localhost:5002/api/label/background-service/status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 回滚方案
|
||||
|
||||
如需恢复到修改前的行为，只需：
|
||||
|
||||
1. 移除所有的 `var cutoffDate = new DateTime(2026, 5, 10, 0, 0, 0);` 定义
|
||||
2. 移除所有的 `.Where(lr => lr.CreatedAt >= cutoffDate)` 条件
|
||||
3. 重新编译和部署
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 如何处理2026-05-10之前的订单？
|
||||
A: 使用 `mode=single` 通过单号进行手动处理：
|
||||
```json
|
||||
{"mode":"single","waybillNumber":"1Z999AA10123456784"}
|
||||
```
|
||||
|
||||
### Q: 定时任务会处理旧订单吗？
|
||||
A: 不会。定时任务 (`GetNewOrdersWithLabelsAsync`) 已被限制为仅处理2026-05-10及以后的订单。
|
||||
|
||||
### Q: 缓存统计会包含旧数据吗？
|
||||
A: 是的。`cache-statistics` 接口统计的是缓存表中的所有数据，不受时间限制。
|
||||
|
||||
### Q: 如何修改截断日期？
|
||||
A: 修改所有Repository中的 `new DateTime(2026, 5, 10, 0, 0, 0)` 为新的日期，然后重新编译部署。
|
||||
|
||||
---
|
||||
|
||||
## 相关文件
|
||||
|
||||
- **修改的数据库访问类**: `src/DAL/Repositories/LabelReplaceRepository.cs`
|
||||
- **定时任务类**: `src/BLL/Services/LabelPdfCacheService.cs`
|
||||
- **批量解析接口**: `src/CONTROLLER/Controllers/LabelController.cs`
|
||||
|
||||
---
|
||||
|
||||
**修改完成于**: 2026-05-14
|
||||
**编译状态**: ✅ 成功
|
||||
**部署状态**: 等待确认
|
||||
Reference in New Issue
Block a user