# 定时任务快速参考

## 📌 核心信息

| 项目 | 内容 |
|------|------|
| **服务类** | `LabelPdfCacheBackgroundService` |
| **执行间隔** | 每5分钟 |
| **处理范围** | 失效缓存、待处理任务、新订单 |
| **时间限制** | 新订单仅处理 >= 2026-05-10 |

---

## 🚀 常用命令

### 查看状态
```bash
curl -X GET http://localhost:5002/api/label/background-service/status
```

### 暂停任务
```bash
curl -X POST http://localhost:5002/api/label/background-service/pause
```

### 恢复任务
```bash
curl -X POST http://localhost:5002/api/label/background-service/resume
```

### 查看缓存统计
```bash
curl -X GET http://localhost:5002/api/label/cache-statistics
```

---

## 📂 文件位置

| 文件 | 路径 |
|------|------|
| **服务主类** | `src/CONTROLLER/BackgroundServices/LabelPdfCacheBackgroundService.cs` |
| **服务管理器** | `src/CONTROLLER/BackgroundServices/BackgroundServiceManager.cs` |
| **业务逻辑** | `src/BLL/Services/LabelPdfCacheService.cs` |
| **数据访问** | `src/DAL/Repositories/LabelPdfCacheRepository.cs` |

---

## ⏱️ 配置参数

### 执行间隔
**文件**: `LabelPdfCacheBackgroundService.cs` 第18行
```csharp
private const int TaskIntervalMinutes = 5;
```
改为所需的分钟数

### 批处理大小
**文件**: `LabelPdfCacheService.cs` ProcessPendingTasksAsync方法
```csharp
public async Task<int> ProcessPendingTasksAsync(int maxRetryCount = 3, int batchSize = 100)
```
调整 `batchSize` 参数

### 时间限制日期
**文件**: `LabelPdfCacheRepository.cs` GetNewOrdersWithLabelsForBackgroundTaskAsync方法
```csharp
var cutoffDate = new DateTime(2026, 5, 10, 0, 0, 0);
```
改为所需的日期

---

## 🔄 工作流程

```
每5分钟执行一次:
    ├─ 处理失效缓存 (Status=3)
    ├─ 处理待处理任务 (Status=0 或 Status=2)
    └─ 处理新订单 (>= 2026-05-10 的有标签订单)
```

---

## ✅ 检查清单

- [ ] 定时任务是否正在运行？ → 查看状态
- [ ] 是否有待处理任务堆积？ → 查看缓存统计
- [ ] 新订单是否被自动处理？ → 检查创建时间是否 >= 2026-05-10
- [ ] 定时任务是否遇到错误？ → 查看日志文件

---

## 🆘 快速故障排查

| 问题 | 解决方案 |
|------|---------|
| 定时任务不执行 | 检查是否暂停，查看日志 |
| 新订单未被处理 | 检查创建时间，检查是否有标签 |
| 任务堆积 | 调整批处理大小或手动处理 |
| 错误重复发生 | 暂停任务，调查问题，恢复 |

---

## 📊 关键指标

从 `/api/label/cache-statistics` 获取：

- **totalRecords**: 总缓存数
- **successRecords**: 成功数
- **failedRecords**: 失败数
- **pendingRecords**: 待处理数
- **averageParseDurationMs**: 平均耗时
- **withBarcodeRecords**: 含条码数

---

## 🔗 相关文档

1. [定时任务暂停指南](01-定时任务暂停指南.md) - 如何控制定时任务
2. [执行范围修改说明](02-定时任务执行范围修改说明.md) - 时间限制详解
3. [定时任务与API隔离](03-定时任务与API隔离修改.md) - API与定时任务的区别

---

**最后更新**: 2026-05-14