407 lines
12 KiB
Markdown
407 lines
12 KiB
Markdown
# 定时任务管理模块 - 项目待办清单
|
||
|
||
## 📋 项目概述
|
||
|
||
**项目名称**: 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
|
||
**状态**: 📋 待审批
|