jennisonzhang/LabelChange-server

Fork 0

Files

Im-Jenisson b2a9b7d3c2 上传源代码版本

2026-06-01 16:30:29 +08:00

7.2 KiB

Raw Permalink Blame History

定时任务文档索引

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

📚 文档清单

1. 核心文档

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

2. 操作指南

暂停与恢复定时任务

参考：定时任务暂停指南

3种方法：

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

定时任务的执行时间限制

参考：定时任务与API隔离修改

关键点：

定时任务：仅处理 >= 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行)

private const int TaskIntervalMinutes = 5;

批处理大小

文件: src/BLL/Services/LabelPdfCacheService.cs (ProcessPendingTasksAsync方法参数)

public async Task<int> ProcessPendingTasksAsync(int maxRetryCount = 3, int batchSize = 100)

时间截断日期

文件: src/DAL/Repositories/LabelPdfCacheRepository.cs

var cutoffDate = new DateTime(2026, 5, 10, 0, 0, 0);

🚀 常用操作

查看定时任务状态

curl -X GET http://localhost:5002/api/label/background-service/status

暂停定时任务

curl -X POST http://localhost:5002/api/label/background-service/pause

恢复定时任务

curl -X POST http://localhost:5002/api/label/background-service/resume

手动触发批量解析

# 处理所有订单（无时间限制）
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"}'

📊 监控指标

缓存统计信息

curl -X GET http://localhost:5002/api/label/cache-statistics

返回字段:

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

🔧 故障排查

定时任务不执行

可能原因:

服务未启动
定时任务已暂停
数据库连接失败

解决方案:

# 检查状态
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

定时任务处理缓慢

可能原因:

待处理任务过多
网络延迟
PDF渲染时间过长

解决方案:

# 查看缓存统计
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}'

新订单未被处理

检查清单:

✅ 订单是否在 >= 2026-05-10 之后创建
✅ 订单是否有标签数据
✅ 定时任务是否正在运行
✅ 缓存表中是否已有该订单的记录

手动处理:

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隔离修改
2026-05-14	添加定时任务暂停/恢复功能	定时任务暂停指南
2026-05-14	限制定时任务仅处理2026-05-10之后订单	定时任务执行范围修改说明
2026-05-13	优化定时任务执行范围	Background Task Scope Improvement

❓ 常见问题

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
维护者: 开发团队
状态: ✅ 完整

7.2 KiB Raw Permalink Blame History Unescape Escape