上传源代码版本

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

@@ -0,0 +1,406 @@
+# 定时任务管理模块 - 项目待办清单
+
+## 📋 项目概述
+
+**项目名称**: 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` 表
+  - 表结构:
+    ```sql
+    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` 表
+  - 表结构:
+    ```sql
+    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  
+**状态**: 📋 待审批