245 lines
7.2 KiB
Markdown
245 lines
7.2 KiB
Markdown
# 定时任务文档索引
|
||
|
||
本文件夹包含所有与 **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
|
||
**维护者**: 开发团队
|
||
**状态**: ✅ 完整
|