# 定时任务文档索引

本文件夹包含所有与 **PDF标签缓存定时任务** 相关的文档说明。

## 📚 文档清单

### 1. 核心文档

| 文档 | 说明 | 最后更新 |
|------|------|---------|
| [定时任务暂停指南](定时任务暂停指南.md) | 如何暂停、恢复定时任务，以及API接口管理 | 2026-05-14 |
| [定时任务执行范围修改说明](定时任务执行范围修改说明_2026-05-14.md) | 限制定时任务仅处理2026-05-10之后订单的修改 | 2026-05-14 |
| [定时任务与API隔离修改](定时任务与API隔离修改_2026-05-14.md) | 时间限制条件仅应用于定时任务，batch-parse接口无限制 | 2026-05-14 |
| [Background Task Scope Improvement](Background_Task_Scope_Improvement.md) | 定时任务执行范围优化总结 | 2026-05-13 |

### 2. 操作指南

#### 暂停与恢复定时任务

参考：[定时任务暂停指南](定时任务暂停指南.md)

**3种方法**：
- 方法1：配置文件方式（生产环保境）
- 方法2：环境变量方式（Docker）
- 方法3：API接口方式（最灵活）

#### 定时任务的执行时间限制

参考：[定时任务与API隔离修改](定时任务与API隔离修改_2026-05-14.md)

**关键点**：
- 定时任务：仅处理 >= 2026-05-10 的新订单
- batch-parse 接口：处理所有订单，无时间限制
- 两者完全隔离，互不影响

### 3. 相关配置

#### 定时任务类
- **位置**: `src/CONTROLLER/BackgroundServices/LabelPdfCacheBackgroundService.cs`
- **执行间隔**: 5分钟
- **主要方法**: `ExecuteAsync()` 和 `ProcessPendingTasksAsync()`

#### 后台服务管理器
- **位置**: `src/CONTROLLER/BackgroundServices/BackgroundServiceManager.cs`
- **用途**: 提供暂停/恢复定时任务的功能

#### 缓存服务
- **位置**: `src/BLL/Services/LabelPdfCacheService.cs`
- **主要方法**: `ProcessPendingTasksAsync()`, `ProcessSingleCacheTaskAsync()`

---

## 🔄 定时任务工作流程

```
定时任务 (每5分钟)
    │
    ├─ 第一步：处理失效缓存
    │  └─ 获取 Status=3 的缓存记录
    │  └─ 重新处理这些订单
    │
    ├─ 第二步：处理待处理任务
    │  └─ 获取 Status=0 或 Status=2 的缓存记录
    │  └─ 尝试重新处理
    │
    └─ 第三步：处理新订单 ⭐ 时间限制在此
       └─ 获取订单表中有标签但缓存表无记录的订单
       └─ 仅处理创建时间 >= 2026-05-10 的订单
       └─ 创建新的缓存记录
```

---

## ⚙️ 配置参数

### 定时任务执行间隔
**文件**: `src/CONTROLLER/BackgroundServices/LabelPdfCacheBackgroundService.cs` (第18行)
```csharp
private const int TaskIntervalMinutes = 5;
```

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

### 时间截断日期
**文件**: `src/DAL/Repositories/LabelPdfCacheRepository.cs`
```csharp
var cutoffDate = new DateTime(2026, 5, 10, 0, 0, 0);
```

---

## 🚀 常用操作

### 查看定时任务状态
```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 POST http://localhost:5002/api/label/batch-parse \
  -H "Content-Type: application/json" \
  -d '{"mode":"all","limit":500}'

# 处理单个订单（包括旧订单）
curl -X POST http://localhost:5002/api/label/batch-parse \
  -H "Content-Type: application/json" \
  -d '{"mode":"single","waybillNumber":"ORDER_NUMBER"}'
```

---

## 📊 监控指标

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

**返回字段**:
- `totalRecords` - 总缓存记录数
- `successRecords` - 成功处理的记录
- `failedRecords` - 失败的记录
- `invalidRecords` - 无效的记录
- `pendingRecords` - 待处理的记录
- `withBarcodeRecords` - 包含条码的记录
- `averageParseDurationMs` - 平均解析时间
- `maxParseDurationMs` - 最大解析时间
- `minParseDurationMs` - 最小解析时间

---

## 🔧 故障排查

### 定时任务不执行

**可能原因**:
1. 服务未启动
2. 定时任务已暂停
3. 数据库连接失败

**解决方案**:
```bash
# 检查状态
curl -X GET http://localhost:5002/api/label/background-service/status

# 如果已暂停，恢复它
curl -X POST http://localhost:5002/api/label/background-service/resume

# 查看日志
tail -f logs/development_api_log-*.txt
```

### 定时任务处理缓慢

**可能原因**:
1. 待处理任务过多
2. 网络延迟
3. PDF渲染时间过长

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

# 手动处理部分任务
curl -X POST http://localhost:5002/api/label/batch-parse \
  -H "Content-Type: application/json" \
  -d '{"mode":"all","limit":100}'
```

### 新订单未被处理

**检查清单**:
1. ✅ 订单是否在 >= 2026-05-10 之后创建
2. ✅ 订单是否有标签数据
3. ✅ 定时任务是否正在运行
4. ✅ 缓存表中是否已有该订单的记录

**手动处理**:
```bash
curl -X POST http://localhost:5002/api/label/batch-parse \
  -H "Content-Type: application/json" \
  -d '{"mode":"single","waybillNumber":"WAYBILL_NUMBER"}'
```

---

## 📝 修改历史

| 日期 | 修改内容 | 文档 |
|------|--------|------|
| 2026-05-14 | 隔离定时任务和API的时间限制条件 | [定时任务与API隔离修改](定时任务与API隔离修改_2026-05-14.md) |
| 2026-05-14 | 添加定时任务暂停/恢复功能 | [定时任务暂停指南](定时任务暂停指南.md) |
| 2026-05-14 | 限制定时任务仅处理2026-05-10之后订单 | [定时任务执行范围修改说明](定时任务执行范围修改说明_2026-05-14.md) |
| 2026-05-13 | 优化定时任务执行范围 | [Background Task Scope Improvement](Background_Task_Scope_Improvement.md) |

---

## ❓ 常见问题

### Q: 定时任务多久执行一次？
A: 每5分钟执行一次。可以在 `LabelPdfCacheBackgroundService.cs` 中修改 `TaskIntervalMinutes` 常量来改变执行频率。

### Q: 如何手动处理2026-05-10之前的订单？
A: 使用 `mode=single` 通过 batch-parse 接口手动处理单个订单，该模式不受时间限制。

### Q: 定时任务会处理失败的订单吗？
A: 会的。定时任务会重试失败的订单，最多重试3次（可配置）。

### Q: 能否改变定时任务的执行时间？
A: 可以。修改 `LabelPdfCacheBackgroundService.cs` 中的 `TaskIntervalMinutes` 常量。

### Q: 暂停定时任务后，待处理的任务会丢失吗？
A: 不会。暂停只是停止周期性执行，待处理的任务会保留在数据库中，恢复后继续处理。

---

## 🔗 相关资源

- **API文档**: 根目录下的 `API_Documentation_zh.md`
- **完整系统流程**: 根目录下的 `SystemFlowDocument.md`
- **项目README**: 根目录下的 `README.md`

---

**最后更新**: 2026-05-14  
**维护者**: 开发团队  
**状态**: ✅ 完整