LabelChange-server/.trae/docs/BackgroundTasks/07-定时任务管理模块待办清单.md

定时任务管理模块 - 项目待办清单

📋 项目概述

项目名称: PDF标签缓存定时任务管理模块
优先级: 高
目标: 建立完整的定时任务管理系统，包括任务执行、监控、告警和控制面板
预期周期: 中期（4-6周）

---

🎯 核心目标

• ✅ 完整的定时任务管理API
• ✅ 后台任务执行监控
• ✅ 定时任务配置管理
• ✅ 任务执行日志和审计
• ✅ 告警和异常处理
• ✅ 管理后台Dashboard

---

📋 需求分析

当前系统现状

• ✅ 已实现:

  • LabelPdfCacheBackgroundService - 后台服务主类
  • ProcessPendingTasksAsync() - 核心处理方法
  • 基本的5分钟定时执行
  • 三步处理流程（失效缓存、待处理任务、新订单）
  • 时间限制条件（>=2026-05-10）
  • 基本的暂停/恢复功能（BackgroundServiceManager）

• ⚠️ 部分实现:

  • 暂停/恢复API接口（需要完整实现在LabelController）
  • 基本的状态查询（需要增强）

• ❌ 未实现:

  • 定时任务配置管理界面
  • 详细的执行日志记录
  • 任务执行历史查询
  • 告警和通知机制
  • 性能监控和分析
  • 错误重试策略可视化
  • 定时任务管理Dashboard
  • 任务调度的可视化配置

---

🔨 任务分解

阶段1: API层完善 (优先级: ⭐⭐⭐)

1.1 完整的控制接口

• Task: 在LabelController中完整实现暂停/恢复API
  • POST /api/label/background-service/pause - 暂停定时任务
  • POST /api/label/background-service/resume - 恢复定时任务
  • GET /api/label/background-service/status - 获取定时任务状态
  • 返回详细的状态信息（运行状态、最后执行时间、下次执行时间等）
  • 预计工作量: 2小时
  • 相关文件: src/CONTROLLER/Controllers/LabelController.cs

1.2 配置管理接口

• Task: 创建定时任务配置管理API
  • GET /api/label/background-service/config - 获取当前配置
  • POST /api/label/background-service/config - 更新配置
  • 支持配置项:
    • 执行间隔（分钟）
    • 批处理大小
    • 重试次数
    • 时间限制日期
    • 是否启用
  • 预计工作量: 4小时
  • 相关文件:
    • src/CONTROLLER/Controllers/LabelController.cs
    • src/BLL/Services/LabelPdfCacheService.cs

1.3 日志查询接口

• Task: 实现执行日志查询API
  • GET /api/label/background-service/logs - 查询执行日志
  • 支持筛选条件:
    • 日期范围
    • 执行状态（成功/失败）
    • 关键词搜索
  • 分页支持
  • 预计工作量: 3小时
  • 相关文件:
    • src/CONTROLLER/Controllers/LabelController.cs
    • src/DAL/Repositories/LabelPdfCacheRepository.cs

阶段2: 数据存储层 (优先级: ⭐⭐⭐)

2.1 创建定时任务日志表

• Task: 设计和创建 background_task_logs 表
  • 表结构:

    CREATE TABLE background_task_logs (
        id BIGINT PRIMARY KEY AUTO_INCREMENT,
        task_name VARCHAR(100),          -- 任务名称
        execution_time DATETIME,          -- 执行时间
        status TINYINT,                   -- 状态: 0=进行中, 1=成功, 2=失败
        processed_count INT,              -- 处理数量
        success_count INT,                -- 成功数
        error_count INT,                  -- 错误数
        duration_ms INT,                  -- 执行耗时(毫秒)
        error_message TEXT,               -- 错误信息
        created_at DATETIME,
        updated_at DATETIME,
        INDEX idx_execution_time (execution_time),
        INDEX idx_status (status)
    )
    

  • 预计工作量: 1小时
  • 相关文件: src/DB/Scripts/CreateBackgroundTaskLogsTable.sql

2.2 创建定时任务配置表

• Task: 设计和创建 background_task_config 表
  • 表结构:

    CREATE TABLE background_task_config (
        id BIGINT PRIMARY KEY AUTO_INCREMENT,
        config_key VARCHAR(100) UNIQUE,   -- 配置键
        config_value VARCHAR(500),        -- 配置值
        description TEXT,                 -- 描述
        is_editable BOOLEAN,              -- 是否可编辑
        created_at DATETIME,
        updated_at DATETIME
    )
    

  • 预计工作量: 1小时
  • 相关文件: src/DB/Scripts/CreateBackgroundTaskConfigTable.sql

2.3 创建日志数据访问层

• Task: 为日志表创建Repository
  • IBackgroundTaskLogRepository 接口
  • BackgroundTaskLogRepository 实现
  • 关键方法:
    • AddLogAsync() - 添加日志
    • GetLogsAsync() - 查询日志
    • GetLatestExecutionAsync() - 获取最后一次执行信息
  • 预计工作量: 3小时
  • 相关文件:
    • src/DAL/Interfaces/IBackgroundTaskLogRepository.cs
    • src/DAL/Repositories/BackgroundTaskLogRepository.cs

2.4 创建配置数据访问层

• Task: 为配置表创建Repository
  • IBackgroundTaskConfigRepository 接口
  • BackgroundTaskConfigRepository 实现
  • 关键方法:
    • GetConfigAsync() - 获取配置
    • UpdateConfigAsync() - 更新配置
    • GetAllConfigsAsync() - 获取所有配置
  • 预计工作量: 2小时
  • 相关文件:
    • src/DAL/Interfaces/IBackgroundTaskConfigRepository.cs
    • src/DAL/Repositories/BackgroundTaskConfigRepository.cs

阶段3: 业务逻辑层 (优先级: ⭐⭐⭐)

3.1 任务执行日志记录

• Task: 在LabelPdfCacheService中添加日志记录
  • ProcessPendingTasksAsync() 方法添加日志记录
    • 记录开始时间
    • 记录处理数量
    • 记录成功/失败数
    • 记录执行耗时
    • 记录错误信息
  • 创建 LogExecutionAsync() 辅助方法
  • 预计工作量: 2小时
  • 相关文件: src/BLL/Services/LabelPdfCacheService.cs

3.2 配置管理服务

• Task: 创建配置管理服务
  • IBackgroundTaskConfigService 接口
  • BackgroundTaskConfigService 实现
  • 关键方法:
    • GetTaskIntervalAsync() - 获取执行间隔
    • GetBatchSizeAsync() - 获取批处理大小
    • GetRetryCountAsync() - 获取重试次数
    • GetCutoffDateAsync() - 获取时间截断日期
    • UpdateConfigAsync() - 更新配置
  • 配置缓存机制（内存缓存）
  • 预计工作量: 3小时
  • 相关文件:
    • src/BLL/Interfaces/IBackgroundTaskConfigService.cs
    • src/BLL/Services/BackgroundTaskConfigService.cs

3.3 任务执行统计服务

• Task: 创建执行统计服务
  • 关键方法:
    • GetExecutionStatsAsync() - 获取执行统计
    • GetRecentExecutionsAsync() - 获取最近执行记录
    • GetFailureRateAsync() - 获取失败率
    • GetAverageDurationAsync() - 获取平均耗时
  • 预计工作量: 2小时
  • 相关文件: src/BLL/Services/LabelPdfCacheService.cs

3.4 动态配置加载

• Task: 实现运行时动态配置
  • 定时刷新配置缓存（每分钟）
  • 配置变更事件通知
  • LabelPdfCacheBackgroundService 支持动态间隔
  • 预计工作量: 3小时
  • 相关文件:
    • src/CONTROLLER/BackgroundServices/LabelPdfCacheBackgroundService.cs
    • src/BLL/Services/BackgroundTaskConfigService.cs

阶段4: 控制器和API (优先级: ⭐⭐)

4.1 扩展LabelController

• Task: 添加定时任务管理相关API端点
  • 暂停/恢复/状态接口（✅ 已规划）
  • 配置管理接口（POST/GET）
  • 日志查询接口
  • 执行统计接口
  • 手动触发接口
  • 预计工作量: 4小时
  • 相关文件: src/CONTROLLER/Controllers/LabelController.cs

4.2 API文档更新

• Task: 更新API文档
  • 添加新接口文档
  • 请求/响应示例
  • 错误码说明
  • 使用场景说明
  • 预计工作量: 2小时
  • 相关文件: API_Documentation_zh.md

阶段5: 告警和监控 (优先级: ⭐⭐)

5.1 告警机制

• Task: 实现定时任务告警
  • 失败告警
  • 长时间未执行告警
  • 执行超时告警
  • 处理数量异常告警
  • 告警通知方式:
    • 邮件通知
    • 系统消息
    • Webhook回调
  • 预计工作量: 5小时
  • 相关文件:
    • src/BLL/Services/LabelPdfCacheService.cs
    • src/BLL/Services/AlertService.cs (新建)

5.2 性能监控

• Task: 添加性能指标监控
  • 执行耗时分析
  • 处理速度分析
  • 失败率分析
  • 资源使用率监控
  • 预计工作量: 3小时
  • 相关文件: src/BLL/Services/PerformanceMetricsService.cs (新建)

阶段6: 管理后台 (优先级: ⭐)

6.1 Dashboard设计

• Task: 创建定时任务管理Dashboard页面
  • 实时运行状态展示
  • 近期执行记录列表
  • 执行统计图表
  • 配置管理界面
  • 控制按钮（暂停/恢复/手动执行）
  • 预计工作量: 8小时（前端）
  • 相关文件: 前端项目

6.2 配置管理页面

• Task: 创建配置管理界面
  • 执行间隔配置
  • 批处理大小配置
  • 重试策略配置
  • 告警规则配置
  • 配置历史记录
  • 预计工作量: 6小时（前端）

6.3 日志查询页面

• Task: 创建日志查询界面
  • 日志列表
  • 高级筛选
  • 详情查看
  • 日志导出
  • 预计工作量: 4小时（前端）

阶段7: 测试和文档 (优先级: ⭐⭐)

7.1 单元测试

• Task: 编写定时任务相关单元测试
  • BackgroundTaskConfigService 测试
  • BackgroundTaskLogRepository 测试
  • LabelPdfCacheService 日志记录测试
  • 测试覆盖率 >= 80%
  • 预计工作量: 4小时
  • 相关文件: src/Tests/

7.2 集成测试

• Task: 编写集成测试
  • API接口测试
  • 数据库操作测试
  • 定时任务执行测试
  • 预计工作量: 3小时
  • 相关文件: src/Tests/

7.3 文档完善

• Task: 完善定时任务管理文档
  • 部署和配置文档
  • API使用指南
  • 故障排查指南
  • 性能优化指南
  • 预计工作量: 3小时
  • 相关文件: .trae/docs/BackgroundTasks/

7.4 用户手册

• Task: 编写最终用户手册
  • 功能说明
  • 操作流程
  • 常见问题解答
  • 预计工作量: 2小时

---

📊 工作量统计

阶段	任务数	预计工作量	优先级
阶段1: API层完善	3	9小时	⭐⭐⭐
阶段2: 数据存储层	4	7小时	⭐⭐⭐
阶段3: 业务逻辑层	4	10小时	⭐⭐⭐
阶段4: 控制器和API	2	6小时	⭐⭐
阶段5: 告警和监控	2	8小时	⭐⭐
阶段6: 管理后台	3	18小时	⭐
阶段7: 测试和文档	4	12小时	⭐⭐
总计	22	70小时	-

---

🔄 执行顺序

建议按以下顺序执行：

1. 第1周: 阶段2 (数据存储层) + 阶段1 (API层)
2. 第2周: 阶段3 (业务逻辑层)
3. 第3周: 阶段4 (控制器) + 阶段7 (测试)
4. 第4周: 阶段5 (告警监控)
5. 第5-6周: 阶段6 (管理后台) + 文档完善

---

🎓 技术栈

• 后端: ASP.NET Core, C#
• 数据库: MySQL, SqlSugar ORM
• 日志: Serilog, ILogger
• 缓存: 内存缓存
• 前端: Vue.js / React (待确定)
• 图表: ECharts / Chart.js

---

✅ 验收标准

功能完整性

• 所有API接口都已实现并测试通过
• 定时任务配置可动态修改
• 执行日志完整记录
• 告警机制正常工作

性能要求

• API响应时间 < 500ms
• 日志查询 < 2s (1000条数据)
• 内存占用 < 100MB

用户体验

• Dashboard直观易用
• 错误信息清晰易懂
• 支持中文界面

文档完整性

• API文档完整
• 用户手册完整
• 部署文档完整

---

🚀 后续计划

• 考虑微服务化部署
• 支持分布式定时任务
• 任务执行链
• 自适应调度算法
• 支持Cron表达式配置

---

📞 联系方式

项目经理: TBD
技术主管: TBD
前端负责人: TBD

---

文档创建日期: 2026-05-14
最后更新: 2026-05-14
版本: 1.0
状态: 📋 待审批