上传源代码版本
This commit is contained in:
Im-Jenisson
244
.trae/docs/BackgroundTasks/00-README.md
Normal file
244
.trae/docs/BackgroundTasks/00-README.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# 定时任务文档索引
|
||||
|
||||
本文件夹包含所有与 **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
|
||||
**维护者**: 开发团队
|
||||
**状态**: ✅ 完整
|
||||
Reference in New Issue
Block a user