上传源代码版本

.trae/docs/BackgroundTasks/05-快速参考.md

@@ -0,0 +1,126 @@
+# 定时任务快速参考
+
+## 📌 核心信息
+
+| 项目 | 内容 |
+|------|------|
+| **服务类** | `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