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

## 📋 项目概述

**项目名称**: 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  
**状态**: 📋 待审批